# gevent

# `gevent` – basic utilities

The most common functions and classes are available in the `gevent` top level package.

`__version__` = '1.2.2'

  The human-readable PEP 440 version identifier

`version_info` = version_info(major=1, minor=2, micro=2, releaselevel='dev', serial=0)

  The programatic version identifier. The fields have (roughly) the same meaning as `sys.version_info` Deprecated in 1.2.

## Greenlet objects

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

class `Greenlet`

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

  Greenlet constructor.

  Parameters:

  - args – The arguments passed to the `run` function.
  - kwargs – The keyword arguments passed to the `run` function.
  - run – 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.

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

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

### 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 `__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.

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

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.

## Spawn helpers

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

  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.

`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.1b1: 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, **kwargs)

  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 `spawn()`, but this method may occasionally be useful as an optimization if there are many greenlets involved.

  Changed in version 1.1b1: If function is not callable, immediately raise a `TypeError` instead of spawning a greenlet that will raise an uncaught TypeError.

  Changed in version 1.1rc2: Accept keyword arguments for `function` as previously (incorrectly) documented. Note that this may incur an additional expense.

  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.

## Useful general functions

`getcurrent`()

  Return the currently executing greenlet (the one that called this function). Note that this may be an instance of `Greenlet` or `greenlet.greenlet`.

### Sleeping

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

`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

  `sleep()`

### Stopping Greenlets

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

  Caution

  Use care when killing greenlets. If they are not prepared for exceptions, this could result in corrupted state.

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

  Caution

  Use care when killing greenlets. If they are not prepared for exceptions, this could result in corrupted state.

  Parameters:

  - greenlets – A bounded iterable of the non-None greenlets to terminate. All the items in this iterable must be greenlets that belong to the same thread.
  - exception – The exception to raise in the greenlets. By default this is `GreenletExit`.
  - block (bool) – If True (the default) then this function only returns when all the greenlets are dead; the current greenlet is unscheduled during that process. If greenlets ignore the initial exception raised in them, then they will be joined (with `gevent.joinall()`) and allowed to die naturally. If False, this function returns immediately and greenlets will raise the exception asynchronously.
  - timeout (float) – A time in seconds to wait for greenlets to die. If given, it is only honored when `block` is True.

  Raises: | Timeout – If blocking and a timeout is given that elapses before all the greenlets are dead.

  Changed in version 1.1a2: greenlets can be any iterable of greenlets, like an iterator or a set. Previously it had to be a list or tuple.

### Waiting

`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` instance
  - `gevent.event.Event` instance
  - `gevent.lock.Semaphore` instance
  - `gevent.subprocess.Popen` instance

  If `objects` is `None` (the default), `wait()` blocks until the current event loop has nothing to do (or until `timeout` passes):

  - all greenlets have finished
  - all servers were stopped
  - all event loop watchers were stopped.

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

`iwait`(objects, timeout=None, count=None)

  Iteratively yield objects as they are ready, until all (or count) are ready or timeout expired.

  Parameters:

  - objects – A sequence (supporting `len()`) containing objects implementing the wait protocol (rawlink() and unlink()).
  - count (int) – If not None, then a number specifying the maximum number of objects to wait for. If `None` (the default), all objects are waited for.
  - timeout (float) – If given, specifies a maximum number of seconds to wait. If the timeout expires before the desired waited-for objects are available, then this method returns immediately.

  See also

  `wait()`

  Changed in version 1.1a1: Add the count parameter.

  Changed in version 1.1a2: No longer raise `LoopExit` if our caller switches greenlets in between items yielded by this function.

`joinall`(greenlets, timeout=None, raise_error=False, count=None)

  Wait for the `greenlets` to finish.

  Parameters:

  - greenlets – A sequence (supporting `len()`) of greenlets to wait for.
  - timeout (float) – If given, the maximum number of seconds to wait.

  Returns: | A sequence of the greenlets that finished before the timeout (if any) expired.

### Working with muliple processes

`fork`(*args, **kwargs)

  Forks a child process and starts a child watcher for it in the parent process so that `waitpid` and SIGCHLD work as expected.

  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.

### Signals

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

  Note

  This may not operate correctly with SIGCHLD if libev child watchers are used (as they are by default with `gevent.os.fork()`).

  Changed in version 1.1b4: This is an alias for `gevent.hub.signal`, included for backwards compatibility; the new module gevent.signal is replacing this name. This alias will be removed in a future release.

  Changed in version 1.2a1: The handler is required to be callable at construction time.

## Timeouts

class `Timeout`(seconds=None, exception=None, ref=True, priority=-1, _use_timer=True)

  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 or a `with` statement 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 the literal `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. (Note that this is not the same thing as a seconds value of 0.)

  Caution

  A seconds value less than 0.0 (e.g., -1) is poorly defined. In the future, support for negative values is likely to do the same thing as a value if `None`.

  Changed in version 1.1b2: If seconds is not given or is `None`, no longer allocate a libev timer that will never be started.

  Changed in version 1.1: Add warning about negative seconds values.

  `pending`

    Return True if the timeout is scheduled to be raised.

  `start`()

    Schedule the timeout.

  classmethod `start_new`(timeout=None, exception=None, ref=True)

    Create a started `Timeout`.

    This is a shortcut, the exact action depends on timeout’s type:

    - If timeout is a `Timeout`, then call its `start()` method if it’s not already begun.
    - Otherwise, create a new `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