PEP 539 – A New C-API for Thread-Local Storage in CPython | peps.python.org
PEP 539 – A New C-API for Thread-Local Storage in CPython PEP 539 – A New C-API for Thread-Local Storage in CPython Author : Erik M. Bray, Masayuki Yamamoto BDFL-Delegate : Alyssa Coghlan Status : Final Type : Standards Track Created : 20-Dec-2016 Python-Version : 3.7 Post-History : 16-Dec-2016, 31-Aug-2017, 08-Sep-2017 Resolution : Python-Dev message Table of Contents Abstract Specification Comparison of API Specification Example Platform Support Changes Motivation Rationale for Proposed Solution Rejected Ideas Implementation Copyright References and Footnotes Abstract The proposal is to add a new Thread Local Storage (TLS) API to CPython which would supersede use of the existing TLS API within the CPython interpreter, while deprecating the existing API.
The new API is named the “Thread Specific Storage (TSS) API” (see Rationale for Proposed Solution for the origin of the name). Because the existing TLS API is only used internally (it is not mentioned in the documentation, and the header that defines it, pythread.h , is not included in Python.h either directly or indirectly), this proposal probably only affects CPython, but might also affect other interpreter implementations (PyPy?) that implement parts of the CPython API.
This is motivated primarily by the fact that the old API uses int to represent TLS keys across all platforms, which is neither POSIX-compliant, nor portable in any practical sense [1] . Note Throughout this document the acronym “TLS” refers to Thread Local Storage and should not be confused with “Transportation Layer Security” protocols. Specification The current API for TLS used inside the CPython interpreter consists of 6 functions: PyAPI_FUNC ( int ) PyThread_create_key ( void ) PyAPI_FUNC ( void ) PyThread_delete_key ( int key ) PyAPI_FUNC ( int ) PyThread_set_key_value ( int key , void * value ) PyAPI_FUNC ( void * ) PyThread_get_key_value ( int key ) PyAPI_FUNC ( void ) PyThread_delete_key_value ( int key ) PyAPI_FUNC ( void ) PyThread_ReInitTLS ( void ) These would be superseded by a new set of analogous functions: PyAPI_FUNC ( int ) PyThread_tss_create ( Py_tss_t * key ) PyAPI_FUNC ( void ) PyThread_tss_delete ( Py_tss_t * key ) PyAPI_FUNC ( int ) PyThread_tss_set ( Py_tss_t * key , void * value ) PyAPI_FUNC ( void * ) PyThread_tss_get ( Py_tss_t * key ) The specification also adds a few new features: A new type Py_tss_t –an opaque type the definition of which may depend on the underlying TLS implementation.
It is defined: typedef struct { int _is_initialized ; NATIVE_TSS_KEY_T _key ; } Py_tss_t ; where NATIVE_TSS_KEY_T is a macro whose value depends on the underlying native TLS implementation (e.g. pthread_key_t ). An initializer for Py_tss_t variables, Py_tss_NEEDS_INIT . Three new functions: PyAPI_FUNC ( Py_tss_t * ) PyThread_tss_alloc ( void ) PyAPI_FUNC ( void ) PyThread_tss_free ( Py_tss_t * key ) PyAPI_FUNC ( int ) PyThread_tss_is_created ( Py_tss_t * key ) The first two are needed for dynamic (de-)allocation of a Py_tss_t , particularly in extension modules built with Py_LIMITED_API , where static allocation of this type is not possible due to its implementation being opaque at build time.
A value returned by PyThread_tss_alloc is in the same state as a value initialized with Py_tss_NEEDS_INIT , or NULL in the case of dynamic allocation failure. The behavior of PyThread_tss_free involves calling PyThread_tss_delete preventively, or is a no-op if the value pointed to by the key argument is NULL . PyThread_tss_is_created returns non-zero if the given Py_tss_t has been initialized (i.e. by PyThread_tss_create ).
The new TSS API does not provide functions which correspond to PyThread_delete_key_value and PyThread_ReInitTLS , because these functions were needed only for CPython’s now defunct built-in TLS implementation; that is the existing behavior of these functions is treated as follows: PyThread_delete_key_value(key) is equivalent to PyThread_set_key_value(key, NULL) , and PyThread_ReInitTLS() is a no-op [8] . The new PyThread_tss_ functions are almost exactly analogous to their original counterparts with a few minor differences: Whereas PyThread_create_key takes no arguments and returns a TLS key as an int , PyThread_tss_create takes a Py_tss_t* as an argument and returns an int status code.
The behavior of PyThread_tss_create is undefined if the value pointed to by the key argument is not initialized by Py_tss_NEEDS_INIT . The returned status code is zero on success and non-zero on failure. The meanings of non-zero status codes are not otherwise defined by this specification. Similarly the other PyThread_tss_ functions are passed a Py_tss_t* whereas previously the key was passed by value. This change is necessary, as being an opaque type, the Py_tss_t type could hypothetically be almost any size.
This is especially necessary for extension modules built with Py_LIMITED_API , where the size of the type is not known. Except for PyThread_tss_free , the behaviors of PyThread_tss_ are undefined if the value pointed to by the key argument is NULL . Moreover, because of the use of Py_tss_t instead of int , there are behaviors in the new API which differ from the existing API with regard to key creation and deletion. PyThread_tss_create can be called repeatedly on the same key–calling it on an already initialized key is a no-op and immediately returns success.
Similarly for calling PyThread_tss_delete with an uninitialized key. The behavior of PyThread_tss_delete is defined to change the key’s initialization state to “uninitialized”–this allows, for example, statically allocated keys to be reset to a sensible state when restarting the CPython interpreter without terminating the process (e.g. embedding Python in an application) [12] . The old PyThread_*_key* functions will be marked as deprecated in the documentation, but will not generate runtime deprecation warnings.
Additionally, on platforms where sizeof(pthread_key_t) != sizeof(int) , PyThread_create_key will return immediately with a failure status, and the other TLS functions will all be no-ops on such platforms. Comparison of API Specification API Thread Local Storage (TLS) Thread Specific Storage (TSS) Version Existing New Key Type int Py_tss_t (opaque type) Handle Native Key cast to int conceal into internal field Function Argument int Py_tss_t * Features create key delete key set value get value delete value reinitialize keys (after fork) create key delete key set value get value (set NULL instead) [8] (unnecessary) [8] dynamically (de-)allocate key check key’s initialization state Key Initializer ( -1 as key creation failure) Py_tss_NEEDS_INIT Requirement native threads (since CPython 3.7 [9] ) native threads Restriction No support for platforms where native TLS key is defined in a way that cannot be safely cast to int .
Unable to statically allocate keys when Py_LIMITED_API is defined. Example With the proposed changes, a TSS key is initialized like: static Py_tss_t tss_key = Py_tss_NEEDS_INIT ; if ( PyThread_tss_create ( & tss_key )) { /* ... handle key creation failure ... */ } The initialization state of the key can then be checked like: assert ( PyThread_tss_is_created ( & tss_key )); The rest of the API is used analogously to the old API: int the_value = 1; if (PyThread_tss_get(&tss_key) == NULL) { PyThread_tss_set(&tss_key, (void *)&the_value); assert(PyThread_tss_get(&tss_key) != NULL); } /* ... once done with the key ... */ PyThread_tss_delete(&tss_key); assert(!PyThread_tss_is_created(&tss_key)); When Py_LIMITED_API is defined, a TSS key must be dynamically allocated: static Py_tss_t *ptr_key = PyThread_tss_alloc(); if (ptr_key == NULL) { /* ... handle key allocation failure ... */ } assert(!PyThread_tss_is_created(ptr_key)); /* ... once done with the key ... */ PyThread_tss_free(ptr_key); ptr_key = NULL; Platform Support Changes A new “Native Thread Implementation” section will be added to PEP 11 that states: As o
The rest of this page is on the live site.