Caveats and Known Issues

This document will describe known issues and sharp edges of greenlets.

Native Functions Should Be Re-entrant

Use caution when switching greenlet stacks that include native (C) frames. Much like with threads, if the library function is not re-entrant, and more than one greenlet attempts to enter it, subtle problems can result.

Common constructs in C that may not be reentrant include:

  • static variables in functions;

  • global variables.

This was the source of an issue in gevent that led to corruption of libuv’s internal state. The fix was to avoid re-entering the vulnerable function.

Use Caution Mixing Greenlets and Signal Handlers

In CPython, signal handler functions must return in order for the rest of the program to proceed. Switching greenlets in a signal handler to, for example, get back to the main greenlet, such that the signal handler function doesn’t really return to CPython, is likely to lead to a hang.

See issue #143 for an example.

Free-threading Is Experimental

Beginning with greenlet 3.3.0, support for Python 3.14’s free-threaded mode is enabled. Use caution, as it has only limited testing.

There are known issues running greenlets in a free-threaded CPython. These include:

  • As with any threaded program, use caution when forking. Greenlet maintains internal locks and forking at the wrong time might result in the child process hanging.

  • Garbage collection differences may cause GreenletExit to no longer be raised in certain multi-threaded scenarios.

  • There may be other memory leaks.

  • It may be necessary to disable the thread-local bytecode cache (and hence the specializing interpreter) to avoid a rare crash. If your process crashes on accessing an attribute or object, or at shutdown during module cleanup, try setting the environment variable PYTHON_TLBC=0 or using the -X tlbc=0 argument.