.. highlightlang:: c

.. _initialization:

*****************************************

Initialization, Finalization, and Threads

*****************************************

.. cfunction:: void Py_Initialize()

   .. index::

      single: Py_SetProgramName()

      single: PyEval_InitThreads()

      single: PyEval_ReleaseLock()

      single: PyEval_AcquireLock()

      single: modules (in module sys)

      single: path (in module sys)

      module: __builtin__

      module: __main__

      module: sys

      triple: module; search; path

      single: PySys_SetArgv()

      single: Py_Finalize()

   Initialize the Python interpreter.  In an application embedding  Python, this

   should be called before using any other Python/C API functions; with the

   exception of :cfunc:`Py_SetProgramName`, :cfunc:`PyEval_InitThreads`,

   :cfunc:`PyEval_ReleaseLock`, and :cfunc:`PyEval_AcquireLock`. This initializes

   the table of loaded modules (``sys.modules``), and creates the fundamental

   modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`.  It also initializes

   the module search path (``sys.path``). It does not set ``sys.argv``; use

   :cfunc:`PySys_SetArgv` for that.  This is a no-op when called for a second time

   (without calling :cfunc:`Py_Finalize` first).  There is no return value; it is a

   fatal error if the initialization fails.

.. cfunction:: void Py_InitializeEx(int initsigs)

   This function works like :cfunc:`Py_Initialize` if *initsigs* is 1. If

   *initsigs* is 0, it skips initialization registration of signal handlers, which

   might be useful when Python is embedded.

   .. versionadded:: 2.4

.. cfunction:: int Py_IsInitialized()

   Return true (nonzero) when the Python interpreter has been initialized, false

   (zero) if not.  After :cfunc:`Py_Finalize` is called, this returns false until

   :cfunc:`Py_Initialize` is called again.

.. cfunction:: void Py_Finalize()

   Undo all initializations made by :cfunc:`Py_Initialize` and subsequent use of

   Python/C API functions, and destroy all sub-interpreters (see

   :cfunc:`Py_NewInterpreter` below) that were created and not yet destroyed since

   the last call to :cfunc:`Py_Initialize`.  Ideally, this frees all memory

   allocated by the Python interpreter.  This is a no-op when called for a second

   time (without calling :cfunc:`Py_Initialize` again first).  There is no return

   value; errors during finalization are ignored.

   This function is provided for a number of reasons.  An embedding application

   might want to restart Python without having to restart the application itself.

   An application that has loaded the Python interpreter from a dynamically

   loadable library (or DLL) might want to free all memory allocated by Python

   before unloading the DLL. During a hunt for memory leaks in an application a

   developer might want to free all memory allocated by Python before exiting from

   the application.

   **Bugs and caveats:** The destruction of modules and objects in modules is done

   in random order; this may cause destructors (:meth:`__del__` methods) to fail

   when they depend on other objects (even functions) or modules.  Dynamically

   loaded extension modules loaded by Python are not unloaded.  Small amounts of

   memory 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 not

   freed.  Some memory allocated by extension modules may not be freed.  Some

   extensions may not work properly if their initialization routine is called more

   than once; this can happen if an application calls :cfunc:`Py_Initialize` and

   :cfunc:`Py_Finalize` more than once.

.. cfunction:: PyThreadState* Py_NewInterpreter()

   .. index::

      module: __builtin__

      module: __main__

      module: sys

      single: stdout (in module sys)

      single: stderr (in module sys)

      single: stdin (in module sys)

   Create a new sub-interpreter.  This is an (almost) totally separate environment

   for the execution of Python code.  In particular, the new interpreter has

   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).

   The return value points to the first thread state created in the new

   sub-interpreter.  This thread state is made in the current thread state.

   Note that no actual thread is created; see the discussion of thread states

   below.  If creation of the new interpreter is unsuccessful, *NULL* is

   returned; no exception is set since the exception state is stored in the

   current thread state and there may not be a current thread state.  (Like all

   other Python/C API functions, the global interpreter lock must be held before

   calling this function and is still held when it returns; however, unlike most

   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

   extension is imported by another (sub-)interpreter, a new module is initialized

   and filled with the contents of this copy; the extension's ``init`` function is

   not called.  Note that this is different from what happens when an extension is

   imported after the interpreter has been completely re-initialized by calling

   :cfunc:`Py_Finalize` and :cfunc:`Py_Initialize`; in that case, the extension's

   ``initmodule`` function *is* called again.

   .. index:: single: close() (in module os)

   **Bugs and caveats:** Because sub-interpreters (and the main interpreter) are

   part of the same process, the insulation between them isn't perfect --- for

   example, using low-level file operations like  :func:`os.close` they can

   (accidentally or maliciously) affect each other's open files.  Because of the

   way extensions are shared between (sub-)interpreters, some extensions may not

   work properly; this is especially likely when the extension makes use of

   (static) global variables, or when the extension manipulates its module's

   dictionary after its initialization.  It is possible to insert objects created

   in one sub-interpreter into a namespace of another sub-interpreter; this should

   be done with great care to avoid sharing user-defined functions, methods,

   instances or classes between sub-interpreters, since import operations executed

   by such objects may affect the wrong (sub-)interpreter's dictionary of loaded

   modules.  (XXX This is a hard-to-fix bug that will be addressed in a future

   release.)

   Also note that the use of this functionality is incompatible with extension

   modules such as PyObjC and ctypes that use the :cfunc:`PyGILState_\*` APIs (and

   this is inherent in the way the :cfunc:`PyGILState_\*` functions work).  Simple

   things may work, but confusing behavior will always be near.

.. cfunction:: void Py_EndInterpreter(PyThreadState *tstate)

   .. index:: single: Py_Finalize()

   Destroy the (sub-)interpreter represented by the given thread state. The given

   thread state must be the current thread state.  See the discussion of thread

   states below.  When the call returns, the current thread state is *NULL*.  All

   thread states associated with this interpreter are destroyed.  (The global

   interpreter lock must be held before calling this function and is still held

   when it returns.)  :cfunc:`Py_Finalize` will destroy all sub-interpreters that

   haven't been explicitly destroyed at that point.

.. cfunction:: void Py_SetProgramName(char *name)

   .. index::

      single: Py_Initialize()

      single: main()

      single: Py_GetPath()

   This function should be called before :cfunc:`Py_Initialize` is called for

   the first time, if it is called at all.  It tells the interpreter the value

   of the ``argv[0]`` argument to the :cfunc:`main` function of the program.

   This is used by :cfunc:`Py_GetPath` and some other functions below to find

   the Python run-time libraries relative to the interpreter executable.  The

   default value is ``'python'``.  The argument should point to a

   zero-terminated character string in static storage whose contents will not

   change for the duration of the program's execution.  No code in the Python

   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.

.. cfunction:: char* Py_GetPrefix()

   Return the *prefix* for installed platform-independent 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 prefix is ``'/usr/local'``. 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()

   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.

   Background: The exec-prefix differs from the prefix when platform dependent

   files (such as executables and shared libraries) are installed in a different

   directory tree.  In a typical installation, platform dependent files may be

   installed in the :file:`/usr/local/plat` subtree while platform independent may

   be installed in :file:`/usr/local`.

   Generally speaking, a platform is a combination of hardware and software

   families, e.g.  Sparc machines running the Solaris 2.x operating system are

   considered the same platform, but Intel machines running Solaris 2.x are another

   platform, and Intel machines running Linux are yet another platform.  Different

   major revisions of the same operating system generally also form different

   platforms.  Non-Unix operating systems are a different story; the installation

   strategies on those systems are so different that the prefix and exec-prefix are

   meaningless, and set to the empty string. Note that compiled Python bytecode

   files are platform independent (but not independent from the Python version by

   which they were compiled!).

   System administrators will know how to configure the :program:`mount` or

   :program:`automount` programs to share :file:`/usr/local` between platforms

   while having :file:`/usr/local/plat` be a different filesystem for each

   platform.

.. cfunction:: char* Py_GetProgramFullPath()

   .. index::

      single: Py_SetProgramName()

      single: executable (in module sys)

   Return the full program name of the Python executable; this is  computed as a

   side-effect of deriving the default module search path  from the program name

   (set by :cfunc:`Py_SetProgramName` above). The returned string points into

   static storage; the caller should not modify its value.  The value is available

   to Python code as ``sys.executable``.

.. cfunction:: char* Py_GetPath()

   .. 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

   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.

   .. 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]"

   .. index:: single: version (in module sys)

   The first word (up to the first space character) is the current Python version;

   the first three characters are the major and minor version separated by a

   period.  The returned string points into static storage; the caller should not

   modify its value.  The value is available to Python code as ``sys.version``.

.. cfunction:: const char* Py_GetBuildNumber()

   Return a string representing the Subversion revision that this Python executable

   was built from.  This number is a string because it may contain a trailing 'M'

   if Python was built from a mixed revision source tree.

   .. versionadded:: 2.5

.. cfunction:: const char* Py_GetPlatform()

   .. index:: single: platform (in module sys)

   Return the platform identifier for the current platform.  On Unix, this is

   formed from the "official" name of the operating system, converted to lower

   case, followed by the major revision number; e.g., for Solaris 2.x, which is

   also known as SunOS 5.x, the value is ``'sunos5'``.  On Mac OS X, it is

   ``'darwin'``.  On Windows, it is ``'win'``.  The returned string points into

   static storage; the caller should not modify its value.  The value is available

   to Python code as ``sys.platform``.

.. cfunction:: const char* Py_GetCopyright()

   Return the official copyright string for the current Python version, for example

   ``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``

   .. index:: single: copyright (in module sys)

   The returned string points into static storage; the caller should not modify its

   value.  The value is available to Python code as ``sys.copyright``.

.. cfunction:: const char* Py_GetCompiler()

   Return an indication of the compiler used to build the current Python version,

   in square brackets, for example::

      "[GCC 2.7.2.2]"

   .. index:: single: version (in module sys)

   The returned string points into static storage; the caller should not modify its

   value.  The value is available to Python code as part of the variable

   ``sys.version``.

.. cfunction:: const char* Py_GetBuildInfo()

   Return information about the sequence number and build date and time  of the

   current Python interpreter instance, for example ::

      "#67, Aug  1 1997, 22:34:28"

   .. index:: single: version (in module sys)

   The returned string points into static storage; the caller should not modify its

   value.  The value is available to Python code as part of the variable

   ``sys.version``.

.. cfunction:: void PySys_SetArgv(int argc, char **argv)

   .. index::

      single: main()

      single: Py_FatalError()

      single: argv (in module sys)

   Set ``sys.argv`` based on *argc* and *argv*.  These parameters are similar to

   those passed to the program's :cfunc:`main` function with the difference that

   the first entry should refer to the script file to be executed rather than the

   executable hosting the Python interpreter.  If there isn't a script that will be

   run, the first entry in *argv* can be an empty string.  If this function fails

   to initialize ``sys.argv``, a fatal condition is signalled using

   :cfunc:`Py_FatalError`.

   .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;

      check w/ Guido.

.. _threads:

Thread State and the Global Interpreter Lock

============================================

.. index::

   single: global interpreter lock

   single: interpreter lock

   single: lock, interpreter

The Python interpreter is not fully thread safe.  In order to support

multi-threaded Python programs, there's a global lock that must be held by the

current thread before it can safely access Python objects. Without the lock,

even the simplest operations could cause problems in a multi-threaded program:

for example, when two threads simultaneously increment the reference count of

the same object, the reference count could end up being incremented only once

instead of twice.

.. 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

released and reacquired around potentially blocking I/O operations like reading

or writing a file, so that other threads can run while the thread that requests

the I/O is waiting for the I/O operation to complete.

.. index::

   single: PyThreadState

   single: PyThreadState

The Python interpreter needs to keep some bookkeeping information separate per

thread --- for this it uses a data structure called :ctype:`PyThreadState`.

There's one global variable, however: the pointer to the current

:ctype:`PyThreadState` structure.  While most thread packages have a way to

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.

   Release the interpreter lock.

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

   Reacquire the 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

state and lock 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);

Using even lower level primitives, we can get roughly the same effect as

follows::

   PyThreadState *_save;

   _save = PyThreadState_Swap(NULL);

   PyEval_ReleaseLock();

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

   PyEval_AcquireLock();

   PyThreadState_Swap(_save);

.. index::

   single: PyEval_RestoreThread()

   single: errno

   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

:cfunc:`PyEval_RestoreThread` don't manipulate the lock; 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

thread could immediately acquire the lock and store its own thread state in the

global variable). Conversely, when acquiring the lock and restoring the thread

state, the lock must be acquired before storing the thread state pointer.

Why am I going on with so much detail about this?  Because when threads are

created from C, they don't have the global interpreter lock, nor is there a

thread state data structure for them.  Such threads must bootstrap themselves

into existence, by first creating a thread state data structure, then acquiring

the lock, and finally storing their thread state pointer, before they can start

using the Python/C API.  When they are done, they should reset the thread state

pointer, release the lock, and finally free their thread state data structure.

Beginning with version 2.3, threads can now take advantage of the

:cfunc:`PyGILState_\*` functions to do all of the above automatically.  The

typical idiom for calling into Python from a C thread is now::

   PyGILState_STATE gstate;

   gstate = PyGILState_Ensure();

   /* Perform Python actions here.  */

   result = CallSomeFunction();

   /* evaluate result */

   /* Release the thread. No Python API allowed beyond this point. */

   PyGILState_Release(gstate);

Note that the :cfunc:`PyGILState_\*` functions assume there is only one global

interpreter (created automatically by :cfunc:`Py_Initialize`).  Python still

supports the creation of additional interpreters (using

:cfunc:`Py_NewInterpreter`), but mixing multiple interpreters and the

:cfunc:`PyGILState_\*` API is unsupported.

.. ctype:: PyInterpreterState

   This data structure represents the state shared by a number of cooperating

   threads.  Threads belonging to the same interpreter share their module

   administration and a few other internal items. There are no public members in

   this structure.

   Threads belonging to different interpreters initially share nothing, except

   process state like available memory, open file descriptors and such.  The global

   interpreter lock is also shared by all threads, regardless of to which

   interpreter they belong.

.. ctype:: PyThreadState

   This data structure represents the state of a single thread.  The only public

   data member is :ctype:`PyInterpreterState \*`:attr:`interp`, which points to

   this thread's interpreter state.

.. cfunction:: void PyEval_InitThreads()

   .. index::

      single: PyEval_ReleaseLock()