Initialization, Finalization, and Threads¶

Before Python Initialization¶

In an application embedding Python, thePy_Initialize() function mustbe called before using any other Python/C API functions; with the exception ofa few functions and theglobal configuration variables.

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

Σημείωση

The following functionsshould not be called beforePy_Initialize():Py_EncodeLocale(),Py_GetPath(),Py_GetPrefix(),Py_GetExecPrefix(),Py_GetProgramFullPath(),Py_GetPythonHome(),Py_GetProgramName() andPyEval_InitThreads().

Global configuration variables¶

Python has variables for the global configuration to control different featuresand options. By default, these flags are controlled bycommand lineoptions.

When a flag is set by an option, the value of the flag is the number of timesthat the option was set. For example,-b setsPy_BytesWarningFlagto 1 and-bb setsPy_BytesWarningFlag to 2.

intPy_BytesWarningFlag¶

This API is kept for backward compatibility: settingPyConfig.bytes_warning should be used instead, seePythonInitialization Configuration.

Issue a warning when comparingbytes orbytearray withstr orbytes withint. Issue an error if greateror equal to2.

Set by the-b option.

Αποσύρθηκε στην έκδοση 3.12.

intPy_DebugFlag¶

This API is kept for backward compatibility: settingPyConfig.parser_debug should be used instead, seePythonInitialization Configuration.

Turn on parser debugging output (for expert only, depending on compilationoptions).

Set by the-d option and thePYTHONDEBUG environmentvariable.

Αποσύρθηκε στην έκδοση 3.12.

intPy_DontWriteBytecodeFlag¶

This API is kept for backward compatibility: settingPyConfig.write_bytecode should be used instead, seePythonInitialization Configuration.

If set to non-zero, Python won’t try to write.pyc files on theimport of source modules.

Set by the-B option and thePYTHONDONTWRITEBYTECODEenvironment variable.

Αποσύρθηκε στην έκδοση 3.12.

intPy_FrozenFlag¶

This API is kept for backward compatibility: settingPyConfig.pathconfig_warnings should be used instead, seePython Initialization Configuration.

Suppress error messages when calculating the module search path inPy_GetPath().

Private flag used by_freeze_module andfrozenmain programs.

Αποσύρθηκε στην έκδοση 3.12.

intPy_HashRandomizationFlag¶

This API is kept for backward compatibility: settingPyConfig.hash_seed andPyConfig.use_hash_seed shouldbe used instead, seePython Initialization Configuration.

Set to1 if thePYTHONHASHSEED environment variable is set toa non-empty string.

If the flag is non-zero, read thePYTHONHASHSEED environmentvariable to initialize the secret hash seed.

Αποσύρθηκε στην έκδοση 3.12.

intPy_IgnoreEnvironmentFlag¶

This API is kept for backward compatibility: settingPyConfig.use_environment should be used instead, seePython Initialization Configuration.

Ignore allPYTHON* environment variables, e.g.PYTHONPATH andPYTHONHOME, that might be set.

Set by the-E and-I options.

Αποσύρθηκε στην έκδοση 3.12.

intPy_InspectFlag¶

This API is kept for backward compatibility: settingPyConfig.inspect should be used instead, seePython Initialization Configuration.

When a script is passed as first argument or the-c option is used,enter interactive mode after executing the script or the command, even whensys.stdin does not appear to be a terminal.

Set by the-i option and thePYTHONINSPECT environmentvariable.

Αποσύρθηκε στην έκδοση 3.12.

intPy_InteractiveFlag¶

This API is kept for backward compatibility: settingPyConfig.interactive should be used instead, seePython Initialization Configuration.

Set by the-i option.

Αποσύρθηκε στην έκδοση 3.12.

intPy_IsolatedFlag¶

This API is kept for backward compatibility: settingPyConfig.isolated should be used instead, seePython Initialization Configuration.

Run Python in isolated mode. In isolated modesys.path containsneither the script’s directory nor the user’s site-packages directory.

Set by the-I option.

Added in version 3.4.

Αποσύρθηκε στην έκδοση 3.12.

intPy_LegacyWindowsFSEncodingFlag¶

This API is kept for backward compatibility: settingPyPreConfig.legacy_windows_fs_encoding should be used instead, seePython Initialization Configuration.

If the flag is non-zero, use thembcs encoding withreplace errorhandler, instead of the UTF-8 encoding withsurrogatepass error handler,for thefilesystem encoding and error handler.

Set to1 if thePYTHONLEGACYWINDOWSFSENCODING environmentvariable is set to a non-empty string.

SeePEP 529 for more details.

Διαθεσιμότητα: Windows.

Αποσύρθηκε στην έκδοση 3.12.

intPy_LegacyWindowsStdioFlag¶

This API is kept for backward compatibility: settingPyConfig.legacy_windows_stdio should be used instead, seePython Initialization Configuration.

If the flag is non-zero, useio.FileIO instead ofio._WindowsConsoleIO forsys standard streams.

Set to1 if thePYTHONLEGACYWINDOWSSTDIO environmentvariable is set to a non-empty string.

SeePEP 528 for more details.

Διαθεσιμότητα: Windows.

Αποσύρθηκε στην έκδοση 3.12.

intPy_NoSiteFlag¶

This API is kept for backward compatibility: settingPyConfig.site_import should be used instead, seePython Initialization Configuration.

Disable the import of the modulesite and the site-dependentmanipulations ofsys.path that it entails. Also disable thesemanipulations ifsite is explicitly imported later (callsite.main() if you want them to be triggered).

Set by the-S option.

Αποσύρθηκε στην έκδοση 3.12.

intPy_NoUserSiteDirectory¶

This API is kept for backward compatibility: settingPyConfig.user_site_directory should be used instead, seePython Initialization Configuration.

Don’t add theusersite-packagesdirectory tosys.path.

Set by the-s and-I options, and thePYTHONNOUSERSITE environment variable.

Αποσύρθηκε στην έκδοση 3.12.

intPy_OptimizeFlag¶

This API is kept for backward compatibility: settingPyConfig.optimization_level should be used instead, seePython Initialization Configuration.

Set by the-O option and thePYTHONOPTIMIZE environmentvariable.

Αποσύρθηκε στην έκδοση 3.12.

intPy_QuietFlag¶

This API is kept for backward compatibility: settingPyConfig.quiet should be used instead, seePythonInitialization Configuration.

Don’t display the copyright and version messages even in interactive mode.

Set by the-q option.

Added in version 3.2.

