Tasklets

Provides a tasklet decorator and related helpers.

Tasklets are a way to write concurrently running functions without threads. Tasklets are executed by an event loop and can suspend themselves blocking for I/O or some other operation using a yield statement. The notion of a blocking operation is abstracted into the Future class, but a tasklet may also yield an RPC in order to wait for that RPC to complete.

The @tasklet decorator wraps generator function so that when it is called, a Future is returned while the generator is executed by the event loop. Within the tasklet, any yield of a Future waits for and returns the Future’s result. For example:

@tasklet
def foo():
    a = yield <some Future>
    b = yield <another Future>
    return a + b

def main():
    f = foo()
    x = f.result()
    print x

Note that blocking until the Future’s result is available using result() is somewhat inefficient (though not vastly – it is not busy-waiting). In most cases such code should be rewritten as a tasklet instead:

@tasklet
def main_tasklet():
    f = foo()
    x = yield f
    print x

Calling a tasklet automatically schedules it with the event loop:

def main():
    f = main_tasklet()
    eventloop.run()  # Run until no tasklets left to do
    f.done()  # Returns True

google.cloud.ndb.tasklets.add_flow_exception(*args, **kwargs)

class google.cloud.ndb.tasklets.Future(info='Unknown')

Bases: object

Represents a task to be completed at an unspecified time in the future.

This is the abstract base class from which all NDB Future classes are derived. A future represents a task that is to be performed asynchronously with the current flow of program control.

Provides interface defined by concurrent.futures.Future as well as that of the legacy Google App Engine NDB Future class.

add_done_callback(callback)

Add a callback function to be run upon task completion. Will run immediately if task has already finished.

Parameters

callback (Callable) – The function to execute.

cancel()

Attempt to cancel the task for this future.

If the task has already completed, this call will do nothing. Otherwise, this will attempt to cancel whatever task this future is waiting on. There is no specific guarantee the underlying task will be cancelled.

cancelled()

Get whether the task for this future has been cancelled.

Returns

If this future’s task has been cancelled, otherwise

False.

Return type

True

check_success()

Check whether a future has completed without raising an exception.

This will wait for the future to finish its task and will then raise the future’s exception, if there is one, or else do nothing.

done()

Get whether future has finished its task.

Returns

True if task has finished, False otherwise.

Return type

bool

exception()

Get the exception for this future, if there is one.

If the task has not yet finished, this will block until the task has finished. When the task has finished, this will get the exception raised during the task, or None, if no exception was raised.

Returns

The exception, or None.

Return type

Union[Exception, None]

get_exception()

Get the exception for this future, if there is one.

If the task has not yet finished, this will block until the task has finished. When the task has finished, this will get the exception raised during the task, or None, if no exception was raised.

Returns

The exception, or None.

Return type

Union[Exception, None]

get_result()

Return the result of this future’s task.

If the task is finished, this will return immediately. Otherwise, this will block until a result is ready.

Returns

The result

Return type

Any

get_traceback()

Get the traceback for this future, if there is one.

Included for backwards compatibility with legacy NDB. If there is an exception for this future, this just returns the __traceback__ attribute of that exception.

Returns

The traceback, or None.

Return type

Union[types.TracebackType, None]

result()

Return the result of this future’s task.

If the task is finished, this will return immediately. Otherwise, this will block until a result is ready.

Returns

The result

Return type

Any

running()

Get whether future’s task is still running.

Returns

False if task has finished, True otherwise.

Return type

bool

set_exception(exception)

Set an exception for this future.

Signals that this future’s task has resulted in an exception. The future is considered done but has no result. Once the exception is set, calls to done() will return True, and calls to result() will raise the exception.

Should not be called from user code.

Parameters

exception (Exception) – The exception that was raised.

set_result(result)

Set the result for this future.

Signals that this future has completed its task and sets the result.

Should not be called from user code.

wait()

Wait for this future’s task to complete.

This future will be done and will have either a result or an exception after a call to this method.

static wait_all(futures)

Calls wait_all().

static wait_any(futures)

Calls wait_any().

google.cloud.ndb.tasklets.make_context(*args, **kwargs)

google.cloud.ndb.tasklets.make_default_context(*args, **kwargs)

class google.cloud.ndb.tasklets.QueueFuture(*args, **kwargs)

Bases: object

class google.cloud.ndb.tasklets.ReducingFuture(*args, **kwargs)

Bases: object

exception google.cloud.ndb.tasklets.Return

Bases: Exception

Return from a tasklet in Python 2.

In Python 2, generators may not return a value. In order to return a value from a tasklet, then, it is necessary to raise an instance of this exception with the return value:

from google.cloud import ndb

@ndb.tasklet
def get_some_stuff():
    future1 = get_something_async()
    future2 = get_something_else_async()
    thing1, thing2 = yield future1, future2
    result = compute_result(thing1, thing2)
    raise ndb.Return(result)

In Python 3, you can simply return the result:

@ndb.tasklet
def get_some_stuff():
    future1 = get_something_async()
    future2 = get_something_else_async()
    thing1, thing2 = yield future1, future2
    result = compute_result(thing1, thing2)
    return result

class google.cloud.ndb.tasklets.SerialQueueFuture(*args, **kwargs)

Bases: object

google.cloud.ndb.tasklets.set_context(*args, **kwargs)

google.cloud.ndb.tasklets.sleep(seconds)

Sleep some amount of time in a tasklet. .. rubric:: Example

..code-block:: python

yield tasklets.sleep(0.5) # Sleep for half a second.

Parameters

seconds (float) – Amount of time, in seconds, to sleep.

Returns

Future will be complete after seconds have elapsed.

Return type

Future

google.cloud.ndb.tasklets.synctasklet(wrapped)

A decorator to run a tasklet as a function when called.

Use this to wrap a request handler function that will be called by some web application framework (e.g. a Django view function or a webapp.RequestHandler.get method).

Parameters

wrapped (Callable) – The wrapped function.

google.cloud.ndb.tasklets.tasklet(wrapped)

A decorator to turn a function or method into a tasklet.

Calling a tasklet will return a Future instance which can be used to get the eventual return value of the tasklet.

For more information on tasklets and cooperative multitasking, see the main documentation.

Parameters

wrapped (Callable) – The wrapped function.

google.cloud.ndb.tasklets.toplevel(wrapped)

A synctasklet decorator that flushes any pending work.

Use of this decorator is largely unnecessary, as you should be using context() which also flushes pending work when exiting the context.

Parameters

wrapped (Callable) – The wrapped function.”

google.cloud.ndb.tasklets.wait_all(futures)

Wait for all of several futures to finish.

Parameters

futures (typing.Sequence[Future]) – The futures to wait on.

google.cloud.ndb.tasklets.wait_any(futures)

Wait for any of several futures to finish.

Parameters

futures (typing.Sequence[Future]) – The futures to wait on.

Returns

The first future to be found to have finished.

Return type

Future