init.rst

c

Initialization, Finalization, and Threads

See also Python Initialization Configuration <init-config>.

Before Python Initialization

In an application embedding Python, the :cPy_Initialize function must be called before using any other Python/C API functions; with the exception of a few functions and the global configuration variables <global-conf-vars>.

The following functions can be safely called before Python is initialized:

• Configuration functions:
  • :cPyImport_AppendInittab
  • :cPyImport_ExtendInittab
  • :cPyInitFrozenExtensions
  • :cPyMem_SetAllocator
  • :cPyMem_SetupDebugHooks
  • :cPyObject_SetArenaAllocator
  • :cPy_SetPath
  • :cPy_SetProgramName
  • :cPy_SetPythonHome
  • :cPy_SetStandardStreamEncoding
  • :cPySys_AddWarnOption
  • :cPySys_AddXOption
  • :cPySys_ResetWarnOptions
• Informative functions:
  • :cPy_IsInitialized
  • :cPyMem_GetAllocator
  • :cPyObject_GetArenaAllocator
  • :cPy_GetBuildInfo
  • :cPy_GetCompiler
  • :cPy_GetCopyright
  • :cPy_GetPlatform
  • :cPy_GetVersion
• Utilities:
  • :cPy_DecodeLocale
• Memory allocators:
  • :cPyMem_RawMalloc
  • :cPyMem_RawRealloc
  • :cPyMem_RawCalloc
  • :cPyMem_RawFree

Note

The following functions should not be called before :cPy_Initialize: :cPy_EncodeLocale, :cPy_GetPath, :cPy_GetPrefix, :cPy_GetExecPrefix, :cPy_GetProgramFullPath, :cPy_GetPythonHome, :cPy_GetProgramName and :cPyEval_InitThreads.

Global configuration variables

Python has variables for the global configuration to control different features and options. By default, these flags are controlled by command line options <using-on-interface-options>.

When a flag is set by an option, the value of the flag is the number of times that the option was set. For example, -b sets :cPy_BytesWarningFlag to 1 and -bb sets :cPy_BytesWarningFlag to 2.

Initializing and finalizing the interpreter

Process-wide parameters

Thread State and the Global Interpreter Lock

single: global interpreter lock single: interpreter lock single: lock, interpreter

The Python interpreter is not fully thread-safe. In order to support multi-threaded Python programs, there's a global lock, called the global interpreter lock or GIL, that must be held by the current thread before it can safely access Python objects. Without the lock, even the simplest operations could cause problems in a multi-threaded program: for example, when two threads simultaneously increment the reference count of the same object, the reference count could end up being incremented only once instead of twice.

single: setswitchinterval() (in module sys)

Therefore, the rule exists that only the thread that has acquired the GIL may operate on Python objects or call Python/C API functions. In order to emulate concurrency of execution, the interpreter regularly tries to switch threads (see sys.setswitchinterval). The lock is also released around potentially blocking I/O operations like reading or writing a file, so that other Python threads can run in the meantime.

single: PyThreadState single: PyThreadState

The Python interpreter keeps some thread-specific bookkeeping information inside a data structure called :cPyThreadState. There's also one global variable pointing to the current :cPyThreadState: it can be retrieved using :cPyThreadState_Get.

Releasing the GIL from extension code

Most extension code manipulating the GIL has the following simple structure:

Save the thread state in a local variable.
Release the global interpreter lock.
... Do some blocking I/O operation ...
Reacquire the global interpreter lock.
Restore the thread state from the local variable.

This is so common that a pair of macros exists to simplify it:

Py_BEGIN_ALLOW_THREADS
... Do some blocking I/O operation ...
Py_END_ALLOW_THREADS

single: Py_BEGIN_ALLOW_THREADS single: Py_END_ALLOW_THREADS

The :cPy_BEGIN_ALLOW_THREADS macro opens a new block and declares a hidden local variable; the :cPy_END_ALLOW_THREADS macro closes the block.

The block above expands to the following code:

PyThreadState *_save;

_save = PyEval_SaveThread();
... Do some blocking I/O operation ...
PyEval_RestoreThread(_save);