Αποσύρθηκε στην έκδοση 3.12.

intPy_UnbufferedStdioFlag¶

This API is kept for backward compatibility: settingPyConfig.buffered_stdio should be used instead, seePythonInitialization Configuration.

Force the stdout and stderr streams to be unbuffered.

Set by the-u option and thePYTHONUNBUFFEREDenvironment variable.

Αποσύρθηκε στην έκδοση 3.12.

intPy_VerboseFlag¶

This API is kept for backward compatibility: settingPyConfig.verbose should be used instead, seePythonInitialization Configuration.

Print a message each time a module is initialized, showing the place(filename or built-in module) from which it is loaded. If greater or equalto2, print a message for each file that is checked for whensearching for a module. Also provides information on module cleanup at exit.

Set by the-v option and thePYTHONVERBOSE environmentvariable.

Αποσύρθηκε στην έκδοση 3.12.

Initializing and finalizing the interpreter¶

voidPy_Initialize()¶

Μέρος τουΣταθερό ABI.

Initialize the Python interpreter. In an application embedding Python,this should be called before using any other Python/C API functions; seeBefore Python Initialization for the few exceptions.

This initializesthe table of loaded modules (sys.modules), and creates the fundamentalmodulesbuiltins,__main__ andsys. It also initializesthe module search path (sys.path). It does not setsys.argv; usePySys_SetArgvEx() for that. This is a no-op when called for a second time(without callingPy_FinalizeEx() first). There is no return value; it is afatal error if the initialization fails.

Use thePy_InitializeFromConfig() function to customize thePython Initialization Configuration.

Σημείωση

On Windows, changes the console mode fromO_TEXT toO_BINARY, which willalso affect non-Python uses of the console using the C Runtime.

voidPy_InitializeEx(intinitsigs)¶

Μέρος τουΣταθερό ABI.

This function works likePy_Initialize() ifinitsigs is1. Ifinitsigs is0, it skips initialization registration of signal handlers, whichmight be useful when Python is embedded.

Use thePy_InitializeFromConfig() function to customize thePython Initialization Configuration.

intPy_IsInitialized()¶: Μέρος τουΣταθερό ABI.
Return true (nonzero) when the Python interpreter has been initialized, false(zero) if not. AfterPy_FinalizeEx() is called, this returns false untilPy_Initialize() is called again.

intPy_FinalizeEx()¶

Μέρος τουΣταθερό ABI από την έκδοση 3.6.

Undo all initializations made byPy_Initialize() and subsequent use ofPython/C API functions, and destroy all sub-interpreters (seePy_NewInterpreter() below) that were created and not yet destroyed sincethe last call toPy_Initialize(). Ideally, this frees all memoryallocated by the Python interpreter. This is a no-op when called for a secondtime (without callingPy_Initialize() again first).

Since this is the reverse ofPy_Initialize(), it should be calledin the same thread with the same interpreter active. That meansthe main thread and the main interpreter.This should never be called whilePy_RunMain() is running.

Normally the return value is0.If there were errors during finalization (flushing buffered data),-1 is returned.

This function is provided for a number of reasons. An embedding applicationmight want to restart Python without having to restart the application itself.An application that has loaded the Python interpreter from a dynamicallyloadable library (or DLL) might want to free all memory allocated by Pythonbefore unloading the DLL. During a hunt for memory leaks in an application adeveloper might want to free all memory allocated by Python before exiting fromthe application.

Bugs and caveats: The destruction of modules and objects in modules is donein random order; this may cause destructors (__del__() methods) to failwhen they depend on other objects (even functions) or modules. Dynamicallyloaded extension modules loaded by Python are not unloaded. Small amounts ofmemory allocated by the Python interpreter may not be freed (if you find a leak,please report it). Memory tied up in circular references between objects is notfreed. Some memory allocated by extension modules may not be freed. Someextensions may not work properly if their initialization routine is called morethan once; this can happen if an application callsPy_Initialize() andPy_FinalizeEx() more than once.

Raises anauditing eventcpython._PySys_ClearAuditHooks with no arguments.

Added in version 3.6.

voidPy_Finalize()¶: Μέρος τουΣταθερό ABI.
This is a backwards-compatible version ofPy_FinalizeEx() thatdisregards the return value.

Process-wide parameters¶

intPy_SetStandardStreamEncoding(constchar*encoding,constchar*errors)¶

This API is kept for backward compatibility: settingPyConfig.stdio_encoding andPyConfig.stdio_errorsshould be used instead, seePython Initialization Configuration.

This function should be called beforePy_Initialize(), if it iscalled at all. It specifies which encoding and error handling to usewith standard IO, with the same meanings as instr.encode().

It overridesPYTHONIOENCODING values, and allows embedding codeto control IO encoding when the environment variable does not work.

encoding and/orerrors may beNULL to usePYTHONIOENCODING and/or default values (depending on othersettings).

Note thatsys.stderr always uses the «backslashreplace» errorhandler, regardless of this (or any other) setting.

IfPy_FinalizeEx() is called, this function will need to be calledagain in order to affect subsequent calls toPy_Initialize().

Returns0 if successful, a nonzero value on error (e.g. calling after theinterpreter has already been initialized).

Added in version 3.4.

Αποσύρθηκε στην έκδοση 3.11.

voidPy_SetProgramName(constwchar_t*name)¶

Μέρος τουΣταθερό ABI.

This API is kept for backward compatibility: settingPyConfig.program_name should be used instead, seePythonInitialization Configuration.

This function should be called beforePy_Initialize() is called forthe first time, if it is called at all. It tells the interpreter the valueof theargv[0] argument to themain() function of the program(converted to wide characters).This is used byPy_GetPath() and some other functions below to findthe Python run-time libraries relative to the interpreter executable. Thedefault value is'python'. The argument should point to azero-terminated wide character string in static storage whose contents will notchange for the duration of the program’s execution. No code in the Pythoninterpreter will change the contents of this storage.

UsePy_DecodeLocale() to decode a bytes string to get awchar_t* string.

Αποσύρθηκε στην έκδοση 3.11.

wchar_t*Py_GetProgramName()¶

Μέρος τουΣταθερό ABI.

Return the program name set withPy_SetProgramName(), or the default.The returned string points into static storage; the caller should not modify itsvalue.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Άλλαξε στην έκδοση 3.10:It now returnsNULL if called beforePy_Initialize().

wchar_t*Py_GetPrefix()¶

Μέρος τουΣταθερό ABI.

