Skip to content
Back to top
View this page

# C API Reference

Greenlets can be created and manipulated from extension modules written in C or C++, or from applications that embed Python. The `greenlet.h` header is provided, and exposes the entire API available to pure Python modules.

Note that much of the API is implemented in terms of macros, meaning that it is not necessarily ABI stable.

## Types

type PyGreenlet

  The C name corresponding to the Python `greenlet.greenlet`.

## Exceptions

type PyExc_GreenletError

  The C name corresponding to the Python `greenlet.error`

type PyExc_GreenletExit

  The C name corresponding to the Python `greenlet.GreenletExit`

## Functions

void PyGreenlet_Import(void)

  A macro that imports the greenlet module and initializes the C API. This must be called once for each extension module that uses the greenlet C API, usually in the module’s init function.

int PyGreenlet_Check(PyObject *p)

  Macro that returns true if the argument is a `PyGreenlet`.

int PyGreenlet_STARTED(PyGreenlet *g)

  Macro that returns true if the greenlet g has started.

int PyGreenlet_ACTIVE(PyGreenlet *g)

  Macro that returns true if the greenlet g has started and has not died.

PyGreenlet *PyGreenlet_GetParent(PyGreenlet *g)

  Macro that returns the parent greenlet of g. Returns a non-null pointer if there is a parent, or a null pointer on an error or if there is no parent. If this returns a non-null pointer, you must decrement its reference.

int PyGreenlet_SetParent(PyGreenlet *g, PyGreenlet *nparent)

  Set the parent greenlet of g.

  Returns:

    0 for success, or -1 on error. When an error is returned, g is not a pointer to a greenlet, and an `AttributeError` has been raised.

PyGreenlet *PyGreenlet_GetCurrent(void)

  Returns the currently active greenlet object.

PyGreenlet *PyGreenlet_New(PyObject *run, PyObject *parent)

  Creates a new greenlet object with the callable run and parent parent. Both parameters are optional and may be `NULL`.

  Parameters:

    - run – If `NULL`, the greenlet will be created, but will fail when switched to.

    - parent – If `NULL`, the parent is automatically set to the current greenlet.

PyObject *PyGreenlet_Switch(PyGreenlet *g, PyObject *args, PyObject *kwargs)

  Switches to the greenlet g. Besides g, the remaining parameters are optional and may be `NULL`.

  Parameters:

    - args – If `args` is NULL, an empty tuple is passed to the target greenlet. If given, must be a `tuple`.

    - kwargs – If kwargs is `NULL`, no keyword arguments are passed to the target greenlet. If given, must be a `dict`.

PyObject *PyGreenlet_Throw(PyGreenlet *g, PyObject *typ, PyObject *val, PyObject *tb)

  Switches to greenlet g, but immediately raise an exception of type typ with the value val, and optionally, the traceback object tb. tb can be `NULL`.

  The arguments typ, val and tb are interpreted as for `PyErr_Restore()`.