# gevent

# Greenlet Objects

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

## Starting Greenlets

To start a new greenlet, pass the target function and its arguments to `Greenlet` constructor and call `Greenlet.start()`:

    >>> 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:

- `gevent.spawn()`
- `gevent.spawn_later()`
- `gevent.spawn_raw()`

## Stopping Greenlets

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`):

- `gevent.kill()`
- `gevent.killall()`

## Subclassing Greenlet

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.

## Boolean Contexts

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.

exception `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.

class `Greenlet`

`Greenlet.``__init__`(run=None, *args, **kwargs)

  Parameters:

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

Attributes

`Greenlet.``exception`

  Holds the exception instance raised by the function if the greenlet has finished with an error. Otherwise `None`.

`Greenlet.``minimal_ident`

  A small, unique 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 `minimal_ident`.

  New in version 1.3a2.

`Greenlet.``name`

  The greenlet name. By default, a unique name is constructed using the `minimal_ident`. You can assign a string to this value to change it. It is shown in the `repr` of this object if it has been assigned to or if the `minimal_ident` has already been generated.

  New in version 1.3a2.

  Changed in version 1.4: Stop showing generated names in the `repr` when the `minimal_ident` hasn’t been requested. This reduces overhead and may be less confusing, since `minimal_ident` can get reused.

`Greenlet.``dead`

  Boolean indicating that the greenlet is dead and will not run again.

`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.``spawn_tree_locals`

  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.

`Greenlet.``spawning_greenlet`

  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.

`Greenlet.``spawning_stack`

  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.

`Greenlet.``spawning_stack_limit`

  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

classmethod `Greenlet.``spawn`(function, *args, **kwargs) → Greenlet

  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.

`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) → None

  Schedule the greenlet to run in the future loop iteration seconds later

`Greenlet.``join`(timeout=None) → None

  Wait until the greenlet finishes or timeout expires. Return `None` regardless.

`Greenlet.``get`(block=True, timeout=None) → object

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

  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.

  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 is dead. A callable is called in its own `greenlet.greenlet` (not a `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.``unlink`(callback)

  Remove the callback set by `link()` or `rawlink()`

`Greenlet.``__str__`()

  Return str(self).

static `Greenlet.``add_spawn_callback`(callback) → None

  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.

static `Greenlet.``remove_spawn_callback`(callback) → None

  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.

## Raw greenlet Methods

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.

class `greenlet.``greenlet`

  The base class from which `Greenlet` descends.

Next page: Implementing servers