L]c@sdZddlmZmZmZmZddlZddlZddlm Z de fdYZ dej fd YZ e Zd efd YZd efd YZdefdYZdZdZdZdZdS(s `StackContext` allows applications to maintain threadlocal-like state that follows execution as it moves to other execution contexts. The motivating examples are to eliminate the need for explicit ``async_callback`` wrappers (as in `tornado.web.RequestHandler`), and to allow some additional context to be kept for logging. This is slightly magic, but it's an extension of the idea that an exception handler is a kind of stack-local state and when that stack is suspended and resumed in a new context that state needs to be preserved. `StackContext` shifts the burden of restoring that state from each call site (e.g. wrapping each `.AsyncHTTPClient` callback in ``async_callback``) to the mechanisms that transfer control from one context to another (e.g. `.AsyncHTTPClient` itself, `.IOLoop`, thread pools, etc). Example usage:: @contextlib.contextmanager def die_on_error(): try: yield except Exception: logging.error("exception in asynchronous operation",exc_info=True) sys.exit(1) with StackContext(die_on_error): # Any exception thrown here *or in callback and its descendants* # will cause the process to exit instead of spinning endlessly # in the ioloop. http_client.fetch(url, callback) ioloop.start() Most applications shouldn't have to work with `StackContext` 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 a stack_context-aware library like `tornado.ioloop` or `tornado.iostream` (for example, if you're writing a thread pool), use `.stack_context.wrap()` before any asynchronous operations to capture the stack context from where the operation was started. * If you're writing an asynchronous library that has some shared resources (such as a connection pool), create those shared resources within a ``with stack_context.NullContext():`` block. This will prevent ``StackContexts`` from leaking from one request to another. * If you want to write something like an exception handler that will persist across asynchronous calls, create a new `StackContext` (or `ExceptionStackContext`), and make your asynchronous calls in a ``with`` block that references your `StackContext`. i(tabsolute_importtdivisiontprint_functiontwith_statementNi(traise_exc_infotStackContextInconsistentErrorcBseZRS((t__name__t __module__(((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRNst_StatecBseZdZRS(cCstdf|_dS(N(ttupletNonetcontexts(tself((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyt__init__Ss(RRR (((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRRst StackContextcBsDeZdZdZdZdZdZdZdZRS(sEstablishes the given context as a StackContext that will be transferred. Note that the parameter is a callable that returns a context manager, not the context itself. That is, where for a non-transferable context manager you would say:: with my_context(): StackContext takes the function itself rather than its result:: with StackContext(my_context): The result of ``with StackContext() as cb:`` is a deactivation callback. Run this callback when the StackContext is no longer needed to ensure that it is not propagated any further (note that deactivating a context does not affect any instances of that context that are currently pending). This is an advanced feature and not necessary in most applications. cCs||_g|_t|_dS(N(tcontext_factoryR tTruetactive(R R((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyR ls  cCs t|_dS(N(tFalseR(R ((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyt _deactivateqscCs*|j}|jj||jdS(N(RR tappendt __enter__(R tcontext((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pytenterus cCs&|jj}|j|||dS(N(R tpopt__exit__(R ttypetvaluet tracebackR((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pytexitzscCsctj|_|jd|f|f|_|jt_y|jWn|jt_nX|jS(Ni(t_stateR t old_contextst new_contextsRR(R ((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRs   cCs[z|j|||Wdtj}|jt_||jk rMtdnd|_XdS(NsWstack_context inconsistency (may be caused by yield within a "with StackContext" block)(RRR RR RR (R RRRtfinal_contexts((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRs   ( RRt__doc__R RRRRR(((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRXs     tExceptionStackContextcBs;eZdZdZdZdZdZdZRS(sASpecialization of StackContext for exception handling. The supplied ``exception_handler`` function will be called in the event of an uncaught exception in this context. The semantics are similar to a try/finally clause, and intended use cases are to log an error, close a socket, or similar cleanup actions. The ``exc_info`` triple ``(type, value, traceback)`` will be passed to the exception_handler function. If the exception handler returns true, the exception will be consumed and will not be propagated to other exception handlers. cCs||_t|_dS(N(texception_handlerRR(R R$((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyR s cCs t|_dS(N(RR(R ((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRscCs#|dk r|j|||SdS(N(R R$(R RRR((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRs cCs5tj|_|jd|f|_|jt_|jS(Ni(RR RR R(R ((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRs  cCsgz#|dk r"|j|||SWdtj}|jt_||jk rYtdnd|_XdS(NsWstack_context inconsistency (may be caused by yield within a "with StackContext" block)(R R$RR RR R(R RRRR!((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRs    (RRR"R RRRR(((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyR#s      t NullContextcBs eZdZdZdZRS(sResets the `StackContext`. Useful when creating a shared resource on demand (e.g. an `.AsyncHTTPClient`) where the stack that caused the creating is not relevant to future operations. cCs"tj|_tdft_dS(N(RR RR R (R ((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRs cCs|jt_dS(N(RRR (R RRR((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyRs(RRR"RR(((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyR%s cCstg|dD]}|jr|^q}|d}x'|dk r_|j r_|jd}q9W|}x\|dk r|jd}x6|dk r|jrPn|j|_|jd}qW|}qiW||fS(s*Remove deactivated handlers from the chainiiN(R RR R(R thtstack_contextstheadtctxtparent((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyt_remove_deactivateds,     csdkstdrStjgdd rhdd rhfd}t|_|Sfd}t|_|S(s Returns a callable object that will restore the current `StackContext` when executed. Use this whenever saving a callback to be executed later in a different execution context (either in a different thread or asynchronously in the same thread). t_wrappediics8z'tj}dt_||SWd|t_XdS(Ni(RR (targstkwargst current_state(t cap_contextstfn(sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyt null_wrappers   c sd}ztj}tdd<}|t_d}d}d}|d}xI|D]A} y| j|d7}WqVtj}| jd}qVXqVW|dkry||}Wqtj}|d}qXn|dk rt||}nx_|dkrV|d8}||} y| j |Wqtj}| jd}PqXqWd}|dk r{t||}n|dkrt |nWd|t_X|S(Nii(NNN(NNN( R RR R+Rtsystexc_infoRt_handle_exceptionRR( R-R.tretR/R texcttoptlast_ctxtstacktntc(R0R1(sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pytwrappedsP                 N(R thasattrRR RR,(R1R2R=((R0R1sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pytwraps   C cCsVxO|dk rQy|j|r*d}nWntj}nX|jd}qW|S(Ni(NNN(R RR3R4R(ttailR7((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pyR5`s cCs| |SWdQXdS(sRun a coroutine ``func`` in the given `StackContext`. It is not safe to have a ``yield`` statement within a ``with StackContext`` block, so it is difficult to use stack context with `.gen.coroutine`. This helper function runs the function in the correct context while keeping the ``yield`` and ``with`` statements syntactically separate. Example:: @gen.coroutine def incorrect(): with StackContext(ctx): # ERROR: this will raise StackContextInconsistentError yield other_coroutine() @gen.coroutine def correct(): yield run_with_stack_context(StackContext(ctx), other_coroutine) .. versionadded:: 3.1 N((Rtfunc((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pytrun_with_stack_contextms(R"t __future__RRRRR3t threadingtutilRt ExceptionRtlocalRRtobjectRR#R%R+R?R5RB(((sFlib/python2.7/site-packages/zmq/eventloop/minitornado/stack_context.pytDs"   L0  c