tornado.concurrent — Work with threads and futures¶

Utilities for working with threads and Futures.

Futures are a pattern for concurrent programming introduced inPython 3.2 in the concurrent.futures package. This package definesa mostly-compatible Future class designed for use from coroutines,as well as some utility functions for interacting with theconcurrent.futures package.

class tornado.concurrent.Future[源代码]¶

Placeholder for an asynchronous result.

A Future encapsulates the result of an asynchronousoperation. In synchronous applications Futures are usedto wait for the result from a thread or process pool; inTornado they are normally used with IOLoop.add_future or byyielding them in a gen.coroutine.

tornado.concurrent.Future is similar toconcurrent.futures.Future, but not thread-safe (and thereforefaster for use with single-threaded event loops).

In addition to exception and set_exception, methods exc_infoand set_exc_info are supported to capture tracebacks in Python 2.The traceback is automatically available in Python 3, but in thePython 2 futures backport this information is discarded.This functionality was previously available in a separate classTracebackFuture, which is now a deprecated alias for this class.


在 4.0 版更改: tornado.concurrent.Future is always a thread-unsafe Futurewith support for the exc_info methods. Previously it wouldbe an alias for the thread-safe concurrent.futures.Futureif that package was available and fall back to the thread-unsafeimplementation if it was not.



在 4.1 版更改: If a Future contains an error but that error is never observed(by calling result(), exception(), or exc_info()),a stack trace will be logged when the Future is garbage collected.This normally indicates an error in the application, but in caseswhere it results in undesired logging it may be necessary tosuppress the logging by ensuring that the exception is observed:f.add_done_callback(lambda f: f.exception()).

Consumer methods¶

Future.result(timeout=None)[源代码]¶

If the operation succeeded, return its result. If it failed,re-raise its exception.

This method takes a timeout argument for compatibility withconcurrent.futures.Future but it is an error to call itbefore the Future is done, so the timeout is never used.

Future.exception(timeout=None)[源代码]¶

If the operation raised an exception, return the Exceptionobject. Otherwise returns None.

This method takes a timeout argument for compatibility withconcurrent.futures.Future but it is an error to call itbefore the Future is done, so the timeout is never used.

Future.excinfo()[源代码]¶

Returns a tuple in the same format as sys.exc_info or None.


4.0 新版功能.

Future.add_done_callback(_fn)[源代码]¶

Attaches the given callback to the Future.

It will be invoked with the Future as its argument when the Futurehas finished running and its result is available. In Tornadoconsider using IOLoop.add_future instead of callingadd_done_callback directly.

Future.done()[源代码]¶

Returns True if the future has finished running.

Future.running()[源代码]¶

Returns True if this operation is currently running.

Future.cancel()[源代码]¶

Cancel the operation, if possible.

Tornado Futures do not support cancellation, so this method alwaysreturns False.

Future.cancelled()[源代码]¶

Returns True if the operation has been cancelled.

Tornado Futures do not support cancellation, so this methodalways returns False.

Producer methods¶

Future.setresult(_result)[源代码]¶

Sets the result of a Future.

It is undefined to call any of the set methods more than onceon the same object.

Future.setexception(_exception)[源代码]¶

Sets the exception of a Future.

Future.setexc_info(_exc_info)[源代码]¶

Sets the exception information of a Future.

Preserves tracebacks on Python 2.


4.0 新版功能.

tornado.concurrent.FUTURES¶

Future 的别名

tornado.concurrent.runon_executor(args, *kwargs)[源代码]¶

Decorator to run a synchronous method asynchronously on an executor.

The decorated method may be called with a callback keywordargument and returns a future.

The IOLoop and executor to be used are determined by the io_loopand executor attributes of self. To use different attributes,pass keyword arguments to the decorator:

@run_on_executor(executor='_thread_pool')
def foo(self):
    pass

在 4.2 版更改: Added keyword arguments to use alternative attributes.

tornado.concurrent.return_future(_f)[源代码]¶

Decorator to make a function that returns via callback return aFuture.

The wrapped function should take a callback keyword argumentand invoke it with one argument when it has finished. To signal failure,the function can simply raise an exception (which will becaptured by the StackContext and passed along to the Future).

From the caller’s perspective, the callback argument is optional.If one is given, it will be invoked when the function is completewith Future.result() as an argument. If the function fails, thecallback will not be run and an exception will be raised into thesurrounding StackContext.

If no callback is given, the caller should use the Future towait for the function to complete (perhaps by yielding it in agen.engine function, or passing it to IOLoop.add_future).

Usage:

@returnfuture
def future_func(arg1, arg2, callback):
    # Do stuff (possibly asynchronous)
    callback(result)

@gen.engine
def caller(callback):
    yield future_func(arg1, arg2)
    callback()

Note that @return_future and @gen.engine can be applied to thesame function, provided @return_future appears first. However,consider using @gen.coroutine instead of this combination.

tornado.concurrent.chain_future(_a, b)[源代码]¶

Chain two futures together so that when one completes, so does the other.

The result (success or failure) of a will be copied to b, unlessb has already been completed or cancelled by the time a finishes.

原文:

https://tornado-zh-cn.readthedocs.io/zh_CN/latest/concurrent.html