tornado.stack_context — Exception handling across asynchronous callbacks¶

    The motivating examples are to eliminate the need for explicitasync_callback wrappers (as in tornado.web.RequestHandler), and toallow some additional context to be kept for logging.

    This is slightly magic, but it’s an extension of the idea that anexception handler is a kind of stack-local state and when that stackis suspended and resumed in a new context that state needs to bepreserved. shifts the burden of restoring that statefrom each call site (e.g. wrapping each AsyncHTTPClient callbackin async_callback) to the mechanisms that transfer control fromone context to another (e.g. itself, IOLoop,thread pools, etc).

    Example usage:

    Most applications shouldn’t have to work with directly.Here are a few rules of thumb for when it’s necessary:

    • If you’re writing an asynchronous library that doesn’t rely on astack_context-aware library like tornado.ioloop or (for example, if you’re writing a thread pool), usestack_context.wrap() before any asynchronous operations to capture thestack context from where the operation was started.
    • If you’re writing an asynchronous library that has some sharedresources (such as a connection pool), create those shared resourceswithin a with stack_context.NullContext(): block. This will preventStackContexts from leaking from one request to another.

    Note that the parameter is a callable that returns a contextmanager, not the context itself. That is, where for anon-transferable context manager you would say:

    1. with my_context():

    StackContext takes the function itself rather than its result:

    class tornado.stackcontext.ExceptionStackContext(_exception_handler)

    Specialization of StackContext for exception handling.

    The supplied exception_handler function will be called in theevent of an uncaught exception in this context. The semantics aresimilar to a try/finally clause, and intended use cases are to logan error, close a socket, or similar cleanup actions. Theexc_info triple (type, value, traceback) will be passed to theexception_handler function.

    If the exception handler returns true, the exception will beconsumed and will not be propagated to other exception handlers.

    class tornado.stack_context.NullContext

    Resets the .

    Useful when creating a shared resource on demand (e.g. anAsyncHTTPClient) where the stack that caused the creating isnot relevant to future operations.

    tornado.stackcontext.(_fn)

    Returns a callable object that will restore the current when executed.

    Use this whenever saving a callback to be executed later in adifferent execution context (either in a different thread orasynchronously in the same thread).

    tornado.stackcontext.run_with_stack_context(_context, func)[源代码]

    Run a coroutine func in the given StackContext.

    Example:

    1. .coroutine
      def incorrect():
          with StackContext(ctx):
    3. @gen.coroutine
      def correct():
          yield run_with_stack_context(StackContext(ctx), other_coroutine)

    3.1 新版功能.