single: PyEval_RestoreThread() single: PyEval_SaveThread()

Here is how these functions work: the global interpreter lock is used to protect the pointer to the current thread state. When releasing the lock and saving the thread state, the current thread state pointer must be retrieved before the lock is released (since another thread could immediately acquire the lock and store its own thread state in the global variable). Conversely, when acquiring the lock and restoring the thread state, the lock must be acquired before storing the thread state pointer.

Note

Calling system I/O functions is the most common use case for releasing the GIL, but it can also be useful before calling long-running computations which don't need access to Python objects, such as compression or cryptographic functions operating over memory buffers. For example, the standard zlib and hashlib modules release the GIL when compressing or hashing data.

Non-Python created threads

When threads are created using the dedicated Python APIs (such as the threading module), a thread state is automatically associated to them and the code showed above is therefore correct. However, when threads are created from C (for example by a third-party library with its own thread management), they don't hold the GIL, nor is there a thread state structure for them.

If you need to call Python code from these threads (often this will be part of a callback API provided by the aforementioned third-party library), you must first register these threads with the interpreter by creating a thread state data structure, then acquiring the GIL, and finally storing their thread state pointer, before you can start using the Python/C API. When you are done, you should reset the thread state pointer, release the GIL, and finally free the thread state data structure.

The :cPyGILState_Ensure and :cPyGILState_Release functions do all of the above automatically. The typical idiom for calling into Python from a C thread is:

PyGILState_STATE gstate;
gstate = PyGILState_Ensure();

/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */

/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);

Note that the :cPyGILState_\* functions assume there is only one global interpreter (created automatically by :cPy_Initialize). Python supports the creation of additional interpreters (using :cPy_NewInterpreter), but mixing multiple interpreters and the :cPyGILState_\* API is unsupported.

Cautions about fork()

Another important thing to note about threads is their behaviour in the face of the C :cfork call. On most systems with :cfork, after a process forks only the thread that issued the fork will exist. This has a concrete impact both on how locks must be handled and on all stored state in CPython's runtime.

The fact that only the "current" thread remains means any locks held by other threads will never be released. Python solves this for os.fork by acquiring the locks it uses internally before the fork, and releasing them afterwards. In addition, it resets any lock-objects in the child. When extending or embedding Python, there is no way to inform Python of additional (non-Python) locks that need to be acquired before or reset after a fork. OS facilities such as :cpthread_atfork would need to be used to accomplish the same thing. Additionally, when extending or embedding Python, calling :cfork directly rather than through os.fork (and returning to or calling into Python) may result in a deadlock by one of Python's internal locks being held by a thread that is defunct after the fork. :cPyOS_AfterFork_Child tries to reset the necessary locks, but is not always able to.

The fact that all other threads go away also means that CPython's runtime state there must be cleaned up properly, which os.fork does. This means finalizing all other :cPyThreadState objects belonging to the current interpreter and all other :cPyInterpreterState objects. Due to this and the special nature of the "main" interpreter <sub-interpreter-support>, :cfork should only be called in that interpreter's "main" thread, where the CPython global runtime was originally initialized. The only exception is if :cexec will be called immediately after.

High-level API

These are the most commonly used types and functions when writing C extension code, or when embedding the Python interpreter:

The following functions use thread-local storage, and are not compatible with sub-interpreters:

The following macros are normally used without a trailing semicolon; look for example usage in the Python source distribution.

Low-level API

All of the following functions must be called after :cPy_Initialize.

3.7 :cPy_Initialize() now initializes the GIL.

Sub-interpreter support

While in most uses, you will only embed a single Python interpreter, there are cases where you need to create several independent interpreters in the same process and perhaps even in the same thread. Sub-interpreters allow you to do that.

The "main" interpreter is the first one created when the runtime initializes. It is usually the only Python interpreter in a process. Unlike sub-interpreters, the main interpreter has unique process-global responsibilities like signal handling. It is also responsible for execution during runtime initialization and is usually the active interpreter during runtime finalization. The :cPyInterpreterState_Main function returns a pointer to its state.

