ó úR‹_c@`s°dZddlmZmZmZddlmZddlmZddl m Z ddl m Z ddgZd efd „ƒYZeƒZdefd „ƒYZd „Zd S(sã Timeouts. Many functions in :mod:`gevent` have a *timeout* argument that allows limiting the time the function will block. When that is not available, the :class:`Timeout` class and :func:`with_timeout` function in this module add timeouts to arbitrary code. .. warning:: Timeouts can only work when the greenlet switches to the hub. If a blocking function is called or an intense calculation is ongoing during which no switches occur, :class:`Timeout` is powerless. i(tabsolute_importtprint_functiontdivision(t string_types(t_NONE(t getcurrent(tget_hub_noargstTimeoutt with_timeoutt _FakeTimercB`speZdZed„ƒZeZed„ƒZeZZd„Z d„Z e Z e Z Z d„Z d„ZRS(cC`stS(N(tFalse(tself((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pytpending(scC`sdS(sAlways returns NoneN((R ((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pytseconds.tcO`stdƒ‚dS(Ns$non-expiring timer cannot be started(tAssertionError(R targstkwargs((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pytstart4scC`sdS(N((R ((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pytstop8scC`s|S(N((R ((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyt __enter__?scC`sdS(N((R t_tt_vt_tb((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyt__exit__Bs((t__name__t __module__t __slots__tpropertyR tactiveR ttimert exceptionRRtcanceltcloseRR(((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyR s     cB`s¤eZdZd d eded„Zd„Zed d eed„ƒZ e d ed„ƒZ e d„ƒZ d„Zd„Zd „Zd „Zd „Zd „ZRS(sS Timeout(seconds=None, exception=None, ref=True, priority=-1) Raise *exception* in the current greenlet after *seconds* have elapsed:: timeout = Timeout(seconds, exception) timeout.start() try: ... # exception will be raised here, after *seconds* passed since start() call finally: timeout.close() .. note:: If the code that the timeout was protecting finishes executing before the timeout elapses, be sure to ``close`` the timeout so it is not unexpectedly raised in the future. Even if it is raised, it is a best practice to close it. This ``try/finally`` construct or a ``with`` statement is a recommended pattern. (If the timeout object will be started again, use ``cancel`` instead of ``close``; this is rare.) When *exception* is omitted or ``None``, the ``Timeout`` instance itself is raised:: >>> import gevent >>> gevent.Timeout(0.1).start() >>> gevent.sleep(0.2) #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): ... Timeout: 0.1 seconds If the *seconds* argument is not given or is ``None`` (e.g., ``Timeout()``), then the timeout will never expire and never raise *exception*. This is convenient for creating functions which take an optional timeout parameter of their own. (Note that this is **not** the same thing as a *seconds* value of ``0``.) :: def function(args, timeout=None): "A function with an optional timeout." timer = Timeout(timeout) with timer: ... .. caution:: A *seconds* value less than ``0.0`` (e.g., ``-1``) is poorly defined. In the future, support for negative values is likely to do the same thing as a value of ``None`` or ``0`` A *seconds* value of ``0`` requests that the event loop spin and poll for I/O; it will immediately expire as soon as control returns to the event loop. .. rubric:: Use As A Context Manager To simplify starting and canceling timeouts, the ``with`` statement can be used:: with gevent.Timeout(seconds, exception) as timeout: pass # ... code block ... This is equivalent to the try/finally block above with one additional feature: if *exception* is the literal ``False``, the timeout is still raised, but the context manager suppresses it, so the code outside the with-block won't see it. This is handy for adding a timeout to the functions that don't support a *timeout* parameter themselves:: data = None with gevent.Timeout(5, False): data = mysock.makefile().readline() if data is None: ... # 5 seconds passed without reading a line else: ... # a line was read within 5 seconds .. caution:: If ``readline()`` above catches and doesn't re-raise :exc:`BaseException` (for example, with a bare ``except:``), then your timeout will fail to function and control won't be returned to you when you expect. .. rubric:: Catching Timeouts When catching timeouts, keep in mind that the one you catch may not be the one you have set (a calling function may have set its own timeout); if you going to silence a timeout, always check that it's the instance you need:: timeout = Timeout(1) timeout.start() try: ... except Timeout as t: if t is not timeout: raise # not my timeout finally: timeout.close() .. versionchanged:: 1.1b2 If *seconds* is not given or is ``None``, no longer allocate a native timer object that will never be started. .. versionchanged:: 1.1 Add warning about negative *seconds* values. .. versionchanged:: 1.3a1 Timeout objects now have a :meth:`close` method that must be called when the timeout will no longer be used to properly clean up native resources. The ``with`` statement does this automatically. iÿÿÿÿcC`sntj|ƒ||_||_||_|dkr@t|_n*tƒj j|pUdd|d|ƒ|_dS(Ngtreftpriority( t BaseExceptiont__init__R Rt _one_shottNoneR Rtget_hubtloop(R R RR"R#R&((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyR%Çs      cC`s”|jrtd|ƒ‚n|jdkr/dS|jdks_|jtks_t|jtƒrh|}n |j}|jj t ƒj |dt ƒdS(sSchedule the timeout.s5%r is already started; to restart it, cancel it firstNtupdate( R RR R'RR t isinstanceRRRRtthrowtTrue(R tthrows((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyRÛs 0  cC`sRt|tƒr)|js%|jƒn|S|||d|d|ƒ}|jƒ|S(s·Create a started :class:`Timeout`. This is a shortcut, the exact action depends on *timeout*'s type: * If *timeout* is a :class:`Timeout`, then call its :meth:`start` method if it's not already begun. * Otherwise, create a new :class:`Timeout` instance, passing (*timeout*, *exception*) as arguments, then call its :meth:`start` method. Returns the :class:`Timeout` instance. R"R&(R+RR R(tclsttimeoutRR"R&((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyt start_newïs    cC`s)|dkrtStj|||dtƒS(NR&(R'R RR1R-(R0RR"((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyt_start_new_or_dummys cC`s|jjp|jjS(s.True if the timeout is scheduled to be raised.(RR R(R ((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyR scC`s'|jjƒ|jr#|jƒndS(sï If the timeout is pending, cancel it. Otherwise, do nothing. The timeout object can be :meth:`started ` again. If you will not start the timeout again, you should use :meth:`close` instead. N(RRR&R!(R ((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyR s  cC`s'|jjƒ|jjƒt|_dS(s‚ Close the timeout and free resources. The timer cannot be started again after this method has been used. N(RRR!R (R ((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyR!&s  cC`srt|ƒj}|jr!d}nd}|jdkr?d}n d|j}d|tt|ƒƒ|j||fS(Ns pendingRs exception=%rs<%s at %s seconds=%s%s%s>(ttypeRR RR'thextidR (R t classnameR R((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyt__repr__/s    cC`s…|jdkrdS|jdkr(dnd}|jdkrNd|j|fS|jtkrnd|j|fSd|j||jfS(s‘ >>> raise Timeout #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): ... Timeout Ritss %s second%ss%s second%s (silent)s%s second%s: %sN(R R'RR (R tsuffix((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyt__str__;scC`s|js|jƒn|S(s^ Start and return the timer. If the timer is already started, just return it. (R R(R ((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyRMs  cC`s-|jƒ||kr)|jtkr)tSdS(s© Stop the timer. .. versionchanged:: 1.3a1 The underlying native timer is also stopped. This object cannot be used again. N(R!RR R-(R ttyptvaluettb((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyRUs N(RRt__doc__R'R-R R%Rt classmethodR1t staticmethodR2RR R R!R7R:RR(((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyRHsz     cO`sƒ|jdtƒ}tj|dtƒ}zJy|||ŽSWn2tk ro}||kri|tk ri|S‚nXWd|jƒXdS(sZWrap a call to *function* with a timeout; if the called function fails to return before the timeout, cancel it and return a flag value, provided by *timeout_value* keyword argument. If timeout expires but *timeout_value* is not provided, raise :class:`Timeout`. Keyword argument *timeout_value* is not passed to *function*. t timeout_valueR&N(tpopRRR1R-R (R tfunctionRtkwdsRAR0tex((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyRbs  N(R>t __future__RRRtgevent._compatRt gevent._utilRtgreenletRtgevent._hub_localRR(t__all__tobjectR R$RR(((sG/var/www/syncserver/local/lib/python2.7/site-packages/gevent/timeout.pyts ' ÿ