==========================
 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; greenlet 3.4.0 expands this support and fixes several
race conditions. 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.