Return theprefix for installed platform-independent files. This is derivedthrough a number of complicated rules from the program name set withPy_SetProgramName() and some environment variables; for example, if theprogram name is'/usr/local/bin/python', the prefix is'/usr/local'. Thereturned string points into static storage; the caller should not modify itsvalue. This corresponds to theprefix variable in the top-levelMakefile and the--prefix argument to theconfigurescript at build time. The value is available to Python code assys.prefix.It is only useful on Unix. See also the next function.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Άλλαξε στην έκδοση 3.10:It now returnsNULL if called beforePy_Initialize().

wchar_t*Py_GetExecPrefix()¶

Μέρος τουΣταθερό ABI.

Return theexec-prefix for installed platform-dependent files. This isderived through a number of complicated rules from the program name set withPy_SetProgramName() and some environment variables; for example, if theprogram name is'/usr/local/bin/python', the exec-prefix is'/usr/local'. The returned string points into static storage; the callershould not modify its value. This corresponds to theexec_prefixvariable in the top-levelMakefile and the--exec-prefixargument to theconfigure script at build time. The value isavailable to Python code assys.exec_prefix. It is only useful on Unix.

Background: The exec-prefix differs from the prefix when platform dependentfiles (such as executables and shared libraries) are installed in a differentdirectory tree. In a typical installation, platform dependent files may beinstalled in the/usr/local/plat subtree while platform independent maybe installed in/usr/local.

Generally speaking, a platform is a combination of hardware and softwarefamilies, e.g. Sparc machines running the Solaris 2.x operating system areconsidered the same platform, but Intel machines running Solaris 2.x are anotherplatform, and Intel machines running Linux are yet another platform. Differentmajor revisions of the same operating system generally also form differentplatforms. Non-Unix operating systems are a different story; the installationstrategies on those systems are so different that the prefix and exec-prefix aremeaningless, and set to the empty string. Note that compiled Python bytecodefiles are platform independent (but not independent from the Python version bywhich they were compiled!).

System administrators will know how to configure themount orautomount programs to share/usr/local between platformswhile having/usr/local/plat be a different filesystem for eachplatform.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Άλλαξε στην έκδοση 3.10:It now returnsNULL if called beforePy_Initialize().

wchar_t*Py_GetProgramFullPath()¶

Μέρος τουΣταθερό ABI.

Return the full program name of the Python executable; this is computed as aside-effect of deriving the default module search path from the program name(set byPy_SetProgramName() above). The returned string points intostatic storage; the caller should not modify its value. The value is availableto Python code assys.executable.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Άλλαξε στην έκδοση 3.10:It now returnsNULL if called beforePy_Initialize().

wchar_t*Py_GetPath()¶

Μέρος τουΣταθερό ABI.

Return the default module search path; this is computed from the program name(set byPy_SetProgramName() above) and some environment variables.The returned string consists of a series of directory names separated by aplatform dependent delimiter character. The delimiter character is':'on Unix and macOS,';' on Windows. The returned string points intostatic storage; the caller should not modify its value. The listsys.path is initialized with this value on interpreter startup; itcan be (and usually is) modified later to change the search path for loadingmodules.

This function should not be called beforePy_Initialize(), otherwiseit returnsNULL.

Άλλαξε στην έκδοση 3.10:It now returnsNULL if called beforePy_Initialize().

voidPy_SetPath(constwchar_t*)¶

Μέρος τουΣταθερό ABI από την έκδοση 3.7.

This API is kept for backward compatibility: settingPyConfig.module_search_paths andPyConfig.module_search_paths_set should be used instead, seePython Initialization Configuration.

Set the default module search path. If this function is called beforePy_Initialize(), thenPy_GetPath() won’t attempt to compute adefault search path but uses the one provided instead. This is useful ifPython is embedded by an application that has full knowledge of the locationof all modules. The path components should be separated by the platformdependent delimiter character, which is':' on Unix and macOS,';'on Windows.

This also causessys.executable to be set to the programfull path (seePy_GetProgramFullPath()) and forsys.prefix andsys.exec_prefix to be empty. It is up to the caller to modify theseif required after callingPy_Initialize().

UsePy_DecodeLocale() to decode a bytes string to get awchar_* string.

The path argument is copied internally, so the caller may free it after thecall completes.

Άλλαξε στην έκδοση 3.8:The program full path is now used forsys.executable, insteadof the program name.

Αποσύρθηκε στην έκδοση 3.11.

constchar*Py_GetVersion()¶

Μέρος τουΣταθερό ABI.

Return the version of this Python interpreter. This is a string that lookssomething like

"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55)\n[GCC 4.2.3]"

The first word (up to the first space character) is the current Python version;the first characters are the major and minor version separated by aperiod. The returned string points into static storage; the caller should notmodify its value. The value is available to Python code assys.version.

Thread State and the Global Interpreter Lock¶

The Python interpreter is not fully thread-safe. In order to supportmulti-threaded Python programs, there’s a global lock, called theglobalinterpreter lock orGIL, that must be held by the current thread beforeit can safely access Python objects. Without the lock, even the simplestoperations could cause problems in a multi-threaded program: for example, whentwo threads simultaneously increment the reference count of the same object, thereference count could end up being incremented only once instead of twice.

Therefore, the rule exists that only the thread that has acquired theGIL may operate on Python objects or call Python/C API functions.In order to emulate concurrency of execution, the interpreter regularlytries to switch threads (seesys.setswitchinterval()). The lock is alsoreleased around potentially blocking I/O operations like reading or writinga file, so that other Python threads can run in the meantime.

The Python interpreter keeps some thread-specific bookkeeping informationinside a data structure calledPyThreadState. There’s also oneglobal variable pointing to the currentPyThreadState: it canbe retrieved usingPyThreadState_Get().

Releasing the GIL from extension code¶

Most extension code manipulating theGIL has the following simplestructure:

Savethethreadstateinalocalvariable.Releasetheglobalinterpreterlock....DosomeblockingI/Ooperation...Reacquiretheglobalinterpreterlock.Restorethethreadstatefromthelocalvariable.

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

Py_BEGIN_ALLOW_THREADS...DosomeblockingI/Ooperation...Py_END_ALLOW_THREADS

ThePy_BEGIN_ALLOW_THREADS macro opens a new block and declares ahidden local variable; thePy_END_ALLOW_THREADS macro closes theblock.

The block above expands to the following code:

