Cooperative Timeouts Using gevent.Timeout

Cooperative timeouts can be implemented with the gevent.Timeout class, and the helper function gevent.with_timeout().

class Timeout(seconds=None, exception=None, ref=True, priority=-1)

Bases: BaseException

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()

Warning

You must always call close on a Timeout object you have created, whether or not the code that the timeout was protecting finishes executing before the timeout elapses (whether or not the Timeout exception is raised) This try/finally construct or a with statement is a good pattern. (If the timeout object will be started again, use cancel instead of close; this is rare. You must still close it when you are done.)

When exception is omitted or None, the Timeout instance itself is raised:

>>> import gevent
>>> gevent.Timeout(0.1).start()
>>> gevent.sleep(0.2)  
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.

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 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.

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()

Changed in version 1.1b2: If seconds is not given or is None, no longer allocate a native timer object that will never be started.

Changed in version 1.1: Add warning about negative seconds values.

Changed in version 1.3a1: Timeout objects now have a 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.

__enter__()

Start and return the timer. If the timer is already started, just return it.

__exit__(typ, value, tb)

Stop the timer.

Changed in version 1.3a1: The underlying native timer is also stopped. This object cannot be used again.

cancel()

If the timeout is pending, cancel it. Otherwise, do nothing.

The timeout object can be started again. If you will not start the timeout again, you should use close() instead.

close()

Close the timeout and free resources. The timer cannot be started again after this method has been used.

start()

Schedule the timeout.

classmethod start_new(timeout=None, exception=None, ref=True, _one_shot=False)

Create a started Timeout.

This is a shortcut, the exact action depends on timeout’s type:

• If timeout is a Timeout, then call its start() method if it’s not already begun.

• Otherwise, create a new Timeout instance, passing (timeout, exception) as arguments, then call its start() method.

Returns the Timeout instance.

property pending

True if the timeout is scheduled to be raised.

Next page: gevent.socket – Cooperative low-level networking interface