gevent.hub - Event-loop hub

get_hub(*args, **kwargs)

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

class Hub(loop=None, default=None)

Bases: greenlet.greenlet

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.

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)

backend = None
cancel_wait(watcher, error)

Cancel an in-progress call to wait() by throwing the given error in the waiting greenlet.

destroy(destroy_loop=None)
exception_stream

A non-data descriptor like @property. The difference is that when the property is assigned to, it is cached in the instance and the function is not called on that instance again.

format_context = 'pprint.saferepr'
handle_error(context, type, value, tb)

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

Parameters: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)
join(timeout=None)

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.

loop_class = [<class 'gevent.libev.corecext.loop'>]
print_exception(context, type, value, tb)
resolver
resolver_class = ['gevent.resolver_thread.Resolver', 'gevent.resolver_ares.Resolver', 'gevent.socket.BlockingResolver']

The class or callable object, or the name of a factory function or class, that will be used to create resolver. By default, configured according to Name Resolution (DNS). If a list, a list of objects in preference order.

run()

Entry-point to running the loop. This method is called automatically when the hub greenlet is scheduled; do not call it directly.

Raises: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.
switch()
switch_out()
threadpool
threadpool_class = ['gevent.threadpool.ThreadPool']
threadpool_size = 10
wait(watcher)

Wait until the watcher (which should not be started) is ready.

The current greenlet will be unscheduled during this time.

See also

gevent.core.io, gevent.core.timer, gevent.core.signal, gevent.core.idle, gevent.core.prepare, gevent.core.check, gevent.core.fork, gevent.core.async, gevent.core.child, gevent.core.stat

class Waiter(hub=None)

Bases: object

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'

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'

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.

exc_info

Holds the exception info passed to throw() if throw() was called. Otherwise None.

get()

If a value/an exception is stored, return/raise it. Otherwise until switch() or throw() is called.

ready()

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

successful()

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

switch(value=None)

Switch to the greenlet if one’s available. Otherwise store the value.

throw(*throw_args)

Switch to the greenlet with the exception. If there’s no greenlet, store the exception.

class LoopExit

Bases: Exception

Exception thrown when the hub finishes running.

In a normal application, this is never thrown or caught explicitly. The internal implementation of functions like join() and 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

Next page: gevent.core - event loop based on libev