PyThreadState*_save;_save=PyEval_SaveThread();...DosomeblockingI/Ooperation...PyEval_RestoreThread(_save);

Here is how these functions work: the global interpreter lock is used to protect the pointer to thecurrent 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 threadstate in the global variable). Conversely, when acquiring the lock and restoringthe thread state, the lock must be acquired before storing the thread statepointer.

Σημείωση

Calling system I/O functions is the most common use case for releasingthe GIL, but it can also be useful before calling long-running computationswhich don’t need access to Python objects, such as compression orcryptographic functions operating over memory buffers. For example, thestandardzlib andhashlib modules release the GIL whencompressing or hashing data.

Non-Python created threads¶

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

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

ThePyGILState_Ensure() andPyGILState_Release() functions doall of the above automatically. The typical idiom for calling into Pythonfrom a C thread is:

PyGILState_STATEgstate;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 thePyGILState_* functions assume there is only one globalinterpreter (created automatically byPy_Initialize()). Pythonsupports the creation of additional interpreters (usingPy_NewInterpreter()), but mixing multiple interpreters and thePyGILState_* API is unsupported.

Cautions about fork()¶

Another important thing to note about threads is their behaviour in the faceof the Cfork() call. On most systems withfork(), after aprocess forks only the thread that issued the fork will exist. This has aconcrete impact both on how locks must be handled and on all stored statein CPython’s runtime.

The fact that only the «current» thread remainsmeans any locks held by other threads will never be released. Python solvesthis foros.fork() by acquiring the locks it uses internally beforethe fork, and releasing them afterwards. In addition, it resets anyLock Objects in the child. When extending or embedding Python, thereis no way to inform Python of additional (non-Python) locks that need to beacquired before or reset after a fork. OS facilities such aspthread_atfork() would need to be used to accomplish the same thing.Additionally, when extending or embedding Python, callingfork()directly rather than throughos.fork() (and returning to or callinginto Python) may result in a deadlock by one of Python’s internal locksbeing held by a thread that is defunct after the fork.PyOS_AfterFork_Child() tries to reset the necessary locks, but is notalways able to.

The fact that all other threads go away also means that CPython’sruntime state there must be cleaned up properly, whichos.fork()does. This means finalizing all otherPyThreadState objectsbelonging to the current interpreter and all otherPyInterpreterState objects. Due to this and the specialnature of the«main» interpreter,fork() should only be called in that interpreter’s «main»thread, where the CPython global runtime was originally initialized.The only exception is ifexec() will be called immediatelyafter.

High-level API¶

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

typePyInterpreterState¶

Μέρος τουΠεριορισμένο API (ως μια αδιαφανής κατασκευή).

This data structure represents the state shared by a number of cooperatingthreads. Threads belonging to the same interpreter share their moduleadministration and a few other internal items. There are no public members inthis structure.

Threads belonging to different interpreters initially share nothing, exceptprocess state like available memory, open file descriptors and such. The globalinterpreter lock is also shared by all threads, regardless of to whichinterpreter they belong.

typePyThreadState¶

Μέρος τουΠεριορισμένο API (ως μια αδιαφανής κατασκευή).

This data structure represents the state of a single thread. The only publicdata member is:

PyInterpreterState*interp¶: This thread’s interpreter state.

voidPyEval_InitThreads()¶

Μέρος τουΣταθερό ABI.

Deprecated function which does nothing.

In Python 3.6 and older, this function created the GIL if it didn’t exist.

Άλλαξε στην έκδοση 3.9:The function now does nothing.

Άλλαξε στην έκδοση 3.7:This function is now called byPy_Initialize(), so you don’thave to call it yourself anymore.

Άλλαξε στην έκδοση 3.2:This function cannot be called beforePy_Initialize() anymore.

Αποσύρθηκε στην έκδοση 3.9.

intPyEval_ThreadsInitialized()¶: Μέρος τουΣταθερό ABI.
Returns a non-zero value ifPyEval_InitThreads() has been called. Thisfunction can be called without holding the GIL, and therefore can be used toavoid calls to the locking API when running single-threaded.
Άλλαξε στην έκδοση 3.7:TheGIL is now initialized byPy_Initialize().
Αποσύρθηκε στην έκδοση 3.9.

PyThreadState*PyEval_SaveThread()¶: Μέρος τουΣταθερό ABI.
Release the global interpreter lock (if it has been created) and reset thethread state toNULL, returning the previous thread state (which is notNULL). If the lock has been created, the current thread must haveacquired it.

voidPyEval_RestoreThread(PyThreadState*tstate)¶: Μέρος τουΣταθερό ABI.
Acquire the global interpreter lock (if it has been created) and set thethread state totstate, which must not beNULL. If the lock has beencreated, the current thread must not have acquired it, otherwise deadlockensues.
Σημείωση
Calling this function from a thread when the runtime is finalizingwill terminate the thread, even if the thread was not created by Python.You can use_Py_IsFinalizing() orsys.is_finalizing() tocheck if the interpreter is in process of being finalized before callingthis function to avoid unwanted termination.

PyThreadState*PyThreadState_Get()¶: Μέρος τουΣταθερό ABI.
Return the current thread state. The global interpreter lock must be held.When the current thread state isNULL, this issues a fatal error (so thatthe caller needn’t check forNULL).

PyThreadState*PyThreadState_Swap(PyThreadState*tstate)¶: Μέρος τουΣταθερό ABI.
Swap the current thread state with the thread state given by the argumenttstate, which may beNULL. The global interpreter lock must be heldand is not released.

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

PyGILState_STATEPyGILState_Ensure()¶

Μέρος τουΣταθερό ABI.

Ensure that the current thread is ready to call the Python C API regardlessof the current state of Python, or of the global interpreter lock. This maybe called as many times as desired by a thread as long as each call ismatched with a call toPyGILState_Release(). In general, otherthread-related APIs may be used betweenPyGILState_Ensure() andPyGILState_Release() calls as long as the thread state is restored toits previous state before the Release(). For example, normal usage of thePy_BEGIN_ALLOW_THREADS andPy_END_ALLOW_THREADS macros isacceptable.

The return value is an opaque «handle» to the thread state whenPyGILState_Ensure() was called, and must be passed toPyGILState_Release() to ensure Python is left in the same state. Eventhough recursive calls are allowed, these handlescannot be shared - eachunique call toPyGILState_Ensure() must save the handle for its calltoPyGILState_Release().

When the function returns, the current thread will hold the GIL and be ableto call arbitrary Python code. Failure is a fatal error.

