/Doc/c-api/init.rst
ReStructuredText | 1021 lines | 722 code | 299 blank | 0 comment | 0 complexity | ce1182933f37f1ebb04aa105aa698a79 MD5 | raw file
1.. highlightlang:: c 2 3 4.. _initialization: 5 6***************************************** 7Initialization, Finalization, and Threads 8***************************************** 9 10 11.. cfunction:: void Py_Initialize() 12 13 .. index:: 14 single: Py_SetProgramName() 15 single: PyEval_InitThreads() 16 single: PyEval_ReleaseLock() 17 single: PyEval_AcquireLock() 18 single: modules (in module sys) 19 single: path (in module sys) 20 module: __builtin__ 21 module: __main__ 22 module: sys 23 triple: module; search; path 24 single: PySys_SetArgv() 25 single: Py_Finalize() 26 27 Initialize the Python interpreter. In an application embedding Python, this 28 should be called before using any other Python/C API functions; with the 29 exception of :cfunc:`Py_SetProgramName`, :cfunc:`PyEval_InitThreads`, 30 :cfunc:`PyEval_ReleaseLock`, and :cfunc:`PyEval_AcquireLock`. This initializes 31 the table of loaded modules (``sys.modules``), and creates the fundamental 32 modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. It also initializes 33 the module search path (``sys.path``). It does not set ``sys.argv``; use 34 :cfunc:`PySys_SetArgv` for that. This is a no-op when called for a second time 35 (without calling :cfunc:`Py_Finalize` first). There is no return value; it is a 36 fatal error if the initialization fails. 37 38 39.. cfunction:: void Py_InitializeEx(int initsigs) 40 41 This function works like :cfunc:`Py_Initialize` if *initsigs* is 1. If 42 *initsigs* is 0, it skips initialization registration of signal handlers, which 43 might be useful when Python is embedded. 44 45 .. versionadded:: 2.4 46 47 48.. cfunction:: int Py_IsInitialized() 49 50 Return true (nonzero) when the Python interpreter has been initialized, false 51 (zero) if not. After :cfunc:`Py_Finalize` is called, this returns false until 52 :cfunc:`Py_Initialize` is called again. 53 54 55.. cfunction:: void Py_Finalize() 56 57 Undo all initializations made by :cfunc:`Py_Initialize` and subsequent use of 58 Python/C API functions, and destroy all sub-interpreters (see 59 :cfunc:`Py_NewInterpreter` below) that were created and not yet destroyed since 60 the last call to :cfunc:`Py_Initialize`. Ideally, this frees all memory 61 allocated by the Python interpreter. This is a no-op when called for a second 62 time (without calling :cfunc:`Py_Initialize` again first). There is no return 63 value; errors during finalization are ignored. 64 65 This function is provided for a number of reasons. An embedding application 66 might want to restart Python without having to restart the application itself. 67 An application that has loaded the Python interpreter from a dynamically 68 loadable library (or DLL) might want to free all memory allocated by Python 69 before unloading the DLL. During a hunt for memory leaks in an application a 70 developer might want to free all memory allocated by Python before exiting from 71 the application. 72 73 **Bugs and caveats:** The destruction of modules and objects in modules is done 74 in random order; this may cause destructors (:meth:`__del__` methods) to fail 75 when they depend on other objects (even functions) or modules. Dynamically 76 loaded extension modules loaded by Python are not unloaded. Small amounts of 77 memory allocated by the Python interpreter may not be freed (if you find a leak, 78 please report it). Memory tied up in circular references between objects is not 79 freed. Some memory allocated by extension modules may not be freed. Some 80 extensions may not work properly if their initialization routine is called more 81 than once; this can happen if an application calls :cfunc:`Py_Initialize` and 82 :cfunc:`Py_Finalize` more than once. 83 84 85.. cfunction:: PyThreadState* Py_NewInterpreter() 86 87 .. index:: 88 module: __builtin__ 89 module: __main__ 90 module: sys 91 single: stdout (in module sys) 92 single: stderr (in module sys) 93 single: stdin (in module sys) 94 95 Create a new sub-interpreter. This is an (almost) totally separate environment 96 for the execution of Python code. In particular, the new interpreter has 97 separate, independent versions of all imported modules, including the 98 fundamental modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. The 99 table of loaded modules (``sys.modules``) and the module search path 100 (``sys.path``) are also separate. The new environment has no ``sys.argv`` 101 variable. It has new standard I/O stream file objects ``sys.stdin``, 102 ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying 103 :ctype:`FILE` structures in the C library). 104 105 The return value points to the first thread state created in the new 106 sub-interpreter. This thread state is made in the current thread state. 107 Note that no actual thread is created; see the discussion of thread states 108 below. If creation of the new interpreter is unsuccessful, *NULL* is 109 returned; no exception is set since the exception state is stored in the 110 current thread state and there may not be a current thread state. (Like all 111 other Python/C API functions, the global interpreter lock must be held before 112 calling this function and is still held when it returns; however, unlike most 113 other Python/C API functions, there needn't be a current thread state on 114 entry.) 115 116 .. index:: 117 single: Py_Finalize() 118 single: Py_Initialize() 119 120 Extension modules are shared between (sub-)interpreters as follows: the first 121 time a particular extension is imported, it is initialized normally, and a 122 (shallow) copy of its module's dictionary is squirreled away. When the same 123 extension is imported by another (sub-)interpreter, a new module is initialized 124 and filled with the contents of this copy; the extension's ``init`` function is 125 not called. Note that this is different from what happens when an extension is 126 imported after the interpreter has been completely re-initialized by calling 127 :cfunc:`Py_Finalize` and :cfunc:`Py_Initialize`; in that case, the extension's 128 ``initmodule`` function *is* called again. 129 130 .. index:: single: close() (in module os) 131 132 **Bugs and caveats:** Because sub-interpreters (and the main interpreter) are 133 part of the same process, the insulation between them isn't perfect --- for 134 example, using low-level file operations like :func:`os.close` they can 135 (accidentally or maliciously) affect each other's open files. Because of the 136 way extensions are shared between (sub-)interpreters, some extensions may not 137 work properly; this is especially likely when the extension makes use of 138 (static) global variables, or when the extension manipulates its module's 139 dictionary after its initialization. It is possible to insert objects created 140 in one sub-interpreter into a namespace of another sub-interpreter; this should 141 be done with great care to avoid sharing user-defined functions, methods, 142 instances or classes between sub-interpreters, since import operations executed 143 by such objects may affect the wrong (sub-)interpreter's dictionary of loaded 144 modules. (XXX This is a hard-to-fix bug that will be addressed in a future 145 release.) 146 147 Also note that the use of this functionality is incompatible with extension 148 modules such as PyObjC and ctypes that use the :cfunc:`PyGILState_\*` APIs (and 149 this is inherent in the way the :cfunc:`PyGILState_\*` functions work). Simple 150 things may work, but confusing behavior will always be near. 151 152 153.. cfunction:: void Py_EndInterpreter(PyThreadState *tstate) 154 155 .. index:: single: Py_Finalize() 156 157 Destroy the (sub-)interpreter represented by the given thread state. The given 158 thread state must be the current thread state. See the discussion of thread 159 states below. When the call returns, the current thread state is *NULL*. All 160 thread states associated with this interpreter are destroyed. (The global 161 interpreter lock must be held before calling this function and is still held 162 when it returns.) :cfunc:`Py_Finalize` will destroy all sub-interpreters that 163 haven't been explicitly destroyed at that point. 164 165 166.. cfunction:: void Py_SetProgramName(char *name) 167 168 .. index:: 169 single: Py_Initialize() 170 single: main() 171 single: Py_GetPath() 172 173 This function should be called before :cfunc:`Py_Initialize` is called for 174 the first time, if it is called at all. It tells the interpreter the value 175 of the ``argv[0]`` argument to the :cfunc:`main` function of the program. 176 This is used by :cfunc:`Py_GetPath` and some other functions below to find 177 the Python run-time libraries relative to the interpreter executable. The 178 default value is ``'python'``. The argument should point to a 179 zero-terminated character string in static storage whose contents will not 180 change for the duration of the program's execution. No code in the Python 181 interpreter will change the contents of this storage. 182 183 184.. cfunction:: char* Py_GetProgramName() 185 186 .. index:: single: Py_SetProgramName() 187 188 Return the program name set with :cfunc:`Py_SetProgramName`, or the default. 189 The returned string points into static storage; the caller should not modify its 190 value. 191 192 193.. cfunction:: char* Py_GetPrefix() 194 195 Return the *prefix* for installed platform-independent files. This is derived 196 through a number of complicated rules from the program name set with 197 :cfunc:`Py_SetProgramName` and some environment variables; for example, if the 198 program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The 199 returned string points into static storage; the caller should not modify its 200 value. This corresponds to the :makevar:`prefix` variable in the top-level 201 :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure` 202 script at build time. The value is available to Python code as ``sys.prefix``. 203 It is only useful on Unix. See also the next function. 204 205 206.. cfunction:: char* Py_GetExecPrefix() 207 208 Return the *exec-prefix* for installed platform-*dependent* files. This is 209 derived through a number of complicated rules from the program name set with 210 :cfunc:`Py_SetProgramName` and some environment variables; for example, if the 211 program name is ``'/usr/local/bin/python'``, the exec-prefix is 212 ``'/usr/local'``. The returned string points into static storage; the caller 213 should not modify its value. This corresponds to the :makevar:`exec_prefix` 214 variable in the top-level :file:`Makefile` and the :option:`--exec-prefix` 215 argument to the :program:`configure` script at build time. The value is 216 available to Python code as ``sys.exec_prefix``. It is only useful on Unix. 217 218 Background: The exec-prefix differs from the prefix when platform dependent 219 files (such as executables and shared libraries) are installed in a different 220 directory tree. In a typical installation, platform dependent files may be 221 installed in the :file:`/usr/local/plat` subtree while platform independent may 222 be installed in :file:`/usr/local`. 223 224 Generally speaking, a platform is a combination of hardware and software 225 families, e.g. Sparc machines running the Solaris 2.x operating system are 226 considered the same platform, but Intel machines running Solaris 2.x are another 227 platform, and Intel machines running Linux are yet another platform. Different 228 major revisions of the same operating system generally also form different 229 platforms. Non-Unix operating systems are a different story; the installation 230 strategies on those systems are so different that the prefix and exec-prefix are 231 meaningless, and set to the empty string. Note that compiled Python bytecode 232 files are platform independent (but not independent from the Python version by 233 which they were compiled!). 234 235 System administrators will know how to configure the :program:`mount` or 236 :program:`automount` programs to share :file:`/usr/local` between platforms 237 while having :file:`/usr/local/plat` be a different filesystem for each 238 platform. 239 240 241.. cfunction:: char* Py_GetProgramFullPath() 242 243 .. index:: 244 single: Py_SetProgramName() 245 single: executable (in module sys) 246 247 Return the full program name of the Python executable; this is computed as a 248 side-effect of deriving the default module search path from the program name 249 (set by :cfunc:`Py_SetProgramName` above). The returned string points into 250 static storage; the caller should not modify its value. The value is available 251 to Python code as ``sys.executable``. 252 253 254.. cfunction:: char* Py_GetPath() 255 256 .. index:: 257 triple: module; search; path 258 single: path (in module sys) 259 260 Return the default module search path; this is computed from the program name 261 (set by :cfunc:`Py_SetProgramName` above) and some environment variables. The 262 returned string consists of a series of directory names separated by a platform 263 dependent delimiter character. The delimiter character is ``':'`` on Unix and 264 Mac OS X, ``';'`` on Windows. The returned string points into static storage; 265 the caller should not modify its value. The value is available to Python code 266 as the list ``sys.path``, which may be modified to change the future search path 267 for loaded modules. 268 269 .. XXX should give the exact rules 270 271 272.. cfunction:: const char* Py_GetVersion() 273 274 Return the version of this Python interpreter. This is a string that looks 275 something like :: 276 277 "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]" 278 279 .. index:: single: version (in module sys) 280 281 The first word (up to the first space character) is the current Python version; 282 the first three characters are the major and minor version separated by a 283 period. The returned string points into static storage; the caller should not 284 modify its value. The value is available to Python code as ``sys.version``. 285 286 287.. cfunction:: const char* Py_GetBuildNumber() 288 289 Return a string representing the Subversion revision that this Python executable 290 was built from. This number is a string because it may contain a trailing 'M' 291 if Python was built from a mixed revision source tree. 292 293 .. versionadded:: 2.5 294 295 296.. cfunction:: const char* Py_GetPlatform() 297 298 .. index:: single: platform (in module sys) 299 300 Return the platform identifier for the current platform. On Unix, this is 301 formed from the "official" name of the operating system, converted to lower 302 case, followed by the major revision number; e.g., for Solaris 2.x, which is 303 also known as SunOS 5.x, the value is ``'sunos5'``. On Mac OS X, it is 304 ``'darwin'``. On Windows, it is ``'win'``. The returned string points into 305 static storage; the caller should not modify its value. The value is available 306 to Python code as ``sys.platform``. 307 308 309.. cfunction:: const char* Py_GetCopyright() 310 311 Return the official copyright string for the current Python version, for example 312 313 ``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'`` 314 315 .. index:: single: copyright (in module sys) 316 317 The returned string points into static storage; the caller should not modify its 318 value. The value is available to Python code as ``sys.copyright``. 319 320 321.. cfunction:: const char* Py_GetCompiler() 322 323 Return an indication of the compiler used to build the current Python version, 324 in square brackets, for example:: 325 326 "[GCC 2.7.2.2]" 327 328 .. index:: single: version (in module sys) 329 330 The returned string points into static storage; the caller should not modify its 331 value. The value is available to Python code as part of the variable 332 ``sys.version``. 333 334 335.. cfunction:: const char* Py_GetBuildInfo() 336 337 Return information about the sequence number and build date and time of the 338 current Python interpreter instance, for example :: 339 340 "#67, Aug 1 1997, 22:34:28" 341 342 .. index:: single: version (in module sys) 343 344 The returned string points into static storage; the caller should not modify its 345 value. The value is available to Python code as part of the variable 346 ``sys.version``. 347 348 349.. cfunction:: void PySys_SetArgv(int argc, char **argv) 350 351 .. index:: 352 single: main() 353 single: Py_FatalError() 354 single: argv (in module sys) 355 356 Set :data:`sys.argv` based on *argc* and *argv*. These parameters are 357 similar to those passed to the program's :cfunc:`main` function with the 358 difference that the first entry should refer to the script file to be 359 executed rather than the executable hosting the Python interpreter. If there 360 isn't a script that will be run, the first entry in *argv* can be an empty 361 string. If this function fails to initialize :data:`sys.argv`, a fatal 362 condition is signalled using :cfunc:`Py_FatalError`. 363 364 This function also prepends the executed script's path to :data:`sys.path`. 365 If no script is executed (in the case of calling ``python -c`` or just the 366 interactive interpreter), the empty string is used instead. 367 368 .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params; 369 check w/ Guido. 370 371 372.. cfunction:: void Py_SetPythonHome(char *home) 373 374 Set the default "home" directory, that is, the location of the standard 375 Python libraries. The libraries are searched in 376 :file:`{home}/lib/python{version}` and :file:`{home}/lib/python{version}`. 377 The argument should point to a zero-terminated character string in static 378 storage whose contents will not change for the duration of the program's 379 execution. No code in the Python interpreter will change the contents of 380 this storage. 381 382 383.. cfunction:: char* Py_GetPythonHome() 384 385 Return the default "home", that is, the value set by a previous call to 386 :cfunc:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME` 387 environment variable if it is set. 388 389 390.. _threads: 391 392Thread State and the Global Interpreter Lock 393============================================ 394 395.. index:: 396 single: global interpreter lock 397 single: interpreter lock 398 single: lock, interpreter 399 400The Python interpreter is not fully thread safe. In order to support 401multi-threaded Python programs, there's a global lock, called the :dfn:`global 402interpreter lock` or :dfn:`GIL`, that must be held by the current thread before 403it can safely access Python objects. Without the lock, even the simplest 404operations could cause problems in a multi-threaded program: for example, when 405two threads simultaneously increment the reference count of the same object, the 406reference count could end up being incremented only once instead of twice. 407 408.. index:: single: setcheckinterval() (in module sys) 409 410Therefore, the rule exists that only the thread that has acquired the global 411interpreter lock may operate on Python objects or call Python/C API functions. 412In order to support multi-threaded Python programs, the interpreter regularly 413releases and reacquires the lock --- by default, every 100 bytecode instructions 414(this can be changed with :func:`sys.setcheckinterval`). The lock is also 415released and reacquired around potentially blocking I/O operations like reading 416or writing a file, so that other threads can run while the thread that requests 417the I/O is waiting for the I/O operation to complete. 418 419.. index:: 420 single: PyThreadState 421 single: PyThreadState 422 423The Python interpreter needs to keep some bookkeeping information separate per 424thread --- for this it uses a data structure called :ctype:`PyThreadState`. 425There's one global variable, however: the pointer to the current 426:ctype:`PyThreadState` structure. Before the addition of :dfn:`thread-local 427storage` (:dfn:`TLS`) the current thread state had to be manipulated 428explicitly. 429 430This is easy enough in most cases. Most code manipulating the global 431interpreter lock has the following simple structure:: 432 433 Save the thread state in a local variable. 434 Release the global interpreter lock. 435 ...Do some blocking I/O operation... 436 Reacquire the global interpreter lock. 437 Restore the thread state from the local variable. 438 439This is so common that a pair of macros exists to simplify it:: 440 441 Py_BEGIN_ALLOW_THREADS 442 ...Do some blocking I/O operation... 443 Py_END_ALLOW_THREADS 444 445.. index:: 446 single: Py_BEGIN_ALLOW_THREADS 447 single: Py_END_ALLOW_THREADS 448 449The :cmacro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a 450hidden local variable; the :cmacro:`Py_END_ALLOW_THREADS` macro closes the 451block. Another advantage of using these two macros is that when Python is 452compiled without thread support, they are defined empty, thus saving the thread 453state and GIL manipulations. 454 455When thread support is enabled, the block above expands to the following code:: 456 457 PyThreadState *_save; 458 459 _save = PyEval_SaveThread(); 460 ...Do some blocking I/O operation... 461 PyEval_RestoreThread(_save); 462 463Using even lower level primitives, we can get roughly the same effect as 464follows:: 465 466 PyThreadState *_save; 467 468 _save = PyThreadState_Swap(NULL); 469 PyEval_ReleaseLock(); 470 ...Do some blocking I/O operation... 471 PyEval_AcquireLock(); 472 PyThreadState_Swap(_save); 473 474.. index:: 475 single: PyEval_RestoreThread() 476 single: errno 477 single: PyEval_SaveThread() 478 single: PyEval_ReleaseLock() 479 single: PyEval_AcquireLock() 480 481There are some subtle differences; in particular, :cfunc:`PyEval_RestoreThread` 482saves and restores the value of the global variable :cdata:`errno`, since the 483lock manipulation does not guarantee that :cdata:`errno` is left alone. Also, 484when thread support is disabled, :cfunc:`PyEval_SaveThread` and 485:cfunc:`PyEval_RestoreThread` don't manipulate the GIL; in this case, 486:cfunc:`PyEval_ReleaseLock` and :cfunc:`PyEval_AcquireLock` are not available. 487This is done so that dynamically loaded extensions compiled with thread support 488enabled can be loaded by an interpreter that was compiled with disabled thread 489support. 490 491The global interpreter lock is used to protect the pointer to the current thread 492state. When releasing the lock and saving the thread state, the current thread 493state pointer must be retrieved before the lock is released (since another 494thread could immediately acquire the lock and store its own thread state in the 495global variable). Conversely, when acquiring the lock and restoring the thread 496state, the lock must be acquired before storing the thread state pointer. 497 498It is important to note that when threads are created from C, they don't have 499the global interpreter lock, nor is there a thread state data structure for 500them. Such threads must bootstrap themselves into existence, by first 501creating a thread state data structure, then acquiring the lock, and finally 502storing their thread state pointer, before they can start using the Python/C 503API. When they are done, they should reset the thread state pointer, release 504the lock, and finally free their thread state data structure. 505 506Beginning with version 2.3, threads can now take advantage of the 507:cfunc:`PyGILState_\*` functions to do all of the above automatically. The 508typical idiom for calling into Python from a C thread is now:: 509 510 PyGILState_STATE gstate; 511 gstate = PyGILState_Ensure(); 512 513 /* Perform Python actions here. */ 514 result = CallSomeFunction(); 515 /* evaluate result */ 516 517 /* Release the thread. No Python API allowed beyond this point. */ 518 PyGILState_Release(gstate); 519 520Note that the :cfunc:`PyGILState_\*` functions assume there is only one global 521interpreter (created automatically by :cfunc:`Py_Initialize`). Python still 522supports the creation of additional interpreters (using 523:cfunc:`Py_NewInterpreter`), but mixing multiple interpreters and the 524:cfunc:`PyGILState_\*` API is unsupported. 525 526Another important thing to note about threads is their behaviour in the face 527of the C :cfunc:`fork` call. On most systems with :cfunc:`fork`, after a 528process forks only the thread that issued the fork will exist. That also 529means any locks held by other threads will never be released. Python solves 530this for :func:`os.fork` by acquiring the locks it uses internally before 531the fork, and releasing them afterwards. In addition, it resets any 532:ref:`lock-objects` in the child. When extending or embedding Python, there 533is no way to inform Python of additional (non-Python) locks that need to be 534acquired before or reset after a fork. OS facilities such as 535:cfunc:`posix_atfork` would need to be used to accomplish the same thing. 536Additionally, when extending or embedding Python, calling :cfunc:`fork` 537directly rather than through :func:`os.fork` (and returning to or calling 538into Python) may result in a deadlock by one of Python's internal locks 539being held by a thread that is defunct after the fork. 540:cfunc:`PyOS_AfterFork` tries to reset the necessary locks, but is not 541always able to. 542 543.. ctype:: PyInterpreterState 544 545 This data structure represents the state shared by a number of cooperating 546 threads. Threads belonging to the same interpreter share their module 547 administration and a few other internal items. There are no public members in 548 this structure. 549 550 Threads belonging to different interpreters initially share nothing, except 551 process state like available memory, open file descriptors and such. The global 552 interpreter lock is also shared by all threads, regardless of to which 553 interpreter they belong. 554 555 556.. ctype:: PyThreadState 557 558 This data structure represents the state of a single thread. The only public 559 data member is :ctype:`PyInterpreterState \*`:attr:`interp`, which points to 560 this thread's interpreter state. 561 562 563.. cfunction:: void PyEval_InitThreads() 564 565 .. index:: 566 single: PyEval_ReleaseLock() 567 single: PyEval_ReleaseThread() 568 single: PyEval_SaveThread() 569 single: PyEval_RestoreThread() 570 571 Initialize and acquire the global interpreter lock. It should be called in the 572 main thread before creating a second thread or engaging in any other thread 573 operations such as :cfunc:`PyEval_ReleaseLock` or 574 ``PyEval_ReleaseThread(tstate)``. It is not needed before calling 575 :cfunc:`PyEval_SaveThread` or :cfunc:`PyEval_RestoreThread`. 576 577 .. index:: single: Py_Initialize() 578 579 This is a no-op when called for a second time. It is safe to call this function 580 before calling :cfunc:`Py_Initialize`. 581 582 .. index:: module: thread 583 584 When only the main thread exists, no GIL operations are needed. This is a 585 common situation (most Python programs do not use threads), and the lock 586 operations slow the interpreter down a bit. Therefore, the lock is not 587 created initially. This situation is equivalent to having acquired the lock: 588 when there is only a single thread, all object accesses are safe. Therefore, 589 when this function initializes the global interpreter lock, it also acquires 590 it. Before the Python :mod:`thread` module creates a new thread, knowing 591 that either it has the lock or the lock hasn't been created yet, it calls 592 :cfunc:`PyEval_InitThreads`. When this call returns, it is guaranteed that 593 the lock has been created and that the calling thread has acquired it. 594 595 It is **not** safe to call this function when it is unknown which thread (if 596 any) currently has the global interpreter lock. 597 598 This function is not available when thread support is disabled at compile time. 599 600 601.. cfunction:: int PyEval_ThreadsInitialized() 602 603 Returns a non-zero value if :cfunc:`PyEval_InitThreads` has been called. This 604 function can be called without holding the GIL, and therefore can be used to 605 avoid calls to the locking API when running single-threaded. This function is 606 not available when thread support is disabled at compile time. 607 608 .. versionadded:: 2.4 609 610 611.. cfunction:: void PyEval_AcquireLock() 612 613 Acquire the global interpreter lock. The lock must have been created earlier. 614 If this thread already has the lock, a deadlock ensues. This function is not 615 available when thread support is disabled at compile time. 616 617 618.. cfunction:: void PyEval_ReleaseLock() 619 620 Release the global interpreter lock. The lock must have been created earlier. 621 This function is not available when thread support is disabled at compile time. 622 623 624.. cfunction:: void PyEval_AcquireThread(PyThreadState *tstate) 625 626 Acquire the global interpreter lock and set the current thread state to 627 *tstate*, which should not be *NULL*. The lock must have been created earlier. 628 If this thread already has the lock, deadlock ensues. This function is not 629 available when thread support is disabled at compile time. 630 631 632.. cfunction:: void PyEval_ReleaseThread(PyThreadState *tstate) 633 634 Reset the current thread state to *NULL* and release the global interpreter 635 lock. The lock must have been created earlier and must be held by the current 636 thread. The *tstate* argument, which must not be *NULL*, is only used to check 637 that it represents the current thread state --- if it isn't, a fatal error is 638 reported. This function is not available when thread support is disabled at 639 compile time. 640 641 642.. cfunction:: PyThreadState* PyEval_SaveThread() 643 644 Release the global interpreter lock (if it has been created and thread 645 support is enabled) and reset the thread state to *NULL*, returning the 646 previous thread state (which is not *NULL*). If the lock has been created, 647 the current thread must have acquired it. (This function is available even 648 when thread support is disabled at compile time.) 649 650 651.. cfunction:: void PyEval_RestoreThread(PyThreadState *tstate) 652 653 Acquire the global interpreter lock (if it has been created and thread 654 support is enabled) and set the thread state to *tstate*, which must not be 655 *NULL*. If the lock has been created, the current thread must not have 656 acquired it, otherwise deadlock ensues. (This function is available even 657 when thread support is disabled at compile time.) 658 659 660.. cfunction:: void PyEval_ReInitThreads() 661 662 This function is called from :cfunc:`PyOS_AfterFork` to ensure that newly 663 created child processes don't hold locks referring to threads which 664 are not running in the child process. 665 666 667The following macros are normally used without a trailing semicolon; look for 668example usage in the Python source distribution. 669 670 671.. cmacro:: Py_BEGIN_ALLOW_THREADS 672 673 This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``. 674 Note that it contains an opening brace; it must be matched with a following 675 :cmacro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this 676 macro. It is a no-op when thread support is disabled at compile time. 677 678 679.. cmacro:: Py_END_ALLOW_THREADS 680 681 This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains 682 a closing brace; it must be matched with an earlier 683 :cmacro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of 684 this macro. It is a no-op when thread support is disabled at compile time. 685 686 687.. cmacro:: Py_BLOCK_THREADS 688 689 This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to 690 :cmacro:`Py_END_ALLOW_THREADS` without the closing brace. It is a no-op when 691 thread support is disabled at compile time. 692 693 694.. cmacro:: Py_UNBLOCK_THREADS 695 696 This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to 697 :cmacro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable 698 declaration. It is a no-op when thread support is disabled at compile time. 699 700All of the following functions are only available when thread support is enabled 701at compile time, and must be called only when the global interpreter lock has 702been created. 703 704 705.. cfunction:: PyInterpreterState* PyInterpreterState_New() 706 707 Create a new interpreter state object. The global interpreter lock need not 708 be held, but may be held if it is necessary to serialize calls to this 709 function. 710 711 712.. cfunction:: void PyInterpreterState_Clear(PyInterpreterState *interp) 713 714 Reset all information in an interpreter state object. The global interpreter 715 lock must be held. 716 717 718.. cfunction:: void PyInterpreterState_Delete(PyInterpreterState *interp) 719 720 Destroy an interpreter state object. The global interpreter lock need not be 721 held. The interpreter state must have been reset with a previous call to 722 :cfunc:`PyInterpreterState_Clear`. 723 724 725.. cfunction:: PyThreadState* PyThreadState_New(PyInterpreterState *interp) 726 727 Create a new thread state object belonging to the given interpreter object. 728 The global interpreter lock need not be held, but may be held if it is 729 necessary to serialize calls to this function. 730 731 732.. cfunction:: void PyThreadState_Clear(PyThreadState *tstate) 733 734 Reset all information in a thread state object. The global interpreter lock 735 must be held. 736 737 738.. cfunction:: void PyThreadState_Delete(PyThreadState *tstate) 739 740 Destroy a thread state object. The global interpreter lock need not be held. 741 The thread state must have been reset with a previous call to 742 :cfunc:`PyThreadState_Clear`. 743 744 745.. cfunction:: PyThreadState* PyThreadState_Get() 746 747 Return the current thread state. The global interpreter lock must be held. 748 When the current thread state is *NULL*, this issues a fatal error (so that 749 the caller needn't check for *NULL*). 750 751 752.. cfunction:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate) 753 754 Swap the current thread state with the thread state given by the argument 755 *tstate*, which may be *NULL*. The global interpreter lock must be held. 756 757 758.. cfunction:: PyObject* PyThreadState_GetDict() 759 760 Return a dictionary in which extensions can store thread-specific state 761 information. Each extension should use a unique key to use to store state in 762 the dictionary. It is okay to call this function when no current thread state 763 is available. If this function returns *NULL*, no exception has been raised and 764 the caller should assume no current thread state is available. 765 766 .. versionchanged:: 2.3 767 Previously this could only be called when a current thread is active, and *NULL* 768 meant that an exception was raised. 769 770 771.. cfunction:: int PyThreadState_SetAsyncExc(long id, PyObject *exc) 772 773 Asynchronously raise an exception in a thread. The *id* argument is the thread 774 id of the target thread; *exc* is the exception object to be raised. This 775 function does not steal any references to *exc*. To prevent naive misuse, you 776 must write your own C extension to call this. Must be called with the GIL held. 777 Returns the number of thread states modified; this is normally one, but will be 778 zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending 779 exception (if any) for the thread is cleared. This raises no exceptions. 780 781 .. versionadded:: 2.3 782 783 784.. cfunction:: PyGILState_STATE PyGILState_Ensure() 785 786 Ensure that the current thread is ready to call the Python C API regardless 787 of the current state of Python, or of the global interpreter lock. This may 788 be called as many times as desired by a thread as long as each call is 789 matched with a call to :cfunc:`PyGILState_Release`. In general, other 790 thread-related APIs may be used between :cfunc:`PyGILState_Ensure` and 791 :cfunc:`PyGILState_Release` calls as long as the thread state is restored to 792 its previous state before the Release(). For example, normal usage of the 793 :cmacro:`Py_BEGIN_ALLOW_THREADS` and :cmacro:`Py_END_ALLOW_THREADS` macros is 794 acceptable. 795 796 The return value is an opaque "handle" to the thread state when 797 :cfunc:`PyGILState_Ensure` was called, and must be passed to 798 :cfunc:`PyGILState_Release` to ensure Python is left in the same state. Even 799 though recursive calls are allowed, these handles *cannot* be shared - each 800 unique call to :cfunc:`PyGILState_Ensure` must save the handle for its call 801 to :cfunc:`PyGILState_Release`. 802 803 When the function returns, the current thread will hold the GIL. Failure is a 804 fatal error. 805 806 .. versionadded:: 2.3 807 808 809.. cfunction:: void PyGILState_Release(PyGILState_STATE) 810 811 Release any resources previously acquired. After this call, Python's state will 812 be the same as it was prior to the corresponding :cfunc:`PyGILState_Ensure` call 813 (but generally this state will be unknown to the caller, hence the use of the 814 GILState API.) 815 816 Every call to :cfunc:`PyGILState_Ensure` must be matched by a call to 817 :cfunc:`PyGILState_Release` on the same thread. 818 819 .. versionadded:: 2.3 820 821 822.. _profiling: 823 824Profiling and Tracing 825===================== 826 827.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 828 829 830The Python interpreter provides some low-level support for attaching profiling 831and execution tracing facilities. These are used for profiling, debugging, and 832coverage analysis tools. 833 834Starting with Python 2.2, the implementation of this facility was substantially 835revised, and an interface from C was added. This C interface allows the 836profiling or tracing code to avoid the overhead of calling through Python-level 837callable objects, making a direct C function call instead. The essential 838attributes of the facility have not changed; the interface allows trace 839functions to be installed per-thread, and the basic events reported to the trace 840function are the same as had been reported to the Python-level trace functions 841in previous versions. 842 843 844.. ctype:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg) 845 846 The type of the trace function registered using :cfunc:`PyEval_SetProfile` and 847 :cfunc:`PyEval_SetTrace`. The first parameter is the object passed to the 848 registration function as *obj*, *frame* is the frame object to which the event 849 pertains, *what* is one of the constants :const:`PyTrace_CALL`, 850 :const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`, 851 :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, or 852 :const:`PyTrace_C_RETURN`, and *arg* depends on the value of *what*: 853 854 +------------------------------+--------------------------------------+ 855 | Value of *what* | Meaning of *arg* | 856 +==============================+======================================+ 857 | :const:`PyTrace_CALL` | Always *NULL*. | 858 +------------------------------+--------------------------------------+ 859 | :const:`PyTrace_EXCEPTION` | Exception information as returned by | 860 | | :func:`sys.exc_info`. | 861 +------------------------------+--------------------------------------+ 862 | :const:`PyTrace_LINE` | Always *NULL*. | 863 +------------------------------+--------------------------------------+ 864 | :const:`PyTrace_RETURN` | Value being returned to the caller. | 865 +------------------------------+--------------------------------------+ 866 | :const:`PyTrace_C_CALL` | Name of function being called. | 867 +------------------------------+--------------------------------------+ 868 | :const:`PyTrace_C_EXCEPTION` | Always *NULL*. | 869 +------------------------------+--------------------------------------+ 870 | :const:`PyTrace_C_RETURN` | Always *NULL*. | 871 +------------------------------+--------------------------------------+ 872 873 874.. cvar:: int PyTrace_CALL 875 876 The value of the *what* parameter to a :ctype:`Py_tracefunc` function when a new 877 call to a function or method is being reported, or a new entry into a generator. 878 Note that the creation of the iterator for a generator function is not reported 879 as there is no control transfer to the Python bytecode in the corresponding 880 frame. 881 882 883.. cvar:: int PyTrace_EXCEPTION 884 885 The value of the *what* parameter to a :ctype:`Py_tracefunc` function when an 886 exception has been raised. The callback function is called with this value for 887 *what* when after any bytecode is processed after which the exception becomes 888 set within the frame being executed. The effect of this is that as exception 889 propagation causes the Python stack to unwind, the callback is called upon 890 return to each frame as the exception propagates. Only trace functions receives 891 these events; they are not needed by the profiler. 892 893 894.. cvar:: int PyTrace_LINE 895 896 The value passed as the *what* parameter to a trace function (but not a 897 profiling function) when a line-number event is being reported. 898 899 900.. cvar:: int PyTrace_RETURN 901 902 The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a 903 call is returning without propagating an exception. 904 905 906.. cvar:: int PyTrace_C_CALL 907 908 The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a C 909 function is about to be called. 910 911 912.. cvar:: int PyTrace_C_EXCEPTION 913 914 The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a C 915 function has thrown an exception. 916 917 918.. cvar:: int PyTrace_C_RETURN 919 920 The value for the *what* parameter to :ctype:`Py_tracefunc` functions when a C 921 function has returned. 922 923 924.. cfunction:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj) 925 926 Set the profiler function to *func*. The *obj* parameter is passed to the 927 function as its first parameter, and may be any Python object, or *NULL*. If 928 the profile function needs to maintain state, using a different value for *obj* 929 for each thread provides a convenient and thread-safe place to store it. The 930 profile function is called for all monitored events except the line-number 931 events. 932 933 934.. cfunction:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj) 935 936 Set the tracing function to *func*. This is similar to 937 :cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number 938 events. 939 940.. cfunction:: PyObject* PyEval_GetCallStats(PyObject *self) 941 942 Return a tuple of function call counts. There are constants defined for the 943 positions within the tuple: 944 945 +-------------------------------+-------+ 946 | Name | Value | 947 +===============================+=======+ 948 | :const:`PCALL_ALL` | 0 | 949 +-------------------------------+-------+ 950 | :const:`PCALL_FUNCTION` | 1 | 951 +-------------------------------+-------+ 952 | :const:`PCALL_FAST_FUNCTION` | 2 | 953 +-------------------------------+-------+ 954 | :const:`PCALL_FASTER_FUNCTION`| 3 | 955 +-------------------------------+-------+ 956 | :const:`PCALL_METHOD` | 4 | 957 +-------------------------------+-------+ 958 | :const:`PCALL_BOUND_METHOD` | 5 | 959 +-------------------------------+-------+ 960 | :const:`PCALL_CFUNCTION` | 6 | 961 +-------------------------------+-------+ 962 | :const:`PCALL_TYPE` | 7 | 963 +-------------------------------+-------+ 964 | :const:`PCALL_GENERATOR` | 8 | 965 +-------------------------------+-------+ 966 | :const:`PCALL_OTHER` | 9 | 967 +-------------------------------+-------+ 968 | :const:`PCALL_POP` | 10 | 969 +-------------------------------+-------+ 970 971 :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created. 972 :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used. 973 974 If there is a method call where the call can be optimized by changing 975 the argument tuple and calling the function directly, it gets recorded 976 twice. 977 978 This function is only present if Python is compiled with :const:`CALL_PROFILE` 979 defined. 980 981.. _advanced-debugging: 982 983Advanced Debugger Support 984========================= 985 986.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 987 988 989These functions are only intended to be used by advanced debugging tools. 990 991 992.. cfunction:: PyInterpreterState* PyInterpreterState_Head() 993 994 Return the interpreter state object at the head of the list of all such objects. 995 996 .. versionadded:: 2.2 997 998 999.. cfunction:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp) 1000 1001 Return the next interpreter state object after *interp* from the list of all 1002 such objects. 1003 1004 .. versionadded:: 2.2 1005 1006 1007.. cfunction:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp) 1008 1009 Return the a pointer to the first :ctype:`PyThreadState` object in the list of 1010 threads associated with the interpreter *interp*. 1011 1012 .. versionadded:: 2.2 1013 1014 1015.. cfunction:: PyThreadState* PyThreadState_Next(PyThreadState *tstate) 1016 1017 Return the next thread state object after *tstate* from the list of all such 1018 objects belonging to the same :ctype:`PyInterpreterState` object. 1019 1020 .. versionadded:: 2.2 1021