Efo3dZddlmZmZmZmZddlZddlZddlm Z Gdde Z Gdd ejZ e ZGd d eZGd d eZGddeZdZdZdZdZy)a `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`. )absolute_importdivisionprint_functionwith_statementN)raise_exc_infoc eZdZy)StackContextInconsistentErrorN)__name__ __module__ __qualname__I/usr/lib/python3/dist-packages/zmq/eventloop/minitornado/stack_context.pyr r Nsrr ceZdZdZy)_Statec&tdf|_yN)tuplecontextsselfs r__init__z_State.__init__Ss$ rN)r r r rrrrrrRs(rrc4eZdZdZdZdZdZdZdZdZ y) StackContextaEstablishes 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. c.||_g|_d|_yNT)context_factoryractive)rrs rrzStackContext.__init__ls.  rcd|_yNFrrs r _deactivatezStackContext._deactivateq  rcz|j}|jj||jyr)rrappend __enter__)rcontexts renterzStackContext.enterus.&&( W%rc^|jj}|j|||yr)rpop__exit__)rtypevalue tracebackr(s rexitzStackContext.exitzs&--##%ui0rctj|_|jd|fz|f|_|jt_ |j |j S#|jt_xYwNr)_stater old_contexts new_contextsr)r#rs rr'zStackContext.__enter__sm"OO!..q1TG;TB++  JJL   "//FO s A""A:cJ |j|||tj}|jt_||jur t dd|_y#tj}|jt_||jur t dd|_wxYwNzWstack_context inconsistency (may be caused by yield within a "with StackContext" block))r0r3rr4r5r rr-r.r/final_contextss rr,zStackContext.__exit__s % IIdE9 -#__N"//FOT%6%663:;; !%D $__N"//FOT%6%663:;; !%D s AAB"N) r r r __doc__rr#r)r0r'r,rrrrrXs%&  1  %rrc.eZdZdZdZdZdZdZdZy)ExceptionStackContextaASpecialization 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. c ||_d|_yr)exception_handlerr)rr>s rrzExceptionStackContext.__init__s!2 rcd|_yr!r"rs rr#z!ExceptionStackContext._deactivater$rc.||j|||Syr)r>rr-r.r/s rr0zExceptionStackContext.exits"  ))$yA A rctj|_|jd|f|_|jt_|jSr2)r3rr4r5r#rs rr'zExceptionStackContext.__enter__s?"OO!..q148++rc |X|j|||tj}|jt_||jur t dd|_S tj}|jt_||jur t dd|_y#tj}|jt_||jur t dd|_wxYwr7)r>r3rr4r5r r8s rr,zExceptionStackContext.__exit__s %--dE9E#__N"//FOT%6%663:;; !%D  $__N"//FOT%6%663:;; !%D $__N"//FOT%6%663:;; !%D s B##AC*N) r r r r:rr#r0r'r,rrrr<r<s! B %rr<ceZdZdZdZdZy) NullContextzResets 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. cXtj|_tdft_yr)r3rr4rrs rr'zNullContext.__enter__s"OO 7D/rc.|jt_yr)r4r3rrAs rr,zNullContext.__exit__s++rN)r r r r:r'r,rrrrErEs *,rrEc\t|dDcgc]}|js|c}}|d}|*|js|jd}| |js|}|F|jd}|0|jrn#|j|_|jd}|0|}|F||fScc}w)z*Remove deactivated handlers from the chainrr)rrr4)rhstack_contextsheadctxparents r_remove_deactivatedrNsx{?!ahhA?@N A;D  4;;  #  4;; C /!!!$ }}%22C ((+F   / D !!)@s B)B)c tdrStjgddsddsfd}d|_|Sfd}d|_|S)a 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). _wrappedrrc tj}dt_|i||t_S#t_wxYwr2)r3r)argskwargs current_state cap_contextsfns r null_wrapperzwrap..null_wrappers8 0 & ".q/4*6*"/-s %4 ATcd} tj}t dx d<}|t_d}d}d}|d}|D]} | j|dz }|  |i|}| t||}n5|dkDr |dz}||} | j||dkDr d}| t||}|dk7r t||t_|S#t j }| j d}YxYw#t j }|d}YxYw#t j }| j d}YxYw#t_wxYw)NrNNNr) r3rrNr)sysexc_infor4_handle_exceptionr0r) rRrSretrTrexctoplast_ctxstackncrUrVs rwrappedzwrap..wrappeds> ,"OOM*=\!_)M MLOh'FO%CCHQKE ,,GGIMH ,{&d-f-C 'S1lMHhA lC?+C5C((s#+FO Q,,,.C..+C &,,.C"1+C!llnnnQ/,FOsY>D;CD;C1&D;DD; D;%C.,D;1D D;%D86D;; E)hasattrr3rrP)rVrWrdrUs` @rwraprfsh zWR, OO$L ?1 l1oa&8 0!% AFG Nrc|$ |j|rd}|jd}|$|S#tj}Y,xYw)NrYr)r0rZr[r4)tailr^s rr\r\`sR   !tyy#(  #   J  !,,.Cs )Ac@|5|cdddS#1swYyxYw)aRun 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 Nr)r(funcs rrun_with_stack_contextrkms!, vs)r: __future__rrrrrZ threadingutilr Exceptionr localrr3objectrr<rErNrfr\rkrrrrrs"3jQP   I (Y__( I%6I%X-%F-%` ,& ,"4`F r