Σημείωση

Calling this function from a thread when the runtime is finalizingwill terminate the thread, even if the thread was not created by Python.You can use_Py_IsFinalizing() orsys.is_finalizing() tocheck if the interpreter is in process of being finalized before callingthis function to avoid unwanted termination.

voidPyGILState_Release(PyGILState_STATE)¶

Μέρος τουΣταθερό ABI.

Release any resources previously acquired. After this call, Python’s state willbe the same as it was prior to the correspondingPyGILState_Ensure() call(but generally this state will be unknown to the caller, hence the use of theGILState API).

Every call toPyGILState_Ensure() must be matched by a call toPyGILState_Release() on the same thread.

PyThreadState*PyGILState_GetThisThreadState()¶: Μέρος τουΣταθερό ABI.
Get the current thread state for this thread. May returnNULL if noGILState API has been used on the current thread. Note that the main threadalways has such a thread-state, even if no auto-thread-state call has beenmade on the main thread. This is mainly a helper/diagnostic function.

intPyGILState_Check()¶: Return1 if the current thread is holding the GIL and0 otherwise.This function can be called from any thread at any time.Only if it has had its Python thread state initialized and currently isholding the GIL will it return1.This is mainly a helper/diagnostic function. It can be usefulfor example in callback contexts or memory allocation functions whenknowing that the GIL is locked can allow the caller to perform sensitiveactions or otherwise behave differently.
Added in version 3.4.

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

Py_BEGIN_ALLOW_THREADS¶: Μέρος τουΣταθερό ABI.
This macro expands to{PyThreadState*_save;_save=PyEval_SaveThread();.Note that it contains an opening brace; it must be matched with a followingPy_END_ALLOW_THREADS macro. See above for further discussion of thismacro.

Py_END_ALLOW_THREADS¶: Μέρος τουΣταθερό ABI.
This macro expands toPyEval_RestoreThread(_save);}. Note that it containsa closing brace; it must be matched with an earlierPy_BEGIN_ALLOW_THREADS macro. See above for further discussion ofthis macro.

Py_BLOCK_THREADS¶: Μέρος τουΣταθερό ABI.
This macro expands toPyEval_RestoreThread(_save);: it is equivalent toPy_END_ALLOW_THREADS without the closing brace.

Py_UNBLOCK_THREADS¶: Μέρος τουΣταθερό ABI.
This macro expands to_save=PyEval_SaveThread();: it is equivalent toPy_BEGIN_ALLOW_THREADS without the opening brace and variabledeclaration.

Low-level API¶

All of the following functions must be called afterPy_Initialize().

Άλλαξε στην έκδοση 3.7:Py_Initialize() now initializes theGIL.

PyInterpreterState*PyInterpreterState_New()¶

Μέρος τουΣταθερό ABI.

Create a new interpreter state object. The global interpreter lock need notbe held, but may be held if it is necessary to serialize calls to thisfunction.

Raises anauditing eventcpython.PyInterpreterState_New with no arguments.

voidPyInterpreterState_Clear(PyInterpreterState*interp)¶

Μέρος τουΣταθερό ABI.

Reset all information in an interpreter state object. The global interpreterlock must be held.

Raises anauditing eventcpython.PyInterpreterState_Clear with no arguments.

voidPyInterpreterState_Delete(PyInterpreterState*interp)¶: Μέρος τουΣταθερό ABI.
Destroy an interpreter state object. The global interpreter lock need not beheld. The interpreter state must have been reset with a previous call toPyInterpreterState_Clear().

PyThreadState*PyThreadState_New(PyInterpreterState*interp)¶: Μέρος τουΣταθερό ABI.
Create a new thread state object belonging to the given interpreter object.The global interpreter lock need not be held, but may be held if it isnecessary to serialize calls to this function.

voidPyThreadState_Clear(PyThreadState*tstate)¶: Μέρος τουΣταθερό ABI.
Reset all information in a thread state object. The global interpreter lockmust be held.
Άλλαξε στην έκδοση 3.9:This function now calls thePyThreadState.on_delete callback.Previously, that happened inPyThreadState_Delete().

voidPyThreadState_Delete(PyThreadState*tstate)¶: Μέρος τουΣταθερό ABI.
Destroy a thread state object. The global interpreter lock need not be held.The thread state must have been reset with a previous call toPyThreadState_Clear().

voidPyThreadState_DeleteCurrent(void)¶: Destroy the current thread state and release the global interpreter lock.LikePyThreadState_Delete(), the global interpreter lock mustbe held. The thread state must have been reset with a previous calltoPyThreadState_Clear().

PyFrameObject*PyThreadState_GetFrame(PyThreadState*tstate)¶

Μέρος τουΣταθερό ABI από την έκδοση 3.10.

Get the current frame of the Python thread statetstate.

Return astrong reference. ReturnNULL if no frame is currentlyexecuting.

Sub-interpreter support¶

While in most uses, you will only embed a single Python interpreter, thereare cases where you need to create several independent interpreters in thesame process and perhaps even in the same thread. Sub-interpreters allowyou 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 signalhandling. It is also responsible for execution during runtime initialization andis usually the active interpreter during runtime finalization. ThePyInterpreterState_Main() function returns a pointer to its state.

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

typePyInterpreterConfig¶

Structure containing most parameters to configure a sub-interpreter.Its values are used only inPy_NewInterpreterFromConfig() andnever modified by the runtime.

Added in version 3.12.

Structure fields:

intuse_main_obmalloc¶

If this is0 then the sub-interpreter will use its own«object» allocator state.Otherwise it will use (share) the main interpreter’s.

If this is0 thencheck_multi_interp_extensionsmust be1 (non-zero).If this is1 thengilmust not bePyInterpreterConfig_OWN_GIL.

intallow_fork¶

If this is0 then the runtime will not support forking theprocess in any thread where the sub-interpreter is currently active.Otherwise fork is unrestricted.

Note that thesubprocess module still workswhen fork is disallowed.

intallow_exec¶

If this is0 then the runtime will not support replacing thecurrent process via exec (e.g.os.execv()) in any threadwhere the sub-interpreter is currently active.Otherwise exec is unrestricted.

Note that thesubprocess module still workswhen exec is disallowed.

intallow_threads¶: If this is0 then the sub-interpreter’sthreading modulewon’t create threads.Otherwise threads are allowed.

intallow_daemon_threads¶: If this is0 then the sub-interpreter’sthreading modulewon’t create daemon threads.Otherwise daemon threads are allowed (as long asallow_threads is non-zero).

