Break the Python/C API manual into smaller files by chapter. This manual

has grown beyond what font-lock will work with using the default (X)Emacs
settings.

Indentation of the description has been made consistent, and a number of
smaller markup adjustments have been made as well.

1 files changed, 774 insertions, 0 deletions

diff --git a/Doc/api/init.tex b/Doc/api/init.tex
new file mode 100644
index 0000000..890ca0d
--- /dev/null
+++ b/Doc/api/init.tex
@@ -0,0 +1,774 @@
+\chapter{Initialization, Finalization, and Threads
+         \label{initialization}}
+
+\begin{cfuncdesc}{void}{Py_Initialize}{}
+  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
+  \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()},
+  \cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()},
+  \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()},
+  and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}.
+  This initializes the table of loaded modules (\code{sys.modules}),
+  and\withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}
+  creates the fundamental modules
+  \module{__builtin__}\refbimodindex{__builtin__},
+  \module{__main__}\refbimodindex{__main__} and
+  \module{sys}\refbimodindex{sys}.  It also initializes the module
+  search\indexiii{module}{search}{path} path (\code{sys.path}).
+  It does not set \code{sys.argv}; use
+  \cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that.  This
+  is a no-op when called for a second time (without calling
+  \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first).  There is
+  no return value; it is a fatal error if the initialization fails.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{Py_IsInitialized}{}
+  Return true (nonzero) when the Python interpreter has been
+  initialized, false (zero) if not.  After \cfunction{Py_Finalize()}
+  is called, this returns false until \cfunction{Py_Initialize()} is
+  called again.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_Finalize}{}
+  Undo all initializations made by \cfunction{Py_Initialize()} and
+  subsequent use of Python/C API functions, and destroy all
+  sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that
+  were created and not yet destroyed since the last call to
+  \cfunction{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 \cfunction{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.
+
+  \strong{Bugs and caveats:} The destruction of modules and objects in
+  modules is done in random order; this may cause destructors
+  (\method{__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 extension may not work properly if
+  their initialization routine is called more than once; this can
+  happen if an applcation calls \cfunction{Py_Initialize()} and
+  \cfunction{Py_Finalize()} more than once.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{}
+  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
+  \module{__builtin__}\refbimodindex{__builtin__},
+  \module{__main__}\refbimodindex{__main__} and
+  \module{sys}\refbimodindex{sys}.  The table of loaded modules
+  (\code{sys.modules}) and the module search path (\code{sys.path})
+  are also separate.  The new environment has no \code{sys.argv}
+  variable.  It has new standard I/O stream file objects
+  \code{sys.stdin}, \code{sys.stdout} and \code{sys.stderr} (however
+  these refer to the same underlying \ctype{FILE} structures in the C
+  library).
+  \withsubitem{(in module sys)}{
+    \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}}
+
+  The return value points to the first thread state created in the new
+  sub-interpreter.  This thread state is made 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.)
+
+  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 \code{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
+  \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
+  \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case,
+  the extension's \code{init\var{module}} function \emph{is} called
+  again.
+
+  \strong{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 \withsubitem{(in module os)}{\ttindex{close()}}
+  \function{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.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
+  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 interpreted are destroyed.  (The global interpreter lock must
+  be held before calling this function and is still held when it
+  returns.)  \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will
+  destroy all sub-interpreters that haven't been explicitly destroyed
+  at that point.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
+  This function should be called before
+  \cfunction{Py_Initialize()}\ttindex{Py_Initialize()} is called
+  for the first time, if it is called at all.  It tells the
+  interpreter the value of the \code{argv[0]} argument to the
+  \cfunction{main()}\ttindex{main()} function of the program.  This is
+  used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some
+  other functions below to find the Python run-time libraries relative
+  to the interpreter executable.  The default value is
+  \code{'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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{Py_GetProgramName}{}
+  Return the program name set with
+  \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the
+  default.  The returned string points into static storage; the caller
+  should not modify its value.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{Py_GetPrefix}{}
+  Return the \emph{prefix} for installed platform-independent files.
+  This is derived through a number of complicated rules from the
+  program name set with \cfunction{Py_SetProgramName()} and some
+  environment variables; for example, if the program name is
+  \code{'/usr/local/bin/python'}, the prefix is \code{'/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
+  \longprogramopt{prefix} argument to the \program{configure} script
+  at build time.  The value is available to Python code as
+  \code{sys.prefix}.  It is only useful on \UNIX.  See also the next
+  function.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
+  Return the \emph{exec-prefix} for installed
+  platform-\emph{de}pendent files.  This is derived through a number
+  of complicated rules from the program name set with
+  \cfunction{Py_SetProgramName()} and some environment variables; for
+  example, if the program name is \code{'/usr/local/bin/python'}, the
+  exec-prefix is \code{'/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 \longprogramopt{exec-prefix} argument to the
+  \program{configure} script at build  time.  The value is available
+  to Python code as \code{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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
+  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
+  \cfunction{Py_SetProgramName()}\ttindex{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
+  \code{sys.executable}.
+  \withsubitem{(in module sys)}{\ttindex{executable}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{char*}{Py_GetPath}{}
+  \indexiii{module}{search}{path}
+  Return the default module search path; this is computed from the 
+  program name (set by \cfunction{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 \character{:} on \UNIX,
+  \character{;} on DOS/Windows, and \character{\e n} (the \ASCII{}
+  newline character) on Macintosh.  The returned string points into
+  static storage; the caller should not modify its value.  The value
+  is available to Python code as the list
+  \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, which
+  may be modified to change the future search path for loaded
+  modules.
+
+  % XXX should give the exact rules
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetVersion}{}
+  Return the version of this Python interpreter.  This is a string
+  that looks something like
+
+\begin{verbatim}
+"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
+\end{verbatim}
+
+  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 the list \code{sys.version}.
+  \withsubitem{(in module sys)}{\ttindex{version}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
+  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 \code{'sunos5'}.  On Macintosh, it is \code{'mac'}.  On Windows,
+  it is \code{'win'}.  The returned string points into static storage;
+  the caller should not modify its value.  The value is available to
+  Python code as \code{sys.platform}.
+  \withsubitem{(in module sys)}{\ttindex{platform}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetCopyright}{}
+  Return the official copyright string for the current Python version,
+  for example
+
+  \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}
+
+  The returned string points into static storage; the caller should
+  not modify its value.  The value is available to Python code as the
+  list \code{sys.copyright}.
+  \withsubitem{(in module sys)}{\ttindex{copyright}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetCompiler}{}
+  Return an indication of the compiler used to build the current
+  Python version, in square brackets, for example:
+
+\begin{verbatim}
+"[GCC 2.7.2.2]"
+\end{verbatim}
+
+  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 \code{sys.version}.
+  \withsubitem{(in module sys)}{\ttindex{version}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{}
+  Return information about the sequence number and build date and time 
+  of the current Python interpreter instance, for example
+
+\begin{verbatim}
+"#67, Aug  1 1997, 22:34:28"
+\end{verbatim}
+
+  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 \code{sys.version}.
+  \withsubitem{(in module sys)}{\ttindex{version}}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
+  Set \code{sys.argv} based on \var{argc} and \var{argv}.  These
+  parameters are similar to those passed to the program's
+  \cfunction{main()}\ttindex{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 \var{argv} can
+  be an empty string.  If this function fails to initialize
+  \code{sys.argv}, a fatal condition is signalled using
+  \cfunction{Py_FatalError()}\ttindex{Py_FatalError()}.
+  \withsubitem{(in module sys)}{\ttindex{argv}}
+  % XXX impl. doesn't seem consistent in allowing 0/NULL for the params; 
+  % check w/ Guido.
+\end{cfuncdesc}
+
+% XXX Other PySys thingies (doesn't really belong in this chapter)
+
+\section{Thread State and the Global Interpreter Lock
+         \label{threads}}
+
+\index{global interpreter lock}
+\index{interpreter lock}
+\index{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.
+
+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 ten bytecode instructions (this can be changed with
+\withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
+\function{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.
+
+The Python interpreter needs to keep some bookkeeping information
+separate per thread --- for this it uses a data structure called
+\ctype{PyThreadState}\ttindex{PyThreadState}.  This is new in Python
+1.5; in earlier versions, such state was stored in global variables,
+and switching threads could cause problems.  In particular, exception
+handling is now thread safe, when the application uses
+\withsubitem{(in module sys)}{\ttindex{exc_info()}}
+\function{sys.exc_info()} to access the exception last raised in the
+current thread.
+
+There's one global variable left, however: the pointer to the current
+\ctype{PyThreadState}\ttindex{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:
+
+\begin{verbatim}
+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.
+\end{verbatim}
+
+This is so common that a pair of macros exists to simplify it:
+
+\begin{verbatim}
+Py_BEGIN_ALLOW_THREADS
+...Do some blocking I/O operation...
+Py_END_ALLOW_THREADS
+\end{verbatim}
+
+The \code{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS} macro
+opens a new block and declares a hidden local variable; the
+\code{Py_END_ALLOW_THREADS}\ttindex{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:
+
+\begin{verbatim}
+    PyThreadState *_save;
+
+    _save = PyEval_SaveThread();
+    ...Do some blocking I/O operation...
+    PyEval_RestoreThread(_save);
+\end{verbatim}
+
+Using even lower level primitives, we can get roughly the same effect
+as follows:
+
+\begin{verbatim}
+    PyThreadState *_save;
+
+    _save = PyThreadState_Swap(NULL);
+    PyEval_ReleaseLock();
+    ...Do some blocking I/O operation...
+    PyEval_AcquireLock();
+    PyThreadState_Swap(_save);
+\end{verbatim}
+
+There are some subtle differences; in particular,
+\cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves
+and restores the value of the  global variable
+\cdata{errno}\ttindex{errno}, since the lock manipulation does not
+guarantee that \cdata{errno} is left alone.  Also, when thread support
+is disabled,
+\cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
+\cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this
+case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and
+\cfunction{PyEval_AcquireLock()}\ttindex{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.
+
+When creating a thread data structure, you need to provide an
+interpreter state data structure.  The interpreter state data
+structure hold global data that is shared by all threads in an
+interpreter, for example the module administration
+(\code{sys.modules}).  Depending on your needs, you can either create
+a new interpreter state data structure, or share the interpreter state
+data structure used by the Python main thread (to access the latter,
+you must obtain the thread state and access its \member{interp} member;
+this must be done by a thread that is created by Python or by the main
+thread after Python is initialized).
+
+
+\begin{ctypedesc}{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.
+\end{ctypedesc}
+
+\begin{ctypedesc}{PyThreadState}
+  This data structure represents the state of a single thread.  The
+  only public data member is \ctype{PyInterpreterState
+  *}\member{interp}, which points to this thread's interpreter state.
+\end{ctypedesc}
+
+\begin{cfuncdesc}{void}{PyEval_InitThreads}{}
+  Initialize and acquire the global interpreter lock.  It should be
+  called in the main thread before creating a second thread or
+  engaging in any other thread operations such as
+  \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or
+  \code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}.
+  It is not needed before calling
+  \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or
+  \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}.
+
+  This is a no-op when called for a second time.  It is safe to call
+  this function before calling
+  \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
+
+  When only the main thread exists, no lock operations are needed.
+  This is a common situation (most Python programs do not use
+  threads), and the lock operations slow the interpreter down a bit.
+  Therefore, the lock is not created initially.  This situation is
+  equivalent to having acquired the lock: when there is only a single
+  thread, all object accesses are safe.  Therefore, when this function
+  initializes the lock, it also acquires it.  Before the Python
+  \module{thread}\refbimodindex{thread} module creates a new thread,
+  knowing that either it has the lock or the lock hasn't been created
+  yet, it calls \cfunction{PyEval_InitThreads()}.  When this call
+  returns, it is guaranteed that the lock has been created and that it
+  has acquired it.
+
+  It is \strong{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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
+  Acquire the global interpreter lock.  The lock must have been
+  created earlier.  If this thread already has the lock, a deadlock
+  ensues.  This function is not available when thread support is
+  disabled at compile time.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
+  Release the global interpreter lock.  The lock must have been
+  created earlier.  This function is not available when thread support
+  is disabled at compile time.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
+  Acquire the global interpreter lock and then set the current thread
+  state to \var{tstate}, which should not be \NULL.  The lock must
+  have been created earlier.  If this thread already has the lock,
+  deadlock ensues.  This function is not available when thread support
+  is disabled at compile time.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
+  Reset the current thread state to \NULL{} and release the global
+  interpreter lock.  The lock must have been created earlier and must
+  be held by the current thread.  The \var{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.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
+  Release the interpreter lock (if it has been created and thread
+  support is enabled) and reset the thread state to \NULL, returning
+  the previous thread state (which is not \NULL).  If the lock has
+  been created, the current thread must have acquired it.  (This
+  function is available even when thread support is disabled at
+  compile time.)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
+  Acquire the interpreter lock (if it has been created and thread
+  support is enabled) and set the thread state to \var{tstate}, which
+  must not be \NULL.  If the lock has been created, the current thread
+  must not have acquired it, otherwise deadlock ensues.  (This
+  function is available even when thread support is disabled at
+  compile time.)
+\end{cfuncdesc}
+
+The following macros are normally used without a trailing semicolon;
+look for example usage in the Python source distribution.
+
+\begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
+  This macro expands to
+  \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
+  Note that it contains an opening brace; it must be matched with a
+  following \code{Py_END_ALLOW_THREADS} macro.  See above for further
+  discussion of this macro.  It is a no-op when thread support is
+  disabled at compile time.
+\end{csimplemacrodesc}
+
+\begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
+  This macro expands to \samp{PyEval_RestoreThread(_save); \}}.
+  Note that it contains a closing brace; it must be matched with an
+  earlier \code{Py_BEGIN_ALLOW_THREADS} macro.  See above for further
+  discussion of this macro.  It is a no-op when thread support is
+  disabled at compile time.
+\end{csimplemacrodesc}
+
+\begin{csimplemacrodesc}{Py_BLOCK_THREADS}
+  This macro expands to \samp{PyEval_RestoreThread(_save);}: it is
+  equivalent to \code{Py_END_ALLOW_THREADS} without the closing brace.
+  It is a no-op when thread support is disabled at compile time.
+\end{csimplemacrodesc}
+
+\begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
+  This macro expands to \samp{_save = PyEval_SaveThread();}: it is
+  equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening
+  brace and variable declaration.  It is a no-op when thread support
+  is disabled at compile time.
+\end{csimplemacrodesc}
+
+All of the following functions are only available when thread support
+is enabled at compile time, and must be called only when the
+interpreter lock has been created.
+
+\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{}
+  Create a new interpreter state object.  The interpreter lock need
+  not be held, but may be held if it is necessary to serialize calls
+  to this function.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
+  Reset all information in an interpreter state object.  The
+  interpreter lock must be held.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
+  Destroy an interpreter state object.  The interpreter lock need not
+  be held.  The interpreter state must have been reset with a previous
+  call to \cfunction{PyInterpreterState_Clear()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{PyThreadState_New}{PyInterpreterState *interp}
+  Create a new thread state object belonging to the given interpreter
+  object.  The interpreter lock need not be held, but may be held if
+  it is necessary to serialize calls to this function.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
+  Reset all information in a thread state object.  The interpreter lock
+  must be held.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
+  Destroy a thread state object.  The interpreter lock need not be
+  held.  The thread state must have been reset with a previous call to
+  \cfunction{PyThreadState_Clear()}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
+  Return the current thread state.  The interpreter lock must be
+  held.  When the current thread state is \NULL, this issues a fatal
+  error (so that the caller needn't check for \NULL).
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Swap}{PyThreadState *tstate}
+  Swap the current thread state with the thread state given by the
+  argument \var{tstate}, which may be \NULL.  The interpreter lock
+  must be held.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{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.  If this function returns \NULL, an
+  exception has been raised and the caller should allow it to
+  propogate.
+\end{cfuncdesc}
+
+
+\section{Profiling and Tracing \label{profiling}}
+
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+The Python interpreter provides some low-level support for attaching
+profiling and execution tracing facilities.  These are used for
+profiling, debugging, and coverage analysis tools.
+
+Starting with Python 2.2, the implementation of this facility was
+substantially revised, and an interface from C was added.  This C
+interface allows the profiling or tracing code to avoid the overhead
+of calling through Python-level callable objects, making a direct C
+function call instead.  The essential attributes of the facility have
+not changed; the interface allows trace functions to be installed
+per-thread, and the basic events reported to the trace function are
+the same as had been reported to the Python-level trace functions in
+previous versions.
+
+\begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj,
+                                PyFrameObject *frame, int what,
+                                PyObject *arg)}
+  The type of the trace function registered using
+  \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
+  The first parameter is the object passed to the registration
+  function as \var{obj}, \var{frame} is the frame object to which the
+  event pertains, \var{what} is one of the constants
+  \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPT},
+  \constant{PyTrace_LINE} or \constant{PyTrace_RETURN}, and \var{arg}
+  depends on the value of \var{what}:
+
+  \begin{tableii}{l|l}{constant}{Value of \var{what}}{Meaning of \var{arg}}
+    \lineii{PyTrace_CALL}{Always \NULL.}
+    \lineii{PyTrace_EXCEPT}{Exception information as returned by
+                            \function{sys.exc_info()}.}
+    \lineii{PyTrace_LINE}{Always \NULL.}
+    \lineii{PyTrace_RETURN}{Value being returned to the caller.}
+  \end{tableii}
+\end{ctypedesc}
+
+\begin{cvardesc}{int}{PyTrace_CALL}
+  The value of the \var{what} parameter to a \ctype{Py_tracefunc}
+  function when a new call to a function or method is being reported,
+  or a new entry into a generator.  Note that the creation of the
+  iterator for a generator function is not reported as there is no
+  control transfer to the Python bytecode in the corresponding frame.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{PyTrace_EXCEPT}
+  The value of the \var{what} parameter to a \ctype{Py_tracefunc}
+  function when an exception has been raised by Python code as the
+  result of an operation.  The operation may have explictly intended
+  to raise the operation (as with a \keyword{raise} statement), or may
+  have triggered an exception in the runtime as a result of the
+  specific operation.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{PyTrace_LINE}
+  The value passed as the \var{what} parameter to a trace function
+  (but not a profiling function) when a line-number event is being
+  reported.
+\end{cvardesc}
+
+\begin{cvardesc}{int}{PyTrace_RETURN}
+  The value for the \var{what} parameter to \ctype{Py_tracefunc}
+  functions when a call is returning without propogating an exception.
+\end{cvardesc}
+
+\begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj}
+  Set the profiler function to \var{func}.  The \var{obj} parameter is
+  passed to the function as its first parameter, and may be any Python
+  object, or \NULL.  If the profile function needs to maintain state,
+  using a different value for \var{obj} for each thread provides a
+  convenient and thread-safe place to store it.  The profile function
+  is called for all monitored events except the line-number events.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj}
+  Set the the tracing function to \var{func}.  This is similar to
+  \cfunction{PyEval_SetProfile()}, except the tracing function does
+  receive line-number events.
+\end{cfuncdesc}
+
+
+\section{Advanced Debugger Support \label{advanced-debugging}}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+These functions are only intended to be used by advanced debugging
+tools.
+
+\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{}
+  Return the interpreter state object at the head of the list of all
+  such objects.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp}
+  Return the next interpreter state object after \var{interp} from the
+  list of all such objects.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp}
+  Return the a pointer to the first \ctype{PyThreadState} object in
+  the list of threads associated with the interpreter \var{interp}.
+  \versionadded{2.2}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate}
+  Return the next thread state object after \var{tstate} from the list
+  of all such objects belonging to the same \ctype{PyInterpreterState}
+  object.
+  \versionadded{2.2}
+\end{cfuncdesc}