gevent.event
– Notifications of multiple listeners¶
- class Event[source]¶
Bases:
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.Important
This object is for communicating among greenlets within the same thread only! Do not try to use it to communicate across threads.
An event object manages an internal flag that can be set to true with the
set()
method and reset to false with theclear()
method. Thewait()
method blocks until the flag is true; as soon as the flag is set to true, all greenlets that are currently blocked in a call towait()
will be scheduled to awaken.Note that the flag may be cleared and set many times before any individual greenlet runs; all the greenlet can know for sure is that the flag was set at least once while it was waiting. If the greenlet cares whether the flag is still set, it must check with
ready()
and possibly call back intowait()
again.Note
The exact order and timing in which waiting greenlets are awakened is not determined.
Once the event is set, other greenlets may run before any waiting greenlets are awakened.
While the code here will awaken greenlets in the order in which they waited, each such greenlet that runs may in turn cause other greenlets to run.
These details may change in the future.
Changed in version 1.5a3: Waiting greenlets are now awakened in the order in which they waited.
Changed in version 1.5a3: The low-level
rawlink
method (most users won’t use this) now automatically unlinks waiters before calling them.Changed in version 20.5.1: Callers to
wait
that find the event already set will now run after any other waiters that had to block. See issue #1520.- is_set()[source]¶
- isSet()[source]¶
- ready()[source]¶
Return true if and only if the internal flag is true.
- clear()[source]¶
Reset the internal flag to false.
Subsequently, threads calling
wait()
will block untilset()
is called to set the internal flag to true again.
- set()[source]¶
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 (untilclear()
is called).
- wait(timeout=None)[source]¶
Block until this object is
ready()
.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 expires.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[source]¶
Bases:
AbstractLinkable
A one-time event that stores a value or an exception.
Like
Event
it wakes up all the waiters whenset()
orset_exception()
is called. Waiters may receive the passed value or exception by callingget()
instead ofwait()
. AnAsyncResult
instance cannot be reset.Important
This object is for communicating among greenlets within the same thread only! Do not try to use it to communicate across threads.
To pass a value call
set()
. Calls toget()
(those that are currently blocking as well as those made in the future) will return the value:>>> from gevent.event import AsyncResult >>> result = AsyncResult() >>> result.set(100) >>> result.get() 100
To pass an exception call
set_exception()
. This will causeget()
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 aslink()
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.Changed in version 1.5a3: Waiting greenlets are now awakened in the order in which they waited.
Changed in version 1.5a3: The low-level
rawlink
method (most users won’t use this) now automatically unlinks waiters before calling them.- get(block=True, timeout=None)[source]¶
Return the stored value or raise the exception.
If this instance already holds a value or an exception, return or raise it immediately. Otherwise, block until another greenlet calls
set()
orset_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 aTimeout
exception.
- get_nowait()[source]¶
Return the value or raise the exception without blocking.
If this object is not yet
ready
, raisegevent.Timeout
immediately.
- set(value=None)[source]¶
Store the value and wake up any waiters.
All greenlets blocking on
get()
orwait()
are awakened. Subsequent calls towait()
andget()
will not block at all.
- set_exception(exception, exc_info=None)[source]¶
Store the exception and wake up any waiters.
All greenlets blocking on
get()
orwait()
are awakened. Subsequent calls towait()
andget()
will not block at all.- Parameters:
exc_info (tuple) – If given, a standard three-tuple of type, value,
traceback
as returned bysys.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()
orwait()
are awakened. Subsequent calls towait()
andget()
will not block at all.
- wait(timeout=None)[source]¶
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()
orset_exception()
(at which point either the value orNone
will be returned, respectively), or until the optional timeout expires (at which pointNone
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).
- property exc_info¶
The three-tuple of exception information if
set_exception()
was called.
- property exception¶
Holds the exception instance passed to
set_exception()
ifset_exception()
was called. OtherwiseNone
.