| separate, independent versions of all imported modules, including the |
| fundamental modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. The |
| table of loaded modules (``sys.modules``) and the module search path |
| (``sys.path``) are also separate. The new environment has no ``sys.argv`` |
| variable. It has new standard I/O stream file objects ``sys.stdin``, |
| ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying |
| :ctype:`FILE` structures in the C library). |
| |
n | The return value points to the first thread state created in the new sub- |
n | The return value points to the first thread state created in the new |
| interpreter. This thread state is made in the current thread state. Note that |
| sub-interpreter. This thread state is made in the current thread state. |
| no actual thread is created; see the discussion of thread states below. If |
| Note that no actual thread is created; see the discussion of thread states |
| creation of the new interpreter is unsuccessful, *NULL* is returned; no |
| below. If creation of the new interpreter is unsuccessful, *NULL* is |
| exception is set since the exception state is stored in the current thread state |
| returned; no exception is set since the exception state is stored in the |
| and there may not be a current thread state. (Like all other Python/C API |
| current thread state and there may not be a current thread state. (Like all |
| functions, the global interpreter lock must be held before calling this function |
| other Python/C API functions, the global interpreter lock must be held before |
| and is still held when it returns; however, unlike most other Python/C API |
| calling this function and is still held when it returns; however, unlike most |
| functions, there needn't be a current thread state on entry.) |
| other Python/C API functions, there needn't be a current thread state on |
| entry.) |
| |
| .. index:: |
| single: Py_Finalize() |
| single: Py_Initialize() |
| |
| Extension modules are shared between (sub-)interpreters as follows: the first |
| time a particular extension is imported, it is initialized normally, and a |
| (shallow) copy of its module's dictionary is squirreled away. When the same |
| |
| .. cfunction:: void Py_SetProgramName(char *name) |
| |
| .. index:: |
| single: Py_Initialize() |
| single: main() |
| single: Py_GetPath() |
| |
n | This function should be called before :cfunc:`Py_Initialize` is called for the |
n | This function should be called before :cfunc:`Py_Initialize` is called for |
| first time, if it is called at all. It tells the interpreter the value of the |
| the first time, if it is called at all. It tells the interpreter the value |
| ``argv[0]`` argument to the :cfunc:`main` function of the program. This is used |
| of the ``argv[0]`` argument to the :cfunc:`main` function of the program. |
| by :cfunc:`Py_GetPath` and some other functions below to find the Python run- |
| This is used by :cfunc:`Py_GetPath` and some other functions below to find |
| time libraries relative to the interpreter executable. The default value is |
| the Python run-time libraries relative to the interpreter executable. The |
| ``'python'``. The argument should point to a zero-terminated character string |
| default value is ``'python'``. The argument should point to a |
| in static storage whose contents will not change for the duration of the |
| zero-terminated character string in static storage whose contents will not |
| program's execution. No code in the Python interpreter will change the contents |
| change for the duration of the program's execution. No code in the Python |
| of this storage. |
| interpreter will change the contents of this storage. |
| |
| |
| .. cfunction:: char* Py_GetProgramName() |
| |
| .. index:: single: Py_SetProgramName() |
| |
| Return the program name set with :cfunc:`Py_SetProgramName`, or the default. |
| The returned string points into static storage; the caller should not modify its |
| value. This corresponds to the :makevar:`prefix` variable in the top-level |
| :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure` |
| script at build time. The value is available to Python code as ``sys.prefix``. |
| It is only useful on Unix. See also the next function. |
| |
| |
| .. cfunction:: char* Py_GetExecPrefix() |
| |
n | Return the *exec-prefix* for installed platform-*de*pendent files. This is |
n | Return the *exec-prefix* for installed platform-*dependent* files. This is |
| derived through a number of complicated rules from the program name set with |
| :cfunc:`Py_SetProgramName` and some environment variables; for example, if the |
| program name is ``'/usr/local/bin/python'``, the exec-prefix is |
| ``'/usr/local'``. The returned string points into static storage; the caller |
| should not modify its value. This corresponds to the :makevar:`exec_prefix` |
| variable in the top-level :file:`Makefile` and the :option:`--exec-prefix` |
| argument to the :program:`configure` script at build time. The value is |
| available to Python code as ``sys.exec_prefix``. It is only useful on Unix. |
| |
| .. index:: |
| triple: module; search; path |
| single: path (in module sys) |
| |
| Return the default module search path; this is computed from the program name |
| (set by :cfunc:`Py_SetProgramName` above) and some environment variables. The |
| returned string consists of a series of directory names separated by a platform |
n | dependent delimiter character. The delimiter character is ``':'`` on Unixand |
n | dependent delimiter character. The delimiter character is ``':'`` on Unix and |
| Mac OS X, ``';'`` on Windows. The returned string points into static storage; |
| the caller should not modify its value. The value is available to Python code |
| as the list ``sys.path``, which may be modified to change the future search path |
| for loaded modules. |
| |
n | .. % XXX should give the exact rules |
n | .. XXX should give the exact rules |
| |
| |
| .. cfunction:: const char* Py_GetVersion() |
| |
| Return the version of this Python interpreter. This is a string that looks |
| something like :: |
| |
| "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]" |
| |
| .. cfunction:: void PySys_SetArgv(int argc, char **argv) |
| |
| .. index:: |
| single: main() |
| single: Py_FatalError() |
| single: argv (in module sys) |
| |
n | Set ``sys.argv`` based on *argc* and *argv*. These parameters are similar to |
n | Set :data:`sys.argv` based on *argc* and *argv*. These parameters are |
| those passed to the program's :cfunc:`main` function with the difference that |
| similar to those passed to the program's :cfunc:`main` function with the |
| the first entry should refer to the script file to be executed rather than the |
| difference that the first entry should refer to the script file to be |
| executable hosting the Python interpreter. If there isn't a script that will be |
| executed rather than the executable hosting the Python interpreter. If there |
| run, the first entry in *argv* can be an empty string. If this function fails |
| isn't a script that will be run, the first entry in *argv* can be an empty |
| to initialize ``sys.argv``, a fatal condition is signalled using |
| string. If this function fails to initialize :data:`sys.argv`, a fatal |
| :cfunc:`Py_FatalError`. |
| condition is signalled using :cfunc:`Py_FatalError`. |
| |
n | This function also prepends the executed script's path to :data:`sys.path`. |
| If no script is executed (in the case of calling ``python -c`` or just the |
| interactive interpreter), the empty string is used instead. |
| |
| .. % XXX impl. doesn't seem consistent in allowing 0/NULL for the params; |
| .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params; |
| .. % check w/ Guido. |
| check w/ Guido. |
| |
n | .. % XXX Other PySys thingies (doesn't really belong in this chapter) |
n | |
| .. cfunction:: void Py_SetPythonHome(char *home) |
| |
| Set the default "home" directory, that is, the location of the standard |
| Python libraries. The libraries are searched in |
| :file:`{home}/lib/python{version}` and :file:`{home}/lib/python{version}`. |
| |
| |
| .. cfunction:: char* Py_GetPythonHome() |
| |
| Return the default "home", that is, the value set by a previous call to |
| :cfunc:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME` |
| environment variable if it is set. |
| |
| |
| .. _threads: |
| |
| Thread State and the Global Interpreter Lock |
| ============================================ |
| |
| .. index:: |
| single: global interpreter lock |
| single: interpreter lock |
| single: lock, interpreter |
| |
n | The Python interpreter is not fully thread safe. In order to support multi- |
n | The Python interpreter is not fully thread safe. In order to support |
| threaded Python programs, there's a global lock that must be held by the current |
| multi-threaded Python programs, there's a global lock, called the :dfn:`global |
| interpreter lock` or :dfn:`GIL`, that must be held by the current thread before |
| thread before it can safely access Python objects. Without the lock, even the |
| it can safely access Python objects. Without the lock, even the simplest |
| simplest operations could cause problems in a multi-threaded program: for |
| operations could cause problems in a multi-threaded program: for example, when |
| example, when two threads simultaneously increment the reference count of the |
| two threads simultaneously increment the reference count of the same object, the |
| same object, the reference count could end up being incremented only once |
| reference count could end up being incremented only once instead of twice. |
| instead of twice. |
| |
| .. index:: single: setcheckinterval() (in module sys) |
| |
| Therefore, the rule exists that only the thread that has acquired the global |
| interpreter lock may operate on Python objects or call Python/C API functions. |
| In order to support multi-threaded Python programs, the interpreter regularly |
| releases and reacquires the lock --- by default, every 100 bytecode instructions |
| (this can be changed with :func:`sys.setcheckinterval`). The lock is also |
| store "per-thread global data," Python's internal platform independent thread |
| abstraction doesn't support this yet. Therefore, the current thread state must |
| be manipulated explicitly. |
| |
| This is easy enough in most cases. Most code manipulating the global |
| interpreter lock has the following simple structure:: |
| |
| Save the thread state in a local variable. |
n | Release the interpreter lock. |
n | Release the global interpreter lock. |
| ...Do some blocking I/O operation... |
n | Reacquire the interpreter lock. |
n | Reacquire the global interpreter lock. |
| Restore the thread state from the local variable. |
| |
| This is so common that a pair of macros exists to simplify it:: |
| |
| Py_BEGIN_ALLOW_THREADS |
| ...Do some blocking I/O operation... |
| Py_END_ALLOW_THREADS |
| |
| .. index:: |
| single: Py_BEGIN_ALLOW_THREADS |
| single: Py_END_ALLOW_THREADS |
| |
| The :cmacro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a |
| hidden local variable; the :cmacro:`Py_END_ALLOW_THREADS` macro closes the |
| block. Another advantage of using these two macros is that when Python is |
| compiled without thread support, they are defined empty, thus saving the thread |
n | state and lock manipulations. |
n | state and GIL manipulations. |
| |
| When thread support is enabled, the block above expands to the following code:: |
| |
| PyThreadState *_save; |
| |
| _save = PyEval_SaveThread(); |
| ...Do some blocking I/O operation... |
| PyEval_RestoreThread(_save); |
| single: PyEval_SaveThread() |
| single: PyEval_ReleaseLock() |
| single: PyEval_AcquireLock() |
| |
| There are some subtle differences; in particular, :cfunc:`PyEval_RestoreThread` |
| saves and restores the value of the global variable :cdata:`errno`, since the |
| lock manipulation does not guarantee that :cdata:`errno` is left alone. Also, |
| when thread support is disabled, :cfunc:`PyEval_SaveThread` and |
n | :cfunc:`PyEval_RestoreThread` don't manipulate the lock; in this case, |
n | :cfunc:`PyEval_RestoreThread` don't manipulate the GIL; in this case, |
| :cfunc:`PyEval_ReleaseLock` and :cfunc:`PyEval_AcquireLock` are not available. |
| This is done so that dynamically loaded extensions compiled with thread support |
| enabled can be loaded by an interpreter that was compiled with disabled thread |
| support. |
| |
| The global interpreter lock is used to protect the pointer to the current thread |
| state. When releasing the lock and saving the thread state, the current thread |
| state pointer must be retrieved before the lock is released (since another |
| |
| .. index:: single: Py_Initialize() |
| |
| This is a no-op when called for a second time. It is safe to call this function |
| before calling :cfunc:`Py_Initialize`. |
| |
| .. index:: module: thread |
| |
n | When only the main thread exists, no lock operations are needed. This is a |
n | When only the main thread exists, no GIL operations are needed. This is a |
| common situation (most Python programs do not use threads), and the lock |
n | operations slow the interpreter down a bit. Therefore, the lock is not created |
n | operations slow the interpreter down a bit. Therefore, the lock is not |
| initially. This situation is equivalent to having acquired the lock: when |
| created initially. This situation is equivalent to having acquired the lock: |
| there is only a single thread, all object accesses are safe. Therefore, when |
| when there is only a single thread, all object accesses are safe. Therefore, |
| this function initializes the lock, it also acquires it. Before the Python |
| when this function initializes the global interpreter lock, it also acquires |
| :mod:`thread` module creates a new thread, knowing that either it has the lock |
| it. Before the Python :mod:`thread` module creates a new thread, knowing |
| or the lock hasn't been created yet, it calls :cfunc:`PyEval_InitThreads`. When |
| that either it has the lock or the lock hasn't been created yet, it calls |
| this call returns, it is guaranteed that the lock has been created and that the |
| :cfunc:`PyEval_InitThreads`. When this call returns, it is guaranteed that |
| calling thread has acquired it. |
| the lock has been created and that the calling thread has acquired it. |
| |
| It is **not** safe to call this function when it is unknown which thread (if |
| any) currently has the global interpreter lock. |
| |
| This function is not available when thread support is disabled at compile time. |
| |
| |
| .. cfunction:: int PyEval_ThreadsInitialized() |
| |
| Returns a non-zero value if :cfunc:`PyEval_InitThreads` has been called. This |
n | function can be called without holding the lock, and therefore can be used to |
n | function can be called without holding the GIL, and therefore can be used to |
| avoid calls to the locking API when running single-threaded. This function is |
| not available when thread support is disabled at compile time. |
| |
| .. versionadded:: 2.4 |
| |
| |
| .. cfunction:: void PyEval_AcquireLock() |
| |
| thread. The *tstate* argument, which must not be *NULL*, is only used to check |
| that it represents the current thread state --- if it isn't, a fatal error is |
| reported. This function is not available when thread support is disabled at |
| compile time. |
| |
| |
| .. cfunction:: PyThreadState* PyEval_SaveThread() |
| |
n | Release the interpreter lock (if it has been created and thread support is |
n | Release the global interpreter lock (if it has been created and thread |
| enabled) and reset the thread state to *NULL*, returning the previous thread |
| support is enabled) and reset the thread state to *NULL*, returning the |
| state (which is not *NULL*). If the lock has been created, the current thread |
| previous thread state (which is not *NULL*). If the lock has been created, |
| must have acquired it. (This function is available even when thread support is |
| the current thread must have acquired it. (This function is available even |
| disabled at compile time.) |
| when thread support is disabled at compile time.) |
| |
| |
| .. cfunction:: void PyEval_RestoreThread(PyThreadState *tstate) |
| |
n | Acquire the interpreter lock (if it has been created and thread support is |
n | Acquire the global interpreter lock (if it has been created and thread |
| enabled) and set the thread state to *tstate*, which must not be *NULL*. If the |
| support is enabled) and set the thread state to *tstate*, which must not be |
| lock has been created, the current thread must not have acquired it, otherwise |
| *NULL*. If the lock has been created, the current thread must not have |
| deadlock ensues. (This function is available even when thread support is |
| acquired it, otherwise deadlock ensues. (This function is available even |
| disabled at compile time.) |
| when thread support is disabled at compile time.) |
| |
| |
| .. cfunction:: void PyEval_ReInitThreads() |
| |
| This function is called from :cfunc:`PyOS_AfterFork` to ensure that newly |
| created child processes don't hold locks referring to threads which |
| are not running in the child process. |
| |
| |
| The following macros are normally used without a trailing semicolon; look for |
| example usage in the Python source distribution. |
| |
| |
| .. cmacro:: Py_BEGIN_ALLOW_THREADS |
| |
| This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``. |
| |
| .. cmacro:: Py_UNBLOCK_THREADS |
| |
| This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to |
| :cmacro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable |
| declaration. It is a no-op when thread support is disabled at compile time. |
| |
| All of the following functions are only available when thread support is enabled |
n | at compile time, and must be called only when the interpreter lock has been |
n | at compile time, and must be called only when the global interpreter lock has |
| created. |
| been created. |
| |
| |
| .. cfunction:: PyInterpreterState* PyInterpreterState_New() |
| |
n | Create a new interpreter state object. The interpreter lock need not be held, |
n | Create a new interpreter state object. The global interpreter lock need not |
| but may be held if it is necessary to serialize calls to this function. |
| be held, but may be held if it is necessary to serialize calls to this |
| function. |
| |
| |
| .. cfunction:: void PyInterpreterState_Clear(PyInterpreterState *interp) |
| |
n | Reset all information in an interpreter state object. The interpreter lock must |
n | Reset all information in an interpreter state object. The global interpreter |
| be held. |
| lock must be held. |
| |
| |
| .. cfunction:: void PyInterpreterState_Delete(PyInterpreterState *interp) |
| |
n | Destroy an interpreter state object. The interpreter lock need not be held. |
n | Destroy an interpreter state object. The global interpreter lock need not be |
| The interpreter state must have been reset with a previous call to |
| held. The interpreter state must have been reset with a previous call to |
| :cfunc:`PyInterpreterState_Clear`. |
| |
| |
| .. cfunction:: PyThreadState* PyThreadState_New(PyInterpreterState *interp) |
| |
n | Create a new thread state object belonging to the given interpreter object. The |
n | Create a new thread state object belonging to the given interpreter object. |
| interpreter lock need not be held, but may be held if it is necessary to |
| The global interpreter lock need not be held, but may be held if it is |
| serialize calls to this function. |
| necessary to serialize calls to this function. |
| |
| |
| .. cfunction:: void PyThreadState_Clear(PyThreadState *tstate) |
| |
n | Reset all information in a thread state object. The interpreter lock must be |
n | Reset all information in a thread state object. The global interpreter lock |
| held. |
| must be held. |
| |
| |
| .. cfunction:: void PyThreadState_Delete(PyThreadState *tstate) |
| |
n | Destroy a thread state object. The interpreter lock need not be held. The |
n | Destroy a thread state object. The global interpreter lock need not be held. |
| thread state must have been reset with a previous call to |
| The thread state must have been reset with a previous call to |
| :cfunc:`PyThreadState_Clear`. |
| |
| |
| .. cfunction:: PyThreadState* PyThreadState_Get() |
| |
n | Return the current thread state. The interpreter lock must be held. When the |
n | Return the current thread state. The global interpreter lock must be held. |
| current thread state is *NULL*, this issues a fatal error (so that the caller |
| When the current thread state is *NULL*, this issues a fatal error (so that |
| needn't check for *NULL*). |
| the caller needn't check for *NULL*). |
| |
| |
| .. cfunction:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate) |
| |
| Swap the current thread state with the thread state given by the argument |
n | *tstate*, which may be *NULL*. The interpreter lock must be held. |
n | *tstate*, which may be *NULL*. The global interpreter lock must be held. |
| |
| |
| .. cfunction:: PyObject* PyThreadState_GetDict() |
| |
| Return a dictionary in which extensions can store thread-specific state |
| information. Each extension should use a unique key to use to store state in |
| the dictionary. It is okay to call this function when no current thread state |
| is available. If this function returns *NULL*, no exception has been raised and |
| zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending |
| exception (if any) for the thread is cleared. This raises no exceptions. |
| |
| .. versionadded:: 2.3 |
| |
| |
| .. cfunction:: PyGILState_STATE PyGILState_Ensure() |
| |
n | Ensure that the current thread is ready to call the Python C API regardless of |
n | Ensure that the current thread is ready to call the Python C API regardless |
| the current state of Python, or of its thread lock. This may be called as many |
| of the current state of Python, or of the global interpreter lock. This may |
| times as desired by a thread as long as each call is matched with a call to |
| be called as many times as desired by a thread as long as each call is |
| :cfunc:`PyGILState_Release`. In general, other thread-related APIs may be used |
| matched with a call to :cfunc:`PyGILState_Release`. In general, other |
| between :cfunc:`PyGILState_Ensure` and :cfunc:`PyGILState_Release` calls as long |
| thread-related APIs may be used between :cfunc:`PyGILState_Ensure` and |
| as the thread state is restored to its previous state before the Release(). For |
| :cfunc:`PyGILState_Release` calls as long as the thread state is restored to |
| example, normal usage of the :cmacro:`Py_BEGIN_ALLOW_THREADS` and |
| its previous state before the Release(). For example, normal usage of the |
| :cmacro:`Py_END_ALLOW_THREADS` macros is acceptable. |
| :cmacro:`Py_BEGIN_ALLOW_THREADS` and :cmacro:`Py_END_ALLOW_THREADS` macros is |
| acceptable. |
| |
| The return value is an opaque "handle" to the thread state when |
n | :cfunc:`PyGILState_Acquire` was called, and must be passed to |
n | :cfunc:`PyGILState_Ensure` was called, and must be passed to |
| :cfunc:`PyGILState_Release` to ensure Python is left in the same state. Even |
| though recursive calls are allowed, these handles *cannot* be shared - each |
n | unique call to :cfunc:`PyGILState_Ensure` must save the handle for its call to |
n | unique call to :cfunc:`PyGILState_Ensure` must save the handle for its call |
| :cfunc:`PyGILState_Release`. |
| to :cfunc:`PyGILState_Release`. |
| |
| When the function returns, the current thread will hold the GIL. Failure is a |
| fatal error. |
| |
| .. versionadded:: 2.3 |
| |
| |
| .. cfunction:: void PyGILState_Release(PyGILState_STATE) |
| |
| |
| .. cfunction:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj) |
| |
| Set the tracing function to *func*. This is similar to |
| :cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number |
| events. |
| |
t | .. cfunction:: PyObject* PyEval_GetCallStats(PyObject *self) |
| |
| Return a tuple of function call counts. There are constants defined for the |
| positions within the tuple: |
| |
| +-------------------------------+-------+ |
| | Name | Value | |
| +===============================+=======+ |
| | :const:`PCALL_ALL` | 0 | |
| +-------------------------------+-------+ |
| | :const:`PCALL_FUNCTION` | 1 | |
| +-------------------------------+-------+ |
| | :const:`PCALL_FAST_FUNCTION` | 2 | |
| +-------------------------------+-------+ |
| | :const:`PCALL_FASTER_FUNCTION`| 3 | |
| +-------------------------------+-------+ |
| | :const:`PCALL_METHOD` | 4 | |
| +-------------------------------+-------+ |
| | :const:`PCALL_BOUND_METHOD` | 5 | |
| +-------------------------------+-------+ |
| | :const:`PCALL_CFUNCTION` | 6 | |
| +-------------------------------+-------+ |
| | :const:`PCALL_TYPE` | 7 | |
| +-------------------------------+-------+ |
| | :const:`PCALL_GENERATOR` | 8 | |
| +-------------------------------+-------+ |
| | :const:`PCALL_OTHER` | 9 | |
| +-------------------------------+-------+ |
| | :const:`PCALL_POP` | 10 | |
| +-------------------------------+-------+ |
| |
| :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created. |
| :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used. |
| |
| If there is a method call where the call can be optimized by changing |
| the argument tuple and calling the function directly, it gets recorded |
| twice. |
| |
| This function is only present if Python is compiled with :const:`CALL_PROFILE` |
| defined. |
| |
| .. _advanced-debugging: |
| |
| Advanced Debugger Support |
| ========================= |
| |
| .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| |