You can switch between sub-interpreters using the :cPyThreadState_Swap function. You can create and destroy them using the following functions:

Bugs and caveats

Because sub-interpreters (and the main interpreter) are part of the same process, the insulation between them isn't perfect --- for example, using low-level file operations like os.close they can (accidentally or maliciously) affect each other's open files. Because of the way extensions are shared between (sub-)interpreters, some extensions may not work properly; this is especially likely when using single-phase initialization or (static) global variables. It is possible to insert objects created in one sub-interpreter into a namespace of another (sub-)interpreter; this should be avoided if possible.

Special care should be taken to avoid sharing user-defined functions, methods, instances or classes between sub-interpreters, since import operations executed by such objects may affect the wrong (sub-)interpreter's dictionary of loaded modules. It is equally important to avoid sharing objects from which the above are reachable.

Also note that combining this functionality with :cPyGILState_\* APIs is delicate, because these APIs assume a bijection between Python thread states and OS-level threads, an assumption broken by the presence of sub-interpreters. It is highly recommended that you don't switch sub-interpreters between a pair of matching :cPyGILState_Ensure and :cPyGILState_Release calls. Furthermore, extensions (such as ctypes) using these APIs to allow calling of Python code from non-Python created threads will probably be broken when using sub-interpreters.

Asynchronous Notifications

A mechanism is provided to make asynchronous notifications to the main interpreter thread. These notifications take the form of a function pointer and a void pointer argument.

Profiling and Tracing

Fred L. Drake, Jr. <fdrake@acm.org>

The Python interpreter provides some low-level support for attaching profiling and execution tracing facilities. These are used for profiling, debugging, and coverage analysis tools.

This C interface allows the profiling or tracing code to avoid the overhead of calling through Python-level callable objects, making a direct C function call instead. The essential attributes of the facility have not changed; the interface allows trace functions to be installed per-thread, and the basic events reported to the trace function are the same as had been reported to the Python-level trace functions in previous versions.

3.12

3.12

Advanced Debugger Support

Fred L. Drake, Jr. <fdrake@acm.org>

These functions are only intended to be used by advanced debugging tools.

Thread Local Storage Support

Masayuki Yamamoto <ma3yuki.8mamo10@gmail.com>

The Python interpreter provides low-level support for thread-local storage (TLS) which wraps the underlying native TLS implementation to support the Python-level thread local storage API (threading.local). The CPython C level APIs are similar to those offered by pthreads and Windows: use a thread key and functions to associate a :cvoid* value per thread.

The GIL does not need to be held when calling these functions; they supply their own locking.

Note that Python.h does not include the declaration of the TLS APIs, you need to include pythread.h to use thread-local storage.

Note

None of these API functions handle memory management on behalf of the :cvoid* values. You need to allocate and deallocate them yourself. If the :cvoid* values happen to be :cPyObject*, these functions don't do refcount operations on them either.

Thread Specific Storage (TSS) API

TSS API is introduced to supersede the use of the existing TLS API within the CPython interpreter. This API uses a new type :cPy_tss_t instead of :cint to represent thread keys.

3.7

"A New C-API for Thread-Local Storage in CPython" (539)

Dynamic Allocation

Dynamic allocation of the :cPy_tss_t, required in extension modules built with Py_LIMITED_API <stable>, where static allocation of this type is not possible due to its implementation being opaque at build time.

Methods

The parameter key of these functions must not be NULL. Moreover, the behaviors of :cPyThread_tss_set and :cPyThread_tss_get are undefined if the given :cPy_tss_t has not been initialized by :cPyThread_tss_create.

Thread Local Storage (TLS) API

3.7 This API is superseded by Thread Specific Storage (TSS) API <thread-specific-storage-api>.

Note

This version of the API does not support platforms where the native TLS key is defined in a way that cannot be safely cast to int. On such platforms, :cPyThread_create_key will return immediately with a failure status, and the other TLS functions will all be no-ops on such platforms.

Due to the compatibility problem noted above, this version of the API should not be used in new code.