The hub is a special greenlet created automatically to run the event loop.
The current hub can be retrieved with get_hub
.
get_hub
(*args, **kwargs)[source]¶Return the hub for the current thread.
If a hub does not exist in the current thread, a new one is
created of the type returned by get_hub_class()
.
Deprecated since version 1.3b1: The *args
and **kwargs
arguments are deprecated. They were
only used when the hub was created, and so were non-deterministic—to be
sure they were used, all callers had to pass them, or they were order-dependent.
Use set_hub
instead.
Hub
(loop=None, default=None)[source]¶A greenlet that runs the event loop.
It is created automatically by get_hub()
.
Switching
Every time this greenlet (i.e., the event loop) is switched to,
if the current greenlet has a switch_out
method, it will be
called. This allows a greenlet to take some cleanup actions before
yielding control. This method should not call any gevent blocking
functions.
wait
(watcher)¶Wait until the watcher (which must not be started) is ready.
The current greenlet will be unscheduled during this time.
cancel_wait
(watcher, error, close_watcher=False)¶Cancel an in-progress call to wait()
by throwing the given error
in the waiting greenlet.
Changed in version 1.3a1: Added the close_watcher parameter. If true, the watcher will be closed after the exception is thrown. The watcher should then be discarded. Closing the watcher is important to release native resources.
Changed in version 1.3a2: Allow the watcher to be None
. No action is taken in that case.
loop
¶the event loop object (`ILoop`) associated with this hub and thus
this native thread.
destroy
(destroy_loop=None)[source]¶Destroy this hub and clean up its resources.
If you manually create hubs, you should call this method before disposing of the hub object reference.
exception_stream
()[source]¶The stream to which exceptions will be written.
Defaults to sys.stderr
unless assigned to.
New in version 1.2a1.
handle_error
(context, type, value, tb)[source]¶Called by the event loop when an error occurs. The arguments
type, value, and tb are the standard tuple returned by sys.exc_info()
.
Applications can set a property on the hub with this same signature to override the error handling provided by this class.
Errors that are system errors
are passed
to handle_system_error()
.
context – If this is None
, indicates a system error that
should generally result in exiting the loop and being thrown to the
parent greenlet.
handle_system_error
(type, value)[source]¶Called from handle_error
when the exception type is determined
to be a system error
.
System errors cause the exception to be raised in the main greenlet (the parent of this hub).
join
(timeout=None)[source]¶Wait for the event loop to finish. Exits only when there are no more spawned greenlets, started servers, active timeouts or watchers.
If timeout is provided, wait no longer for the specified number of seconds.
Returns True if exited because the loop finished execution. Returns False if exited because of timeout expired.
run
()[source]¶Entry-point to running the loop. This method is called automatically when the hub greenlet is scheduled; do not call it directly.
gevent.exceptions.LoopExit – If the loop finishes running. This means that there are no other scheduled greenlets, and no active watchers or servers. In some situations, this indicates a programming error.
NOT_ERROR
= (<class 'greenlet.GreenletExit'>, <class 'SystemExit'>)¶Instances of these classes are not considered to be errors and do not get logged/printed when raised by the event loop.
SYSTEM_ERROR
= (<class 'KeyboardInterrupt'>, <class 'SystemExit'>, <class 'SystemError'>)¶If instances of these classes are raised into the event loop, they will be propagated out to the main greenlet (where they will usually be caught by Python itself)
main_hub
¶Is this the hub for the main thread?
New in version 1.3b1.
name
= ''¶A string giving the name of this hub. Useful for associating hubs with particular threads. Printed as part of the default repr.
New in version 1.3b1.
resolver
¶The DNS resolver that the socket functions will use.
See also
threadpool
¶The threadpool associated with this hub.
Usually this is a
gevent.threadpool.ThreadPool
, but
you can customize that
.
Use this object to schedule blocking (non-cooperative) operations in a different thread to prevent them from halting the event loop.
threadpool_size
= 10¶The size we use for our threadpool. Either use a subclass for this, or change it immediately after creating the hub.
The current event loop can be obtained with get_hub().loop
.
All implementations of the loop provide a common minimum interface.
ILoop
[source]¶The common interface expected for all event loops.
Caution
This is an internal, low-level interface. It may change between minor versions of gevent.
Watchers
The methods that create event loop watchers are io
, timer
,
signal
, idle
, prepare
, check
, fork
, async_
, child
,
stat
. These all return various types of IWatcher
.
All of those methods have one or two common arguments. ref is a boolean saying whether the event loop is allowed to exit even if this watcher is still started. priority is event loop specific.
Waiter
(hub=None)[source]¶A low level communication utility for greenlets.
Waiter is a wrapper around greenlet’s switch()
and throw()
calls that makes them somewhat safer:
switching will occur only if the waiting greenlet is executing get()
method currently;
any error raised in the greenlet is handled inside switch()
and throw()
if switch()
/throw()
is called before the receiver calls get()
, then Waiter
will store the value/exception. The following get()
will return the value/raise the exception.
The switch()
and throw()
methods must only be called from the Hub
greenlet.
The get()
method must be called from a greenlet other than Hub
.
>>> result = Waiter()
>>> timer = get_hub().loop.timer(0.1)
>>> timer.start(result.switch, 'hello from Waiter')
>>> result.get() # blocks for 0.1 seconds
'hello from Waiter'
>>> timer.close()
If switch is called before the greenlet gets a chance to call get()
then
Waiter
stores the value.
>>> result = Waiter()
>>> timer = get_hub().loop.timer(0.1)
>>> timer.start(result.switch, 'hi from Waiter')
>>> sleep(0.2)
>>> result.get() # returns immediately without blocking
'hi from Waiter'
>>> timer.close()
Warning
This a limited and dangerous way to communicate between
greenlets. It can easily leave a greenlet unscheduled forever
if used incorrectly. Consider using safer classes such as
gevent.event.Event
, gevent.event.AsyncResult
,
or gevent.queue.Queue
.
LoopExit
[source]¶Exception thrown when the hub finishes running (gevent.hub.Hub.run
would return).
In a normal application, this is never thrown or caught
explicitly. The internal implementation of functions like
gevent.hub.Hub.join()
and gevent.joinall()
may catch it, but user code
generally should not.
Caution
Errors in application programming can also lead to this exception being raised. Some examples include (but are not limited too):
greenlets deadlocking on a lock;
using a socket or other gevent object with native thread affinity from a different thread
The following exceptions are not expected to be thrown and are not meant to be caught; if they are raised to user code it is generally a serious programming error or a bug in gevent, greenlet, or its event loop implementation. They are presented here for documentation purposes only.
ConcurrentObjectUseError
[source]¶Raised when an object is used (waited on) by two greenlets independently, meaning the object was entered into a blocking state by one greenlet and then another while still blocking in the first one.
This is usually a programming error.
See also
Next page: gevent.core
- (deprecated) event loop abstraction