intcheck_multi_interp_extensions¶

If this is0 then all extension modules may be imported,including legacy (single-phase init) modules,in any thread where the sub-interpreter is currently active.Otherwise only multi-phase init extension modules(seePEP 489) may be imported.(Also seePy_mod_multiple_interpreters.)

This must be1 (non-zero) ifuse_main_obmalloc is0.

intgil¶

This determines the operation of the GIL for the sub-interpreter.It may be one of the following:

PyInterpreterConfig_DEFAULT_GIL¶: Use the default selection (PyInterpreterConfig_SHARED_GIL).

PyInterpreterConfig_SHARED_GIL¶: Use (share) the main interpreter’s GIL.

PyInterpreterConfig_OWN_GIL¶: Use the sub-interpreter’s own GIL.

If this isPyInterpreterConfig_OWN_GIL thenPyInterpreterConfig.use_main_obmalloc must be0.

PyStatusPy_NewInterpreterFromConfig(PyThreadState**tstate_p,constPyInterpreterConfig*config)¶

Create a new sub-interpreter. This is an (almost) totally separate environmentfor the execution of Python code. In particular, the new interpreter hasseparate, independent versions of all imported modules, including thefundamental modulesbuiltins,__main__ andsys. Thetable of loaded modules (sys.modules) and the module search path(sys.path) are also separate. The new environment has nosys.argvvariable. It has new standard I/O stream file objectssys.stdin,sys.stdout andsys.stderr (however these refer to the same underlyingfile descriptors).

The givenconfig controls the options with which the interpreteris initialized.

Upon success,tstate_p will be set to the first thread statecreated in the newsub-interpreter. This thread state is made in the current thread state.Note that no actual thread is created; see the discussion of thread statesbelow. If creation of the new interpreter is unsuccessful,tstate_p is set toNULL;no exception is set since the exception state is stored in thecurrent thread state and there may not be a current thread state.

Like all other Python/C API functions, the global interpreter lockmust be held before calling this function and is still held when itreturns. Likewise a current thread state must be set on entry. Onsuccess, the returned thread state will be set as current. If thesub-interpreter is created with its own GIL then the GIL of thecalling interpreter will be released. When the function returns,the new interpreter’s GIL will be held by the current thread andthe previously interpreter’s GIL will remain released here.

Added in version 3.12.

Sub-interpreters are most effective when isolated from each other,with certain functionality restricted:

PyInterpreterConfigconfig={.use_main_obmalloc=0,.allow_fork=0,.allow_exec=0,.allow_threads=1,.allow_daemon_threads=0,.check_multi_interp_extensions=1,.gil=PyInterpreterConfig_OWN_GIL,};PyThreadState*tstate=NULL;PyStatusstatus=Py_NewInterpreterFromConfig(&tstate,&config);if(PyStatus_Exception(status)){Py_ExitStatusException(status);}

Note that the config is used only briefly and does not get modified.During initialization the config’s values are converted into variousPyInterpreterState values. A read-only copy of the configmay be stored internally on thePyInterpreterState.

Extension modules are shared between (sub-)interpreters as follows:

For modules using multi-phase initialization,e.g.PyModule_FromDefAndSpec(), a separate module object iscreated and initialized for each interpreter.Only C-level static and global variables are shared between thesemodule objects.
For modules using single-phase initialization,e.g.PyModule_Create(), the first time a particular extensionis imported, it is initialized normally, and a (shallow) copy of itsmodule’s dictionary is squirreled away.When the same extension is imported by another (sub-)interpreter, a newmodule is initialized and filled with the contents of this copy; theextension’sinit function is not called.Objects in the module’s dictionary thus end up shared across(sub-)interpreters, which might cause unwanted behavior (seeBugs and caveats below).
Note that this is different from what happens when an extension isimported after the interpreter has been completely re-initialized bycallingPy_FinalizeEx() andPy_Initialize(); in thatcase, the extension’sinitmodule functionis called again.As with multi-phase initialization, this means that only C-level staticand global variables are shared between these modules.

PyThreadState*Py_NewInterpreter(void)¶: Μέρος τουΣταθερό ABI.
Create a new sub-interpreter. This is essentially just a wrapperaroundPy_NewInterpreterFromConfig() with a config thatpreserves the existing behavior. The result is an unisolatedsub-interpreter that shares the main interpreter’s GIL, allowsfork/exec, allows daemon threads, and allows single-phase initmodules.

voidPy_EndInterpreter(PyThreadState*tstate)¶

Μέρος τουΣταθερό ABI.

Destroy the (sub-)interpreter represented by the given thread state.The given thread state must be the current thread state. See thediscussion of thread states below. When the call returns,the current thread state isNULL. All thread states associatedwith this interpreter are destroyed. The global interpreter lockused by the target interpreter must be held before calling thisfunction. No GIL is held when it returns.

Py_FinalizeEx() will destroy all sub-interpreters thathaven’t been explicitly destroyed at that point.

A Per-Interpreter GIL¶

UsingPy_NewInterpreterFromConfig() you can createa sub-interpreter that is completely isolated from other interpreters,including having its own GIL. The most important benefit of thisisolation is that such an interpreter can execute Python code withoutbeing blocked by other interpreters or blocking any others. Thus asingle Python process can truly take advantage of multiple CPU coreswhen running Python code. The isolation also encourages a differentapproach to concurrency than that of just using threads.(SeePEP 554.)

Using an isolated interpreter requires vigilance in preserving thatisolation. That especially means not sharing any objects or mutablestate without guarantees about thread-safety. Even objects that areotherwise immutable (e.g.None,(1,5)) can’t normally be sharedbecause of the refcount. One simple but less-efficient approach aroundthis is to use a global lock around all use of some state (or object).Alternately, effectively immutable objects (like integers or strings)can be made safe in spite of their refcounts by making them «immortal».In fact, this has been done for the builtin singletons, small integers,and a number of other builtin objects.

If you preserve isolation then you will have access to proper multi-corecomputing without the complications that come with free-threading.Failure to preserve isolation will expose you to the full consequencesof free-threading, including races and hard-to-debug crashes.

Aside from that, one of the main challenges of using multiple isolatedinterpreters is how to communicate between them safely (not breakisolation) and efficiently. The runtime and stdlib do not provideany standard approach to this yet. A future stdlib module would helpmitigate the effort of preserving isolation and expose effective toolsfor communicating (and sharing) data between interpreters.

