Skip to content
Back to top
View this page

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