gevent.event – Notifications of multiple listeners

class Event

Bases: gevent.event._AbstractLinkable

A synchronization primitive that allows one greenlet to wake up one or more others. It has the same interface as threading.Event but works across greenlets.

An event object manages an internal flag that can be set to true with the set() method and reset to false with the clear() method. The wait() method blocks until the flag is true.

Note

The order and timing in which waiting greenlets are awakened is not determined. As an implementation note, in gevent 1.1 and 1.0, waiting greenlets are awakened in a undetermined order sometime after the current greenlet yields to the event loop. Other greenlets (those not waiting to be awakened) may run between the current greenlet yielding and the waiting greenlets being awakened. These details may change in the future.

is_set()
isSet()
ready()

Return true if and only if the internal flag is true.

clear()

Reset the internal flag to false.

Subsequently, threads calling wait() will block until set() is called to set the internal flag to true again.

isSet()

Return true if and only if the internal flag is true.

is_set()

Return true if and only if the internal flag is true.

ready()

Return true if and only if the internal flag is true.

set()

Set the internal flag to true.

All greenlets waiting for it to become true are awakened in some order at some time in the future. Greenlets that call wait() once the flag is true will not block at all (until clear() is called).

wait(timeout=None)

Block until the internal flag is true.

If the internal flag is true on entry, return immediately. Otherwise, block until another thread (greenlet) calls set() to set the flag to true, or until the optional timeout occurs.

When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof).

Returns:This method returns true if and only if the internal flag has been set to true, either before the wait call or after the wait starts, so it will always return True except if a timeout is given and the operation times out.

Changed in version 1.1: The return value represents the flag during the elapsed wait, not just after it elapses. This solves a race condition if one greenlet sets and then clears the flag without switching, while other greenlets are waiting. When the waiters wake up, this will return True; previously, they would still wake up, but the return value would be False. This is most noticeable when the timeout is present.

class AsyncResult

Bases: gevent.event._AbstractLinkable

A one-time event that stores a value or an exception.

Like Event it wakes up all the waiters when set() or set_exception() is called. Waiters may receive the passed value or exception by calling get() instead of wait(). An AsyncResult instance cannot be reset.

To pass a value call set(). Calls to get() (those that are currently blocking as well as those made in the future) will return the value:

>>> result = AsyncResult()
>>> result.set(100)
>>> result.get()
100

To pass an exception call set_exception(). This will cause get() to raise that exception:

>>> result = AsyncResult()
>>> result.set_exception(RuntimeError('failure'))
>>> result.get()
Traceback (most recent call last):
 ...
RuntimeError: failure

AsyncResult implements __call__() and thus can be used as link() target:

>>> import gevent
>>> result = AsyncResult()
>>> gevent.spawn(lambda : 1/0).link(result)
>>> try:
...     result.get()
... except ZeroDivisionError:
...     print('ZeroDivisionError')
ZeroDivisionError

Note

The order and timing in which waiting greenlets are awakened is not determined. As an implementation note, in gevent 1.1 and 1.0, waiting greenlets are awakened in a undetermined order sometime after the current greenlet yields to the event loop. Other greenlets (those not waiting to be awakened) may run between the current greenlet yielding and the waiting greenlets being awakened. These details may change in the future.

Changed in version 1.1: The exact order in which waiting greenlets are awakened is not the same as in 1.0.

Changed in version 1.1: Callbacks linked to this object are required to be hashable, and duplicates are merged.

cancel()
cancelled()
done()
exc_info

The three-tuple of exception information if set_exception() was called.

exception

Holds the exception instance passed to set_exception() if set_exception() was called. Otherwise None.

get(block=True, timeout=None)

Return the stored value or raise the exception.

If this instance already holds a value or an exception, return or raise it immediatelly. Otherwise, block until another greenlet calls set() or set_exception() or until the optional timeout occurs.

When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). If the timeout elapses, the Timeout exception will be raised.

Parameters:block (bool) – If set to False and this instance is not ready, immediately raise a Timeout exception.
get_nowait()

Return the value or raise the exception without blocking.

If this object is not yet ready, raise gevent.Timeout immediately.

ready()

Return true if and only if it holds a value or an exception

result(timeout=None)
set(value=None)

Store the value and wake up any waiters.

All greenlets blocking on get() or wait() are awakened. Subsequent calls to wait() and get() will not block at all.

set_exception(exception, exc_info=None)

Store the exception and wake up any waiters.

All greenlets blocking on get() or wait() are awakened. Subsequent calls to wait() and get() will not block at all.

Parameters:exc_info (tuple) – If given, a standard three-tuple of type, value, traceback as returned by sys.exc_info(). This will be used when the exception is re-raised to propagate the correct traceback.
set_result(value=None)

Store the value and wake up any waiters.

All greenlets blocking on get() or wait() are awakened. Subsequent calls to wait() and get() will not block at all.

successful()

Return true if and only if it is ready and holds a value

value

Holds the value passed to set() if set() was called. Otherwise, None

wait(timeout=None)

Block until the instance is ready.

If this instance already holds a value, it is returned immediately. If this instance already holds an exception, None is returned immediately.

Otherwise, block until another greenlet calls set() or set_exception() (at which point either the value or None will be returned, respectively), or until the optional timeout expires (at which point None will also be returned).

When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof).

Note

If a timeout is given and expires, None will be returned (no timeout exception will be raised).

Next page: gevent.queue – Synchronized queues