Added in version 3.12.

Bugs and caveats¶

Because sub-interpreters (and the main interpreter) are part of the sameprocess, the insulation between them isn’t perfect — for example, usinglow-level file operations likeos.close() they can(accidentally or maliciously) affect each other’s open files. Because of theway extensions are shared between (sub-)interpreters, some extensions may notwork properly; this is especially likely when using single-phase initializationor (static) global variables.It is possible to insert objects created in one sub-interpreter intoa 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 importoperations executed by such objects may affect the wrong (sub-)interpreter’sdictionary of loaded modules. It is equally important to avoid sharingobjects from which the above are reachable.

Also note that combining this functionality withPyGILState_* APIsis delicate, because these APIs assume a bijection between Python thread statesand 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 pairof matchingPyGILState_Ensure() andPyGILState_Release() calls.Furthermore, extensions (such asctypes) using these APIs to allow callingof Python code from non-Python created threads will probably be broken when usingsub-interpreters.

Asynchronous Notifications¶

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

intPy_AddPendingCall(int(*func)(void*),void*arg)¶

Μέρος τουΣταθερό ABI.

Schedule a function to be called from the main interpreter thread. Onsuccess,0 is returned andfunc is queued for being called in themain thread. On failure,-1 is returned without setting any exception.

When successfully queued,func will beeventually called from themain interpreter thread with the argumentarg. It will be calledasynchronously with respect to normally running Python code, but withboth these conditions met:

on abytecode boundary;
with the main thread holding theglobal interpreter lock(func can therefore use the full C API).

func must return0 on success, or-1 on failure with an exceptionset.func won’t be interrupted to perform another asynchronousnotification recursively, but it can still be interrupted to switchthreads if the global interpreter lock is released.

This function doesn’t need a current thread state to run, and it doesn’tneed the global interpreter lock.

To call this function in a subinterpreter, the caller must hold the GIL.Otherwise, the functionfunc can be scheduled to be called from the wronginterpreter.

Προειδοποίηση

This is a low-level function, only useful for very special cases.There is no guarantee thatfunc will be called as quick aspossible. If the main thread is busy executing a system call,func won’t be called before the system call returns. Thisfunction is generallynot suitable for calling Python code fromarbitrary C threads. Instead, use thePyGILState API.

Added in version 3.1.

Άλλαξε στην έκδοση 3.9:If this function is called in a subinterpreter, the functionfunc isnow scheduled to be called from the subinterpreter, rather than beingcalled from the main interpreter. Each subinterpreter now has its ownlist of scheduled calls.

Profiling and Tracing¶

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

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

typedefint(*Py_tracefunc)(PyObject*obj,PyFrameObject*frame,intwhat,PyObject*arg)¶

The type of the trace function registered usingPyEval_SetProfile() andPyEval_SetTrace(). The first parameter is the object passed to theregistration function asobj,frame is the frame object to which the eventpertains,what is one of the constantsPyTrace_CALL,PyTrace_EXCEPTION,PyTrace_LINE,PyTrace_RETURN,PyTrace_C_CALL,PyTrace_C_EXCEPTION,PyTrace_C_RETURN,orPyTrace_OPCODE, andarg depends on the value ofwhat:

Value ofwhat	Meaning ofarg
`PyTrace_CALL`	Always`Py_None`.
`PyTrace_EXCEPTION`	Exception information as returned by`sys.exc_info()`.
`PyTrace_LINE`	Always`Py_None`.
`PyTrace_RETURN`	Value being returned to the caller,or`NULL` if caused by an exception.
`PyTrace_C_CALL`	Function object being called.
`PyTrace_C_EXCEPTION`	Function object being called.
`PyTrace_C_RETURN`	Function object being called.
`PyTrace_OPCODE`	Always`Py_None`.

intPyTrace_CALL¶: The value of thewhat parameter to aPy_tracefunc function when a newcall to a function or method is being reported, or a new entry into a generator.Note that the creation of the iterator for a generator function is not reportedas there is no control transfer to the Python bytecode in the correspondingframe.

intPyTrace_EXCEPTION¶: The value of thewhat parameter to aPy_tracefunc function when anexception has been raised. The callback function is called with this value forwhat when after any bytecode is processed after which the exception becomesset within the frame being executed. The effect of this is that as exceptionpropagation causes the Python stack to unwind, the callback is called uponreturn to each frame as the exception propagates. Only trace functions receivesthese events; they are not needed by the profiler.

intPyTrace_LINE¶: The value passed as thewhat parameter to aPy_tracefunc function(but not a profiling function) when a line-number event is being reported.It may be disabled for a frame by settingf_trace_lines to0 on that frame.

intPyTrace_RETURN¶: The value for thewhat parameter toPy_tracefunc functions when acall is about to return.

intPyTrace_C_CALL¶: The value for thewhat parameter toPy_tracefunc functions when a Cfunction is about to be called.

intPyTrace_C_EXCEPTION¶: The value for thewhat parameter toPy_tracefunc functions when a Cfunction has raised an exception.

intPyTrace_C_RETURN¶: The value for thewhat parameter toPy_tracefunc functions when a Cfunction has returned.

intPyTrace_OPCODE¶: The value for thewhat parameter toPy_tracefunc functions (but notprofiling functions) when a new opcode is about to be executed. This event isnot emitted by default: it must be explicitly requested by settingf_trace_opcodes to1 on the frame.

voidPyEval_SetProfile(Py_tracefuncfunc,PyObject*obj)¶

Set the profiler function tofunc. Theobj parameter is passed to thefunction as its first parameter, and may be any Python object, orNULL. Ifthe profile function needs to maintain state, using a different value forobjfor each thread provides a convenient and thread-safe place to store it. Theprofile function is called for all monitored events exceptPyTrace_LINEPyTrace_OPCODE andPyTrace_EXCEPTION.

See also thesys.setprofile() function.

The caller must hold theGIL.

voidPyEval_SetProfileAllThreads(Py_tracefuncfunc,PyObject*obj)¶

LikePyEval_SetProfile() but sets the profile function in all running threadsbelonging to the current interpreter instead of the setting it only on the current thread.

The caller must hold theGIL.

AsPyEval_SetProfile(), this function ignores any exceptions raised whilesetting the profile functions in all threads.

Added in version 3.12.

voidPyEval_SetTrace(Py_tracefuncfunc,PyObject*obj)¶

