gevent.Greenlet is a light-weight cooperatively-scheduled
execution unit. It is a more powerful version of
greenlet.greenlet. For general information, see Lightweight pseudothreads.
You can retrieve the current greenlet at any time using
gevent.getcurrent().
To start a new greenlet, pass the target function and its arguments to
Greenlet constructor and call Greenlet.start():
>>> from gevent import Greenlet
>>> def myfunction(arg1, arg2, kwarg1=None):
... pass
>>> g = Greenlet(myfunction, 'arg1', 'arg2', kwarg1=1)
>>> g.start()
or use classmethod Greenlet.spawn() which is a shortcut that
does the same:
>>> g = Greenlet.spawn(myfunction, 'arg1', 'arg2', kwarg1=1)
There are also various spawn helpers in gevent, including:
You can wait for a greenlet to finish with its Greenlet.join()
method. There are helper functions to join multiple greenlets or
heterogenous collections of objects:
You can forcibly stop a Greenlet using its Greenlet.kill()
method. There are also helper functions that can be useful in limited
circumstances (if you might have a raw greenlet):
New in version 21.1.0.
Greenlets also function as context managers, so you can combine spawning and waiting for a greenlet to finish in a single line:
>>> def in_greenlet():
... print("In the greenlet")
... return 42
>>> with Greenlet.spawn(in_greenlet) as g:
... print("In the with suite")
In the with suite
In the greenlet
>>> g.get(block=False)
42
Normally, the greenlet is joined to wait for it to finish, but if the body of the suite raises an exception, the greenlet is killed with that exception.
>>> import gevent
>>> try:
... with Greenlet.spawn(gevent.sleep, 0.1) as g:
... raise Exception("From with body")
... except Exception:
... pass
>>> g.dead
True
>>> g.successful()
False
>>> g.get(block=False)
Traceback (most recent call last):
...
Exception: From with body
To subclass a Greenlet, override its _run() method and
call Greenlet.__init__(self) in the subclass __init__. This
can be done to override Greenlet.__str__(): if _run raises
an exception, its string representation will be printed after the
traceback it generated.
class MyNoopGreenlet(Greenlet):
def __init__(self, seconds):
Greenlet.__init__(self)
self.seconds = seconds
def _run(self):
gevent.sleep(self.seconds)
def __str__(self):
return 'MyNoopGreenlet(%s)' % self.seconds
Important
You SHOULD NOT attempt to override the run() method.
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 boolean value is an improvement on the raw
greenlet's boolean value. The raw
greenlet’s boolean value returns False if the 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.
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.
args – The arguments passed to the run function.
kwargs – The keyword arguments passed to the run function.
run (callable) – The callable object to run. If not given, this object’s
_run method will be invoked (typically defined by subclasses).
Changed in version 1.1b1: 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.
Changed in version 1.3b1: The GEVENT_TRACK_GREENLET_TREE configuration value may be set to
a false value to disable spawn_tree_locals, spawning_greenlet,
and spawning_stack. The first two will be None in that case, and the
latter will be empty.
Changed in version 1.5: Greenlet objects are now more careful to verify that their parent is really
a gevent hub, raising a TypeError earlier instead of an AttributeError later.
Changed in version 20.12.1: Greenlet objects now function as context managers. Exiting the with suite
ensures that the greenlet has completed by joining
the greenlet (blocking, with
no timeout). If the body of the suite raises an exception, the greenlet is
killed with the default arguments and not joined in that case.
Attributes
Holds the exception instance raised by the function if the
greenlet has finished with an error. Otherwise None.
A small, unique non-negative integer that identifies this object.
This is similar to threading.Thread.ident (and id)
in that as long as this object is alive, no other greenlet in
this hub will have the same id, but it makes a stronger
guarantee that the assigned values will be small and
sequential. Sometime after this object has died, the value
will be available for reuse.
To get ids that are unique across all hubs, combine this with
the hub’s (self.parent) minimal_ident.
Accessing this property from threads other than the thread running this greenlet is not defined.
New in version 1.3a2.
Boolean indicating that the greenlet is dead and will not run again.
This is true if:
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.
A dictionary that is shared between all the greenlets in a “spawn tree”, that is, a spawning greenlet and all its descendent greenlets. All children of the main (root) greenlet start their own spawn trees. Assign a new dictionary to this attribute on an instance of this class to create a new spawn tree (as far as locals are concerned).
New in version 1.3a2.
A weak-reference to the greenlet that was current when this object
was created. Note that the parent attribute is always the
hub.
New in version 1.3a2.
A lightweight frame-like object capturing the stack when
this greenlet was created as well as the stack when the spawning
greenlet was created (if applicable). This can be passed to
traceback.print_stack().
New in version 1.3a2.
A class attribute specifying how many levels of the spawning stack will be kept. Specify a smaller number for higher performance, spawning greenlets, specify a larger value for improved debugging.
New in version 1.3a2.
Methods
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__().
Changed in version 1.1b1: If a function is given that is not callable, immediately raise a TypeError
instead of spawning a greenlet that will raise an uncaught TypeError.
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.
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.
Schedule the greenlet to run in the future loop iteration seconds later
Wait until the greenlet finishes or timeout expires. Return
None regardless.
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.
Raise the exception in the greenlet.
If block is True (the default), wait until the greenlet
dies or the optional timeout expires; this may require switching
greenlets.
If block is False, the current greenlet is not unscheduled.
This function always returns None and never raises an error. It
may be called multpile times on the same greenlet object, and may be
called on an unstarted or dead greenlet.
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).
Caution
Use care when killing greenlets. If the code executing is not
exception safe (e.g., makes proper use of finally) then an
unexpected exception could result in corrupted state. Using
a link() or rawlink() (cheaper) may be a safer way to
clean up resources.
See also gevent.kill() and gevent.killall().
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. Links (rawlink())
will still be executed, though.
Changed in version 20.12.1: If this greenlet is ready(), immediately return instead of
requiring a trip around the event loop.
Link greenlet’s completion to a callable.
The callback will be called with this instance as an
argument once this greenlet is dead. A callable is called in
its own greenlet.greenlet (not a
Greenlet).
The callback will be called even if linked after the greenlet is already ready().
Like link() but callback is only notified when the greenlet
has completed successfully.
Like link() but callback is only notified when the
greenlet dies because of an unhandled exception.
Register a callable to be executed when the greenlet finishes execution.
The callback will be called with this instance as an argument.
The callback will be called even if linked after the greenlet is already ready().
Caution
The callback will be called in the hub and MUST NOT raise an exception.
Return str(self).
Set up a callback to be invoked when Greenlet objects
are started.
The invocation order of spawn callbacks is unspecified. Adding the same callback more than one time will not cause it to be called more than once.
New in version 1.4.0.
Remove callback function added with Greenlet.add_spawn_callback().
This function will not fail if callback has been already removed or
if callback was never added.
New in version 1.4.0.
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.
Next page: Implementing servers