eventlet/doc/modules/timeout.rst

   1 :mod:`timeout` -- Universal Timeouts
   2 ========================================
   3
   4 .. class:: eventlet.timeout.Timeout
   5
   6     Raises *exception* in the current greenthread after *timeout* seconds::
   7
   8         timeout = Timeout(seconds, exception)
   9         try:
  10             ... # execution here is limited by timeout
  11         finally:
  12             timeout.cancel()
  13
  14     When *exception* is omitted or ``None``, the :class:`Timeout` instance
  15     itself is raised:
  16
  17         >>> Timeout(0.1)
  18         >>> eventlet.sleep(0.2)
  19         Traceback (most recent call last):
  20          ...
  21         Timeout: 0.1 seconds
  22
  23     You can use the  ``with`` statement for additional convenience::
  24
  25         with Timeout(seconds, exception) as timeout:
  26             pass # ... code block ...
  27
  28     This is equivalent to the try/finally block in the first example.
  29
  30     There is an additional feature when using the ``with`` statement: if
  31     *exception* is ``False``, the timeout is still raised, but the with
  32     statement suppresses it, so the code outside the with-block won't see it::
  33
  34         data = None
  35         with Timeout(5, False):
  36             data = mysock.makefile().readline()
  37         if data is None:
  38             ... # 5 seconds passed without reading a line
  39         else:
  40             ... # a line was read within 5 seconds
  41
  42     As a very special case, if *seconds* is None, the timer is not scheduled,
  43     and is only useful if you're planning to raise it directly.
  44
  45     There are two Timeout caveats to be aware of:
  46
  47     * If the code block in the try/finally or with-block never cooperatively yields, the timeout cannot be raised.  In Eventlet, this should rarely be a problem, but be aware that you cannot time out CPU-only operations with this class.
  48     * If the code block catches and doesn't re-raise :class:`BaseException`  (for example, with ``except:``), then it will catch the Timeout exception, and might not abort as intended.
  49
  50     When catching timeouts, keep in mind that the one you catch may not be the
  51     one you have set; if you going to silence a timeout, always check that it's
  52     the same instance that you set::
  53
  54         timeout = Timeout(1)
  55         try:
  56             ...
  57         except Timeout as t:
  58             if t is not timeout:
  59                 raise # not my timeout
  60
  61     .. automethod:: cancel
  62     .. autoattribute:: pending
  63
  64
  65 .. function:: eventlet.timeout.with_timeout(seconds, function, *args, **kwds)
  66
  67     Wrap a call to some (yielding) function with a timeout; if the called
  68     function fails to return before the timeout, cancel it and return a flag
  69     value.
  70
  71     :param seconds: seconds before timeout occurs
  72     :type seconds: int or float
  73     :param func: the callable to execute with a timeout; it must cooperatively yield, or else the timeout will not be able to trigger
  74     :param \*args: positional arguments to pass to *func*
  75     :param \*\*kwds: keyword arguments to pass to *func*
  76     :param timeout_value: value to return if timeout occurs (by default raises
  77       :class:`Timeout`)
  78
  79     :rtype: Value returned by *func* if *func* returns before *seconds*, else
  80       *timeout_value* if provided, else raises :class:`Timeout`.
  81
  82     :exception Timeout: if *func* times out and no ``timeout_value`` has
  83       been provided.
  84     :exception: Any exception raised by *func*
  85
  86     Example::
  87
  88         data = with_timeout(30, urllib2.open, 'http://www.google.com/', timeout_value="")
  89
  90     Here *data* is either the result of the ``get()`` call, or the empty string
  91     if it took too long to return.  Any exception raised by the ``get()`` call
  92     is passed through to the caller.