Set the tracing function tofunc. This is similar toPyEval_SetProfile(), except the tracing function does receive line-numberevents and per-opcode events, but does not receive any event related to C functionobjects being called. Any trace function registered usingPyEval_SetTrace()will not receivePyTrace_C_CALL,PyTrace_C_EXCEPTION orPyTrace_C_RETURN as a value for thewhat parameter.

Advanced Debugger Support¶

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

PyInterpreterState*PyInterpreterState_Head()¶: Return the interpreter state object at the head of the list of all such objects.

PyInterpreterState*PyInterpreterState_Main()¶: Return the main interpreter state object.

PyInterpreterState*PyInterpreterState_Next(PyInterpreterState*interp)¶: Return the next interpreter state object afterinterp from the list of allsuch objects.

PyThreadState*PyInterpreterState_ThreadHead(PyInterpreterState*interp)¶: Return the pointer to the firstPyThreadState object in the list ofthreads associated with the interpreterinterp.

PyThreadState*PyThreadState_Next(PyThreadState*tstate)¶: Return the next thread state object aftertstate from the list of all suchobjects belonging to the samePyInterpreterState object.

Thread Local Storage Support¶

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

The GIL doesnot need to be held when calling these functions; they supplytheir own locking.

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

Σημείωση

None of these API functions handle memory management on behalf of thevoid* values. You need to allocate and deallocate them yourself.If thevoid* values happen to bePyObject*, thesefunctions 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 theCPython interpreter. This API uses a new typePy_tss_t instead ofint to represent thread keys.

Added in version 3.7.

Δείτε επίσης

«A New C-API for Thread-Local Storage in CPython» (PEP 539)

typePy_tss_t¶

This data structure represents the state of a thread key, the definition ofwhich may depend on the underlying TLS implementation, and it has aninternal field representing the key’s initialization state. There are nopublic members in this structure.

WhenPy_LIMITED_API is not defined, static allocation ofthis type byPy_tss_NEEDS_INIT is allowed.

Py_tss_NEEDS_INIT¶: This macro expands to the initializer forPy_tss_t variables.Note that this macro won’t be defined withPy_LIMITED_API.

Dynamic Allocation¶

Dynamic allocation of thePy_tss_t, required in extension modulesbuilt withPy_LIMITED_API, where static allocation of this typeis not possible due to its implementation being opaque at build time.

Py_tss_t*PyThread_tss_alloc()¶: Μέρος τουΣταθερό ABI από την έκδοση 3.7.
Return a value which is the same state as a value initialized withPy_tss_NEEDS_INIT, orNULL in the case of dynamic allocationfailure.

voidPyThread_tss_free(Py_tss_t*key)¶: Μέρος τουΣταθερό ABI από την έκδοση 3.7.
Free the givenkey allocated byPyThread_tss_alloc(), afterfirst callingPyThread_tss_delete() to ensure any associatedthread locals have been unassigned. This is a no-op if thekeyargument isNULL.
Σημείωση
A freed key becomes a dangling pointer. You should reset the key toNULL.

Methods¶

The parameterkey of these functions must not beNULL. Moreover, thebehaviors ofPyThread_tss_set() andPyThread_tss_get() areundefined if the givenPy_tss_t has not been initialized byPyThread_tss_create().

intPyThread_tss_is_created(Py_tss_t*key)¶: Μέρος τουΣταθερό ABI από την έκδοση 3.7.
Return a non-zero value if the givenPy_tss_t has been initializedbyPyThread_tss_create().

intPyThread_tss_create(Py_tss_t*key)¶: Μέρος τουΣταθερό ABI από την έκδοση 3.7.
Return a zero value on successful initialization of a TSS key. The behavioris undefined if the value pointed to by thekey argument is notinitialized byPy_tss_NEEDS_INIT. This function can be calledrepeatedly on the same key – calling it on an already initialized key is ano-op and immediately returns success.

voidPyThread_tss_delete(Py_tss_t*key)¶: Μέρος τουΣταθερό ABI από την έκδοση 3.7.
Destroy a TSS key to forget the values associated with the key across allthreads, and change the key’s initialization state to uninitialized. Adestroyed key is able to be initialized again byPyThread_tss_create(). This function can be called repeatedly onthe same key – calling it on an already destroyed key is a no-op.

intPyThread_tss_set(Py_tss_t*key,void*value)¶: Μέρος τουΣταθερό ABI από την έκδοση 3.7.
Return a zero value to indicate successfully associating avoid*value with a TSS key in the current thread. Each thread has a distinctmapping of the key to avoid* value.

void*PyThread_tss_get(Py_tss_t*key)¶: Μέρος τουΣταθερό ABI από την έκδοση 3.7.
Return thevoid* value associated with a TSS key in the currentthread. This returnsNULL if no value is associated with the key in thecurrent thread.

Thread Local Storage (TLS) API¶

Αποσύρθηκε στην έκδοση 3.7:This API is superseded byThread Specific Storage (TSS) API.

Σημείωση

This version of the API does not support platforms where the native TLS keyis defined in a way that cannot be safely cast toint. On such platforms,PyThread_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 notbe used in new code.

intPyThread_create_key()¶: Μέρος τουΣταθερό ABI.

voidPyThread_delete_key(intkey)¶: Μέρος τουΣταθερό ABI.

intPyThread_set_key_value(intkey,void*value)¶: Μέρος τουΣταθερό ABI.

void*PyThread_get_key_value(intkey)¶: Μέρος τουΣταθερό ABI.

voidPyThread_delete_key_value(intkey)¶: Μέρος τουΣταθερό ABI.

voidPyThread_ReInitTLS()¶: Μέρος τουΣταθερό ABI.

Movatterモバイル変換

Πλοήγηση

Initialization, Finalization, and Threads¶

Before Python Initialization¶

Global configuration variables¶

Initializing and finalizing the interpreter¶

Process-wide parameters¶

Thread State and the Global Interpreter Lock¶

Releasing the GIL from extension code¶

Non-Python created threads¶

Cautions about fork()¶

High-level API¶

Low-level API¶

Sub-interpreter support¶

A Per-Interpreter GIL¶

Bugs and caveats¶

Asynchronous Notifications¶

Profiling and Tracing¶

Advanced Debugger Support¶

Thread Local Storage Support¶

Thread Specific Storage (TSS) API¶

Dynamic Allocation¶

Methods¶

Thread Local Storage (TLS) API¶

Πίνακας περιεχομένων

Προηγούμενο θέμα

Επόμενο θέμα

Αυτή η Σελίδα

Πλοήγηση