gevent
– basic utilities¶The most common functions and classes are available in the gevent
top level package.
__version__
= '1.1b4.dev0'¶The human-readable PEP 440 version identifier
version_info
= version_info(major=1, minor=1, micro=0, releaselevel='beta', serial='4')¶The programatic version identifier. The fields have (roughly) the
same meaning as sys.version_info
Greenlet
is a light-weight cooperatively-scheduled execution unit.
To start a new greenlet, pass the target function and its arguments to Greenlet
constructor and call start()
:
>>> g = Greenlet(myfunction, 'arg1', 'arg2', kwarg1=1)
>>> g.start()
or use classmethod spawn()
which is a shortcut that does the same:
>>> g = Greenlet.spawn(myfunction, 'arg1', 'arg2', kwarg1=1)
To subclass a Greenlet
, override its _run()
method and
call Greenlet.__init__(self)
in __init__()
: It also a good
idea to override __str__()
: if _run()
raises an exception,
its string representation will be printed after the traceback it
generated.
Important
You SHOULD NOT attempt to override the
run()
method.
Greenlet
¶Greenlet.
__init__
(run=None, *args, **kwargs)¶Greenlet constructor.
Parameters: |
|
---|
Changed in version 1.1a3: The run
argument to the constructor is now verified to be a callable
object. Previously, passing a non-callable object would fail after the greenlet
was spawned.
Greenlet.
value
¶Holds the value returned by the function if the greenlet has
finished successfully. Until then, or if it finished in error, None
.
Tip
Recall that a greenlet killed with the default
GreenletExit
is considered to have finished
successfully, and the GreenletExit
exception will be
its value.
Greenlet.
exception
¶Holds the exception instance raised by the function if the greenlet has finished with an error.
Otherwise None
.
Greenlet.
ready
()¶Return a true value if and only if the greenlet has finished execution.
Changed in version 1.1: This function is only guaranteed to return true or false values, not
necessarily the literal constants True
or False
.
Greenlet.
successful
()¶Return a true value if and only if the greenlet has finished execution successfully, that is, without raising an error.
Tip
A greenlet that has been killed with the default
GreenletExit
exception is considered successful.
That is, GreenletExit
is not considered an error.
Note
This function is only guaranteed to return true or false values,
not necessarily the literal constants True
or False
.
Greenlet.
start
()¶Schedule the greenlet to run in this loop iteration
Greenlet.
start_later
(seconds)¶Schedule the greenlet to run in the future loop iteration seconds later
Greenlet.
join
(timeout=None)¶Wait until the greenlet finishes or timeout expires.
Return None
regardless.
Greenlet.
get
(block=True, timeout=None)¶Return the result the greenlet has returned or re-raise the exception it has raised.
If block is False
, raise gevent.Timeout
if the greenlet is still alive.
If block is True
, unschedule the current greenlet until the result is available
or the timeout expires. In the latter case, gevent.Timeout
is raised.
Greenlet.
kill
(exception=GreenletExit, block=True, timeout=None)¶Raise the exception
in the greenlet.
If block
is True
(the default), wait until the greenlet dies or the optional timeout expires.
If block is False
, the current greenlet is not unscheduled.
The function always returns None
and never raises an error.
Note
Depending on what this greenlet is executing and the state
of the event loop, the exception may or may not be raised
immediately when this greenlet resumes execution. It may
be raised on a subsequent green call, or, if this greenlet
exits before making such a call, it may not be raised at
all. As of 1.1, an example where the exception is raised
later is if this greenlet had called sleep(0)
; an example where the exception is raised
immediately is if this greenlet had called
sleep(0.1)
.
See also gevent.kill()
.
Parameters: | exception (type) – The type of exception to raise in the greenlet. The default
is GreenletExit , which indicates a successful() completion
of the greenlet. |
---|
Changed in version 0.13.0: block is now True
by default.
Changed in version 1.1a2: If this greenlet had never been switched to, killing it will prevent it from ever being switched to.
Greenlet.
link
(callback)¶Link greenlet’s completion to a callable.
The callback will be called with this instance as an argument once this greenlet’s dead. A callable is called in its own greenlet.
Greenlet.
link_value
(callback)¶Like link()
but callback is only notified when the greenlet has completed successfully.
Greenlet.
link_exception
(callback)¶Like link()
but callback is only notified when the greenlet dies because of an unhandled exception.
Greenlet.
rawlink
(callback)¶Register a callable to be executed when the greenlet finishes execution.
The callback will be called with this instance as an argument.
Caution
The callable will be called in the HUB greenlet.
Greenlet objects have a boolean value (__nonzero__
or
__bool__
) which is true if it’s active: started but not dead yet.
It’s possible to use it like this:
>>> g = gevent.spawn(...)
>>> while g:
# do something while g is alive
The Greenlet’s __nonzero__
is an improvement on greenlet’s
__nonzero__
. The greenlet’s __nonzero__
returns False if greenlet has not
been switched to yet or is already dead. While the latter is OK, the
former is not good, because a just spawned Greenlet has not been
switched to yet and thus would evaluate to False.
Being a greenlet subclass, Greenlet
also has switch() and throw() methods. However, these should
not be used at the application level as they can very easily lead to
greenlets that are forever unscheduled. Prefer higher-level safe
classes, like Event
and Queue
, instead.
GreenletExit
¶A special exception that kills the greenlet silently.
When a greenlet raises GreenletExit
or a subclass, the traceback is not
printed and the greenlet is considered successful
.
The exception instance is available under value
property as if it was returned by the greenlet, not raised.
spawn
(function, *args, **kwargs)¶Create a new Greenlet
object and schedule it to run function(*args, **kwargs)
.
This can be used as gevent.spawn
or Greenlet.spawn
.
The arguments are passed to Greenlet.__init__()
.
spawn_later
(seconds, function, *args, **kwargs)¶Create and return a new Greenlet object scheduled to run function(*args, **kwargs)
in the future loop iteration seconds later. This can be used as Greenlet.spawn_later
or gevent.spawn_later
.
The arguments are passed to Greenlet.__init__()
.
Changed in version 1.1a3: If an argument that’s meant to be a function (the first argument in args, or the run
keyword )
is given to this classmethod (and not a classmethod of a subclass),
it is verified to be callable. Previously, the spawned greenlet would have failed
when it started running.
spawn_raw
(function, *args)¶Create a new greenlet.greenlet
object and schedule it to run function(*args, **kwargs)
.
This returns a raw greenlet which does not have all the useful methods that
gevent.Greenlet
has. Typically, applications should prefer gevent.spawn()
,
but this method may occasionally be useful as an optimization if there are many greenlets
involved.
Changed in version 1.1a3: Verify that function
is callable, raising a TypeError if not. Previously,
the spawned greenlet would have failed the first time it was switched to.
getcurrent
()¶Return the currently executing greenlet (the one that called this
function). Note that this may be an instance of Greenlet
or greenlet.greenlet
.
sleep
(seconds=0, ref=True)¶Put the current greenlet to sleep for at least seconds.
seconds may be specified as an integer, or a float if fractional seconds are desired.
Tip
In the current implementation, a value of 0 (the default) means to yield execution to any other runnable greenlets, but this greenlet may be scheduled again before the event loop cycles (in an extreme case, a greenlet that repeatedly sleeps with 0 can prevent greenlets that are ready to do I/O from being scheduled for some (small) period of time); a value greater than 0, on the other hand, will delay running this greenlet until the next iteration of the loop.
If ref is False, the greenlet running sleep()
will not prevent gevent.wait()
from exiting.
See also
idle
(priority=0)¶Cause the calling greenlet to wait until the event loop is idle.
Idle is defined as having no other events of the same or higher priority pending. That is, as long as sockets, timeouts or even signals of the same or higher priority are being processed, the loop is not idle.
See also
kill
(greenlet, exception=GreenletExit)¶Kill greenlet asynchronously. The current greenlet is not unscheduled.
Note
The method Greenlet.kill()
method does the same and
more (and the same caveats listed there apply here). However, the MAIN
greenlet - the one that exists initially - does not have a
kill()
method, and neither do any created with spawn_raw()
,
so you have to use this function.
Changed in version 1.1a2: If the greenlet
has a kill
method, calls it. This prevents a
greenlet from being switched to for the first time after it’s been
killed but not yet executed.
killall
(greenlets, exception=GreenletExit, block=True, timeout=None)¶Forceably terminate all the greenlets
by causing them to raise exception
.
Parameters: |
|
---|---|
Raises Timeout: | If blocking and a timeout is given that elapses before all the greenlets are dead. |
wait
(objects=None, timeout=None, count=None)¶Wait for objects
to become ready or for event loop to finish.
If objects
is provided, it must be a list containing objects
implementing the wait protocol (rawlink() and unlink() methods):
gevent.Greenlet
instancegevent.event.Event
instancegevent.lock.Semaphore
instancegevent.subprocess.Popen
instanceIf objects
is None
(the default), wait()
blocks until
the current event loop has nothing to do (or until timeout
passes):
If count
is None
(the default), wait for all objects
to become ready.
If count
is a number, wait for (up to) count
objects to become
ready. (For example, if count is 1
then the function exits
when any object in the list is ready).
If timeout
is provided, it specifies the maximum number of
seconds wait()
will block.
Returns the list of ready objects, in the order in which they were ready.
See also
iwait
(objects, timeout=None, count=None)¶Iteratively yield objects as they are ready, until all (or count) are ready or timeout expired.
Parameters: |
|
---|
See also
joinall
(greenlets, timeout=None, raise_error=False, count=None)¶Wait for the greenlets
to finish.
Parameters: | |
---|---|
Returns: | A sequence of the greenlets that finished before the timeout (if any) expired. |
fork
(*args, **kwargs)¶Forks a child process and starts a child watcher for it in the parent process.
This implementation of fork
is a wrapper for fork_and_watch()
when the environment variable GEVENT_NOWAITPID
is not defined.
This is the default and should be used by most applications.
Changed in version 1.1b2.
reinit
()¶Prepare the gevent hub to run in a new (forked) process.
This should be called immediately after os.fork()
in the
child process. This is done automatically by
gevent.os.fork()
or if the os
module has been
monkey-patched. If this function is not called in a forked
process, symptoms may include hanging of functions like
socket.getaddrinfo()
, and the hub’s threadpool is unlikely
to work.
Note
Registered fork watchers may or may not run before
this function (and thus gevent.os.fork
) return. If they have
not run, they will run “soon”, after an iteration of the event loop.
You can force this by inserting a few small (but non-zero) calls to sleep()
after fork returns. (As of gevent 1.1 and before, fork watchers will
not have run, but this may change in the future.)
Note
This function may be removed in a future major release if the fork process can be more smoothly managed.
Warning
See remarks in gevent.os.fork()
about greenlets
and libev watchers in the child process.
signal
(signalnum, handler, *args, **kwargs)¶Call the handler with the args and kwargs when the process receives the signal signalnum.
The handler will be run in a new greenlet when the signal is delivered.
This returns an object with the useful method cancel
, which, when called,
will prevent future deliveries of signalnum from calling handler.
Timeout
(seconds=None, exception=None, ref=True, priority=-1)¶Bases: exceptions.BaseException
Raise exception in the current greenlet after given time period:
timeout = Timeout(seconds, exception)
timeout.start()
try:
... # exception will be raised here, after *seconds* passed since start() call
finally:
timeout.cancel()
Note
If the code that the timeout was protecting finishes
executing before the timeout elapses, be sure to cancel
the timeout
so it is not unexpectedly raised in the future. Even if it is raised, it is a best
practice to cancel it. This try/finally
construct is a recommended pattern.
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
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 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.
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
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.
Changed in version 1.1b2: If seconds is not given or is None
, no longer allocate a libev
timer that will never be started.
pending
¶Return True if the timeout is scheduled to be raised.
start
()¶Schedule the timeout.
start_new
(timeout=None, exception=None, ref=True)¶Create a started Timeout
.
This is a shortcut, the exact action depends on timeout‘s type:
Timeout
, then call its start()
method
if it’s not already begun.Timeout
instance, passing (timeout, exception) as
arguments, then call its start()
method.Returns the Timeout
instance.
cancel
()¶If the timeout is pending, cancel it. Otherwise, do nothing.
with_timeout
(seconds, function, *args, **kwds)¶Wrap a call to function with a timeout; if the called function fails to return before the timeout, cancel it and return a flag value, provided by timeout_value keyword argument.
If timeout expires but timeout_value is not provided, raise Timeout
.
Keyword argument timeout_value is not passed to function.
Next page: Networking interfaces