cpython/Doc/ext/ext.tex

\documentstyle[twoside,11pt,myformat,times]{report}

\title{\bf Extending and Embedding the Python Interpreter}

\author{
	Guido van Rossum \\
	Dept. CST, CWI, P.O. Box 94079 \\
	1090 GB Amsterdam, The Netherlands \\
	E-mail: {\tt guido@cwi.nl}
}

% Tell \index to actually write the .idx file
\makeindex

\begin{document}

\pagenumbering{roman}

\maketitle

\begin{abstract}

\noindent
This document describes how to write modules in C or C++ to extend the
Python interpreter.  It also describes how to use Python as an
`embedded' language, and how extension modules can be loaded
dynamically (at run time) into the interpreter, if the operating
system supports this feature.

\end{abstract}

\pagebreak

{
\parskip = 0mm
\tableofcontents
}

\pagebreak

\pagenumbering{arabic}


\chapter{Extending Python with C or C++ code}


\section{Introduction}

It is quite easy to add non-standard built-in modules to Python, if
you know how to program in C.  A built-in module known to the Python
programmer as \code{foo} is generally implemented by a file called
\file{foomodule.c}.  All but the most essential standard built-in
modules also adhere to this convention, and in fact some of them form
excellent examples of how to create an extension.

Extension modules can do two things that can't be done directly in
Python: they can implement new data types, and they can make system
calls or call C library functions.  Since the latter is usually the
most important reason for adding an extension, I'll concentrate on
adding `wrappers' around C library functions; the concrete example
uses the wrapper for
\code{system()} in module \code{posix}, found in (of course) the file
\file{posixmodule.c}.

It is important not to be impressed by the size and complexity of
the average extension module; much of this is straightforward
`boilerplate' code (starting right with the copyright notice)!

Let's skip the boilerplate and have a look at an interesting function
in \file{posixmodule.c} first:

\begin{verbatim}
    static object *
    posix_system(self, args)
        object *self;
        object *args;
    {
        char *command;
        int sts;
        if (!getargs(args, "s", &command))
            return NULL;
        sts = system(command);
        return mkvalue("i", sts);
    }
\end{verbatim}

This is the prototypical top-level function in an extension module.
It will be called (we'll see later how this is made possible) when the
Python program executes statements like

\begin{verbatim}
    >>> import posix
    >>> sts = posix.system('ls -l')
\end{verbatim}

There is a straightforward translation from the arguments to the call
in Python (here the single value \code{'ls -l'}) to the arguments that
are passed to the C function.  The C function always has two
parameters, conventionally named \var{self} and \var{args}.  In this
example, \var{self} will always be a \code{NULL} pointer, since this is a
function, not a method (this is done so that the interpreter doesn't
have to understand two different types of C functions).

The \var{args} parameter will be a pointer to a Python object, or
\code{NULL} if the Python function/method was called without
arguments.  It is necessary to do full argument type checking on each
call, since otherwise the Python user would be able to cause the
Python interpreter to `dump core' by passing the wrong arguments to a
function in an extension module (or no arguments at all).  Because
argument checking and converting arguments to C is such a common task,
there's a general function in the Python interpreter which combines
these tasks: \code{getargs()}.  It uses a template string to determine
both the types of the Python argument and the types of the C variables
into which it should store the converted values.  (More about this
later.)\footnote{
There are convenience macros \code{getstrarg()},
\code{getintarg()}, etc., for many common forms of \code{getargs()}
templates.  These are relics from the past; it's better to call
\code{getargs()} directly.}

If \code{getargs()} returns nonzero, the argument list has the right
type and its components have been stored in the variables whose
addresses are passed.  If it returns zero, an error has occurred.  In
the latter case it has already raised an appropriate exception by
calling \code{err_setstr()}, so the calling function can just return
\code{NULL}.


\section{Intermezzo: errors and exceptions}

An important convention throughout the Python interpreter is the
following: when a function fails, it should set an exception condition
and return an error value (often a NULL pointer).  Exceptions are set
in a global variable in the file errors.c; if this variable is NULL no
exception has occurred.  A second variable is the `associated value'
of the exception.

The file errors.h declares a host of err_* functions to set various
types of exceptions.  The most common one is \code{err_setstr()} --- its
arguments are an exception object (e.g. RuntimeError --- actually it
can be any string object) and a C string indicating the cause of the
error (this is converted to a string object and stored as the
`associated value' of the exception).  Another useful function is
\code{err_errno()}, which only takes an exception argument and
constructs the associated value by inspection of the (UNIX) global
variable errno.

You can test non-destructively whether an exception has been set with
\code{err_occurred()}.  However, most code never calls
\code{err_occurred()} to see whether an error occurred or not, but
relies on error return values from the functions it calls instead:

When a function that calls another function detects that the called
function fails, it should return an error value but not set an
condition --- one is already set.  The caller is then supposed to also
return an error indication to *its* caller, again *without* calling
\code{err_setstr()}, and so on --- the most detailed cause of the error
was already reported by the function that detected it in the first
place.  Once the error has reached Python's interpreter main loop,
this aborts the currently executing Python code and tries to find an
exception handler specified by the Python programmer.

To ignore an exception set by a function call that failed, the
exception condition must be cleared explicitly by calling
\code{err_clear()}.  The only time C code should call
\code{err_clear()} is if it doesn't want to pass the error on to the
interpreter but wants to handle it completely by itself (e.g. by
trying something else or pretending nothing happened).

Finally, the function \code{err_get()} gives you both error variables
*and clears them*.  Note that even if an error occurred the second one
may be NULL.  I doubt you will need to use this function.

Note that a failing \code{malloc()} call must also be turned into an
exception --- the direct caller of \code{malloc()} (or
\code{realloc()}) must call \code{err_nomem()} and return a failure
indicator itself.  All the object-creating functions
(\code{newintobject()} etc.) already do this, so only if you call
\code{malloc()} directly this note is of importance.

Also note that, with the important exception of \code{getargs()}, functions
that return an integer status usually use 0 for success and -1 for
failure.

Finally, be careful about cleaning up garbage (making appropriate
[\code{X}]\code{DECREF()} calls) when you return an error!


\section{Back to the example}

Going back to posix_system, you should now be able to understand this
bit:

\begin{verbatim}
        if (!getargs(args, "s", &command))
            return NULL;
\end{verbatim}

It returns NULL (the error indicator for functions of this kind) if an
error is detected in the argument list, relying on the exception set
by \code{getargs()}.  The string value of the argument is now copied to the
local variable 'command'.

If a Python function is called with multiple arguments, the argument
list is turned into a tuple.  Python programs can us this feature, for
instance, to explicitly create the tuple containing the arguments
first and make the call later.

The next statement in posix_system is a call tothe C library function
\code{system()}, passing it the string we just got from \code{getargs()}:

\begin{verbatim}
        sts = system(command);
\end{verbatim}

Python strings may contain internal null bytes; but if these occur in
this example the rest of the string will be ignored by \code{system()}.

Finally, posix.\code{system()} must return a value: the integer status
returned by the C library \code{system()} function.  This is done by the
function \code{newintobject()}, which takes a (long) integer as parameter.

\begin{verbatim}
        return newintobject((long)sts);
\end{verbatim}

(Yes, even integers are represented as objects on the heap in Python!)
If you had a function that returned no useful argument, you would need
this idiom:

\begin{verbatim}
        INCREF(None);
        return None;
\end{verbatim}

'None' is a unique Python object representing 'no value'.  It differs
from NULL, which means 'error' in most contexts (except when passed as
a function argument --- there it means 'no arguments').


\section{The module's function table}

I promised to show how I made the function \code{posix_system()}
available to Python programs.  This is shown later in posixmodule.c:

\begin{verbatim}
    static struct methodlist posix_methods[] = {
        ...
        {"system",  posix_system},
        ...
        {NULL,      NULL}        /* Sentinel */
    };

    void
    initposix()
    {
        (void) initmodule("posix", posix_methods);
    }
\end{verbatim}

(The actual \code{initposix()} is somewhat more complicated, but most
extension modules are indeed as simple as that.)  When the Python
program first imports module 'posix', \code{initposix()} is called,
which calls \code{initmodule()} with specific parameters.  This
creates a module object (which is inserted in the table sys.modules
under the key 'posix'), and adds built-in-function objects to the
newly created module based upon the table (of type struct methodlist)
that was passed as its second parameter.  The function
\code{initmodule()} returns a pointer to the module object that it
creates, but this is unused here.  It aborts with a fatal error if the
module could not be initialized satisfactorily.


\section{Calling the module initialization function}

There is one more thing to do: telling the Python module to call the
\code{initfoo()} function when it encounters an 'import foo' statement.
This is done in the file config.c.  This file contains a table mapping
module names to parameterless void function pointers.  You need to add
a declaration of \code{initfoo()} somewhere early in the file, and a
line saying

\begin{verbatim}
    {"foo",     initfoo},
\end{verbatim}

to the initializer for inittab[].  It is conventional to include both
the declaration and the initializer line in preprocessor commands
\code{\#ifdef USE_FOO} / \code{\#endif}, to make it easy to turn the
foo extension on or off.  Note that the Macintosh version uses a
different configuration file, distributed as configmac.c.  This
strategy may be extended to other operating system versions, although
usually the standard config.c file gives a pretty useful starting
point for a new config*.c file.

And, of course, I forgot the Makefile.  This is actually not too hard,
just follow the examples for, say, AMOEBA.  Just find all occurrences
of the string AMOEBA in the Makefile and do the same for FOO that's
done for AMOEBA...

(Note: if you are using dynamic loading for your extension, you don't
need to edit config.c and the Makefile.  See \file{./DYNLOAD} for more
info about this.)


\section{Calling Python functions from C}

The above concentrates on making C functions accessible to the Python
programmer.  The reverse is also often useful: calling Python
functions from C.  This is especially the case for libraries that
support so-called `callback' functions.  If a C interface makes heavy
use of callbacks, the equivalent Python often needs to provide a
callback mechanism to the Python programmer; the implementation may
require calling the Python callback functions from a C callback.
Other uses are also possible.

Fortunately, the Python interpreter is easily called recursively, and
there is a standard interface to call a Python function.  I won't
dwell on how to call the Python parser with a particular string as
input --- if you're interested, have a look at the implementation of
the \samp{-c} command line option in pythonmain.c.

Calling a Python function is easy.  First, the Python program must
somehow pass you the Python function object.  You should provide a
function (or some other interface) to do this.  When this function is
called, save a pointer to the Python function object (be careful to
INCREF it!) in a global variable --- or whereever you see fit.
For example, the following function might be part of a module
definition:

\begin{verbatim}
    static object *my_callback;

    static object *
    my_set_callback(dummy, arg)
        object *dummy, *arg;
    {
        XDECREF(my_callback); /* Dispose of previous callback */
        my_callback = arg;
        XINCREF(my_callback); /* Remember new callback */
        /* Boilerplate for "void" return */
        INCREF(None);
        return None;
    }
\end{verbatim}

Later, when it is time to call the function, you call the C function
\code{call_object()}.  This function has two arguments, both pointers
to arbitrary Python objects: the Python function, and the argument.
The argument can be NULL to call the function without arguments.  For
example:

\begin{verbatim}
    object *result;
    ...
    /* Time to call the callback */
    result = call_object(my_callback, (object *)NULL);
\end{verbatim}

\code{call_object()} returns a Python object pointer: this is
the return value of the Python function.  \code{call_object()} is
`reference-count-neutral' with respect to its arguments, but the
return value is `new': either it is a brand new object, or it is an
existing object whose reference count has been incremented.  So, you
should somehow apply DECREF to the result, even (especially!) if you
are not interested in its value.

Before you do this, however, it is important to check that the return
value isn't NULL.  If it is, the Python function terminated by raising
an exception.  If the C code that called \code{call_object()} is
called from Python, it should now return an error indication to its
Python caller, so the interpreter can print a stack trace, or the
calling Python code can handle the exception.  If this is not possible
or desirable, the exception should be cleared by calling
\code{err_clear()}.  For example:

\begin{verbatim}
    if (result == NULL)
        return NULL; /* Pass error back */
    /* Here maybe use the result */
    DECREF(result); 
\end{verbatim}

Depending on the desired interface to the Python callback function,
you may also have to provide an argument to \code{call_object()}.  In
some cases the argument is also provided by the Python program,
through the same interface that specified the callback function.  It
can then be saved and used in the same manner as the function object.
In other cases, you may have to construct a new object to pass as
argument.  In this case you must dispose of it as well.  For example,
if you want to pass an integral event code, you might use the
following code:

\begin{verbatim}
    object *argument;
    ...
    argument = newintobject((long)eventcode);
    result = call_object(my_callback, argument);
    DECREF(argument);
    if (result == NULL)
        return NULL; /* Pass error back */
    /* Here maybe use the result */
    DECREF(result);
\end{verbatim}

Note the placement of DECREF(argument) immediately after the call,
before the error check!  Also note that strictly spoken this code is
not complete: \code{newintobject()} may run out of memory, and this
should be checked.

In even more complicated cases you may want to pass the callback
function multiple arguments.  To this end you have to construct (and
dispose of!) a tuple object.  Details (mostly concerned with the
errror checks and reference count manipulation) are left as an
exercise for the reader; most of this is also needed when returning
multiple values from a function.

XXX TO DO: explain objects.

XXX TO DO: defining new object types.


\section{Format strings for {\tt getargs()}}

The \code{getargs()} function is declared in \file{modsupport.h} as
follows:

\begin{verbatim}
    int getargs(object *arg, char *format, ...);
\end{verbatim}

The remaining arguments must be addresses of variables whose type is
determined by the format string.  For the conversion to succeed, the
`arg' object must match the format and the format must be exhausted.
Note that while \code{getargs()} checks that the Python object really
is of the specified type, it cannot check that the addresses provided
in the call match: if you make mistakes there, your code will probably
dump core.

A format string consists of a single `format unit'.  A format unit
describes one Python object; it is usually a single character or a
parenthesized string.  The type of a format units is determined from
its first character, the `format letter':

\begin{description}

\item[\samp{s} (string)]
The Python object must be a string object.  The C argument must be a
char** (i.e. the address of a character pointer), and a pointer to
the C string contained in the Python object is stored into it. If the
next character in the format string is \samp{\#}, another C argument
of type int* must be present, and the length of the Python string (not
counting the trailing zero byte) is stored into it.

\item[\samp{z} (string or zero, i.e. \code{NULL})]
Like \samp{s}, but the object may also be None.  In this case the
string pointer is set to NULL and if a \samp{\#} is present the size
it set to 0.

\item[\samp{b} (byte, i.e. char interpreted as tiny int)]
The object must be a Python integer.  The C argument must be a char*.

\item[\samp{h} (half, i.e. short)]
The object must be a Python integer.  The C argument must be a short*.

\item[\samp{i} (int)]
The object must be a Python integer.  The C argument must be an int*.

\item[\samp{l} (long)]
The object must be a (plain!) Python integer.  The C argument must be
a long*.

\item[\samp{c} (char)]
The Python object must be a string of length 1.  The C argument must
be a char*.  (Don't pass an int*!)

\item[\samp{f} (float)]
The object must be a Python int or float.  The C argument must be a
float*.

\item[\samp{d} (double)]
The object must be a Python int or float.  The C argument must be a
double*.

\item[\samp{S} (string object)]
The object must be a Python string.  The C argument must be an
object** (i.e. the address of an object pointer).  The C program thus
gets back the actual string object that was passed, not just a pointer
to its array of characters and its size as for format character
\samp{s}.

\item[\samp{O} (object)]
The object can be any Python object, including None, but not NULL.
The C argument must be an object**.  This can be used if an argument
list must contain objects of a type for which no format letter exist:
the caller must then check that it has the right type.

\item[\samp{(} (tuple)]
The object must be a Python tuple.  Following the \samp{(} character
in the format string must come a number of format units describing the
elements of the tuple, followed by a \samp{)} character.  Tuple
format units may be nested.  (There are no exceptions for empty and
singleton tuples; \samp{()} specifies an empty tuple and \samp{(i)} a
singleton of one integer.  Normally you don't want to use the latter,
since it is hard for the user to specify.

\end{description}

More format characters will probably be added as the need arises.  It
should be allowed to use Python long integers whereever integers are
expected, and perform a range check.  (A range check is in fact always
necessary for the \samp{b}, \samp{h} and \samp{i} format
letters, but this is currently not implemented.)

Some example calls:

\begin{verbatim}
    int ok;
    int i, j;
    long k, l;
    char *s;
    int size;

    ok = getargs(args, "(lls)", &k, &l, &s); /* Two longs and a string */
        /* Possible Python call: f(1, 2, 'three') */
    
    ok = getargs(args, "s", &s); /* A string */
        /* Possible Python call: f('whoops!') */

    ok = getargs(args, ""); /* No arguments */
        /* Python call: f() */
    
    ok = getargs(args, "((ii)s#)", &i, &j, &s, &size);
        /* A pair of ints and a string, whose size is also returned */
        /* Possible Python call: f(1, 2, 'three') */

    {
        int left, top, right, bottom, h, v;
        ok = getargs(args, "(((ii)(ii))(ii))",
                 &left, &top, &right, &bottom, &h, &v);
                 /* A rectangle and a point */
                 /* Possible Python call:
                    f( ((0, 0), (400, 300)), (10, 10)) */
    }
\end{verbatim}

Note that a format string must consist of a single unit; strings like
\samp{is} and \samp{(ii)s\#} are not valid format strings.  (But
\samp{s\#} is.)

The \code{getargs()} function does not support variable-length
argument lists.  In simple cases you can fake these by trying several
calls to
\code{getargs()} until one succeeds, but you must take care to call
\code{err_clear()} before each retry.  For example:

\begin{verbatim}
    static object *my_method(self, args) object *self, *args; {
        int i, j, k;

        if (getargs(args, "(ii)", &i, &j)) {
            k = 0; /* Use default third argument */
        }
        else {
            err_clear();
            if (!getargs(args, "(iii)", &i, &j, &k))
                return NULL;
        }
        /* ... use i, j and k here ... */
        INCREF(None);
        return None;
    }
\end{verbatim}

(It is possible to think of an extension to the definition of format
strings to accomodate this directly, e.g., placing a \samp{|} in a
tuple might specify that the remaining arguments are optional.
\code{getargs()} should then return one more than the number of
variables stored into.)

Advanced users note: If you set the `varargs' flag in the method list
for a function, the argument will always be a tuple (the `raw argument
list').  In this case you must enclose single and empty argument lists
in parentheses, e.g., \samp{(s)} and \samp{()}.


\section{The {\tt mkvalue()} function}

This function is the counterpart to \code{getargs()}.  It is declared
in \file{modsupport.h} as follows:

\begin{verbatim}
    object *mkvalue(char *format, ...);
\end{verbatim}

It supports exactly the same format letters as \code{getargs()}, but
the arguments (which are input to the function, not output) must not
be pointers, just values.  If a byte, short or float is passed to a
varargs function, it is widened by the compiler to int or double, so
\samp{b} and \samp{h} are treated as \samp{i} and \samp{f} is
treated as \samp{d}.  \samp{S} is treated as \samp{O}, \samp{s} is
treated as \samp{z}.  \samp{z\#} and \samp{s\#} are supported: a
second argument specifies the length of the data (negative means use
\code{strlen()}).  \samp{S} and \samp{O} add a reference to their
argument (so you should \code{DECREF()} it if you've just created it
and aren't going to use it again).

If the argument for \samp{O} or \samp{S} is a NULL pointer, it is
assumed that this was caused because the call producing the argument
found an error and set an exception.  Therefore, \code{mkvalue()} will
return \code{NULL} but won't set an exception if one is already set.
If no exception is set, \code{SystemError} is set.

If there is an error in the format string, the \code{SystemError}
exception is set, since it is the calling C code's fault, not that of
the Python user who sees the exception.

Example:

\begin{verbatim}
    return mkvalue("(ii)", 0, 0);
\end{verbatim}

returns a tuple containing two zeros.  (Outer parentheses in the
format string are actually superfluous, but you can use them for
compatibility with \code{getargs()}, which requires them if more than
one argument is expected.)


\section{Reference counts}

Here's a useful explanation of \code{INCREF()} and \code{DECREF()}
(after an original by Sjoerd Mullender).

Use \code{XINCREF()} or \code{XDECREF()} instead of \code{INCREF()} /
\code{DECREF()} when the argument may be \code{NULL}.

The basic idea is, if you create an extra reference to an object, you
must \code{INCREF()} it, if you throw away a reference to an object,
you must \code{DECREF()} it.  Functions such as
\code{newstringobject()}, \code{newsizedstringobject()},
\code{newintobject()}, etc. create a reference to an object.  If you
want to throw away the object thus created, you must use
\code{DECREF()}.

If you put an object into a tuple or list using \code{settupleitem()}
or \code{setlistitem()}, the idea is that you usually don't want to
keep a reference of your own around, so Python does not
\code{INCREF()} the elements.  It does \code{DECREF()} the old value.
This means that if you put something into such an object using the
functions Python provides for this, you must \code{INCREF()} the
object if you also want to keep a separate reference to the object around.
Also, if you replace an element, you should \code{INCREF()} the old
element first if you want to keep it.  If you didn't \code{INCREF()}
it before you replaced it, you are not allowed to look at it anymore,
since it may have been freed.

Returning an object to Python (i.e. when your C function returns)
creates a reference to an object, but it does not change the reference
count.  When your code does not keep another reference to the object,
you should not \code{INCREF()} or \code{DECREF()} it (assuming it is a
newly created object).  When you do keep a reference around, you
should \code{INCREF()} the object.  Also, when you return a global
object such as \code{None}, you should \code{INCREF()} it.

If you want to return a tuple, you should consider using
\code{mkvalue()}.  This function creates a new tuple with a reference
count of 1 which you can return.  If any of the elements you put into
the tuple are objects (format codes \samp{O} or \samp{S}), they
are \code{INCREF()}'ed by \code{mkvalue()}.  If you don't want to keep
references to those elements around, you should \code{DECREF()} them
after having called \code{mkvalue()}.

Usually you don't have to worry about arguments.  They are
\code{INCREF()}'ed before your function is called and
\code{DECREF()}'ed after your function returns.  When you keep a
reference to an argument, you should \code{INCREF()} it and
\code{DECREF()} when you throw it away.  Also, when you return an
argument, you should \code{INCREF()} it, because returning the
argument creates an extra reference to it.

If you use \code{getargs()} to parse the arguments, you can get a
reference to an object (by using \samp{O} in the format string).  This
object was not \code{INCREF()}'ed, so you should not \code{DECREF()}
it.  If you want to keep the object, you must \code{INCREF()} it
yourself.

If you create your own type of objects, you should use \code{NEWOBJ()}
to create the object.  This sets the reference count to 1.  If you
want to throw away the object, you should use \code{DECREF()}.  When
the reference count reaches zero, your type's \code{dealloc()}
function is called.  In it, you should \code{DECREF()} all object to
which you keep references in your object, but you should not use
\code{DECREF()} on your object.  You should use \code{DEL()} instead.


\section{Using C++}

It is possible to write extension modules in C++.  Some restrictions
apply: since the main program (the Python interpreter) is compiled and
linked by the C compiler, global or static objects with constructors
cannot be used.  All functions that will be called directly or
indirectly (i.e. via function pointers) by the Python interpreter will
have to be declared using \code{extern "C"}; this applies to all
`methods' as well as to the module's initialization function.
It is unnecessary to enclose the Python header files in
\code{extern "C" \{...\}} --- they do this already.


\chapter{Embedding Python in another application}

Embedding Python is similar to extending it, but not quite.  The
difference is that when you extend Python, the main program of the
application is still the Python interpreter, while of you embed
Python, the main program may have nothing to do with Python ---
instead, some parts of the application occasionally call the Python
interpreter to run some Python code.

So if you are embedding Python, you are providing your own main
program.  One of the things this main program has to do is initialize
the Python interpreter.  At the very least, you have to call the
function \code{initall()}.  There are optional calls to pass command
line arguments to Python.  Then later you can call the interpreter
from any part of the application.

There are several different ways to call the interpreter: you can pass
a string containing Python statements to \code{run_command()}, or you
can pass a stdio file pointer and a file name (for identification in
error messages only) to \code{run_script()}.  You can also call the
lower-level operations described in the previous chapters to construct
and use Python objects.

A simple demo of embedding Python can be found in the directory
\file{<pythonroot>/embed}.


\section{Using C++}

It is also possible to embed Python in a C++ program; how this is done
exactly will depend on the details of the C++ system used; in general
you will need to write the main program in C++, and use the C++
compiler to compile and link your program.  There is no need to
recompile Python itself with C++.


\chapter{Dynamic Loading}

On some systems (e.g., SunOS, SGI Irix) it is possible to configure
Python to support dynamic loading of modules implemented in C.  Once
configured and installed it's trivial to use: if a Python program
executes \code{import foo}, the search for modules tries to find a
file \file{foomodule.o} in the module search path, and if one is
found, it is linked with the executing binary and executed.  Once
linked, the module acts just like a built-in module.

The advantages of dynamic loading are twofold: the `core' Python
binary gets smaller, and users can extend Python with their own
modules implemented in C without having to build and maintain their
own copy of the Python interpreter.  There are also disadvantages:
dynamic loading isn't available on all systems (this just means that
on some systems you have to use static loading), and dynamically
loading a module that was compiled for a different version of Python
(e.g., with a different representation of objects) may dump core.

{\bf NEW:} Under SunOS, dynamic loading now uses SunOS shared
libraries and is always configured.  See at the end of this chapter
for how to create a dynamically loadable module.


\section{Configuring and building the interpreter for dynamic loading}

(Ignore this section for SunOS --- on SunOS dynamic loading is always
configured.)

Dynamic loading is a little complicated to configure, since its
implementation is extremely system dependent, and there are no
really standard libraries or interfaces for it.  I'm using an
extremely simple interface, which basically needs only one function:

\begin{verbatim}
    funcptr = dl_loadmod(binary, object, function)
\end{verbatim}

where \code{binary} is the pathname of the currently executing program
(not just \code{argv[0]}!), \code{object} is the name of the \samp{.o}
file to be dynamically loaded, and \code{function} is the name of a
function in the module.  If the dynamic loading succeeds,
\code{dl_loadmod()} returns a pointer to the named function; if not, it
returns \code{NULL}.

I provide two implementations of \code{dl_loadmod()}: one for SGI machines
running Irix 4.0 (written by my colleague Jack Jansen), and one that
is a thin interface layer for Wilson Ho's (GNU) dynamic loading
package \dfn{dld} (version 3.2.3).  Dld implements a much more powerful
version of dynamic loading than needed (including unlinking), but it
does not support System V's COFF object file format.  It currently
supports only VAX (Ultrix), Sun 3 (SunOS 3.4 and 4.0), SPARCstation
(SunOS 4.0), Sequent Symmetry (Dynix), and Atari ST (from the dld
3.2.3 README file).  Dld is part of the standard Python distribution;
if you didn't get it,many ftp archive sites carry dld these days, so
it won't be hard to get hold of it if you need it (using archie).

(If you don't know where to get dld, try anonymous ftp to
\file{wuarchive.wustl.edu:/mirrors2/gnu/dld-3.2.3.tar.Z}.  Jack's dld
can be found at \file{ftp.cwi.nl:/pub/python/dl.tar.Z}.)

To build a Python interpreter capable of dynamic loading, you need to
edit the Makefile.  Basically you must uncomment the lines starting
with \samp{\#DL_}, but you must also edit some of the lines to choose
which version of dl_loadmod to use, and fill in the pathname of the dld
library if you use it.  And, of course, you must first build
dl_loadmod and dld, if used.  (This is now done through the Configure
script.  For SunOS, everything is now automatic as long as the
architecture type is \code{sun4}.)


\section{Building a dynamically loadable module}

Building an object file usable by dynamic loading is easy, if you
follow these rules (substitute your module name for \code{foo}
everywhere):

\begin{itemize}

\item
The source filename must be \file{foomodule.c}, so the object
name is \file{foomodule.o}.

\item
The module must be written as a (statically linked) Python extension
module (described in an earlier chapter) except that no line for it
must be added to \file{config.c} and it mustn't be linked with the
main Python interpreter.

\item
The module's initialization function must be called \code{initfoo}; it
must install the module in \code{sys.modules} (generally by calling
\code{initmodule()} as explained earlier.

\item
The module must be compiled with \samp{-c}.  The resulting .o file must
not be stripped.

\item
Since the module must include many standard Python include files, it
must be compiled with a \samp{-I} option pointing to the Python source
directory (unless it resides there itself).

\item
On SGI Irix, the compiler flag \samp{-G0} (or \samp{-G 0}) must be passed.
IF THIS IS NOT DONE THE RESULTING CODE WILL NOT WORK.

\item
{\bf NEW:} On SunOS, you must create a shared library from your \samp{.o}
file using the following command (assuming your module is called
\code{foo}):

\begin{verbatim}
	ld -o foomodule.so foomodule.o <any other libraries needed>
\end{verbatim}

and place the resulting \samp{.so} file in the Python search path (not
the \samp{.o} file).  Note: on Solaris, you need to pass \samp{-G} to
the loader.

\end{itemize}


\section{Using libraries}

If your dynamically loadable module needs to be linked with one or
more libraries that aren't linked with Python (or if it needs a
routine that isn't used by Python from one of the libraries with which
Python is linked), you must specify a list of libraries to search
after loading the module in a file with extension \samp{.libs} (and
otherwise the same as your \samp{.o} file).  This file should contain
one or more lines containing whitespace-separated absolute library
pathnames.  When using the dl interface, \samp{-l...} flags may also
be used (it is in fact passed as an option list to the system linker
ld(1)), but the dl-dld interface requires absolute pathnames.  I
believe it is possible to specify shared libraries here.

(On SunOS, any extra libraries must be specified on the \code{ld}
command that creates the \samp{.so} file.)


\section{Caveats}

Dynamic loading requires that \code{main}'s \code{argv[0]} contains
the pathname or at least filename of the Python interpreter.
Unfortunately, when executing a directly executable Python script (an
executable file with \samp{\#!...} on the first line), the kernel
overwrites \code{argv[0]} with the name of the script.  There is no
easy way around this, so executable Python scripts cannot use
dynamically loaded modules.  (You can always write a simple shell
script that calls the Python interpreter with the script as its
input.)

When using dl, the overlay is first converted into an `overlay' for
the current process by the system linker (\code{ld}).  The overlay is
saved as a file with extension \samp{.ld}, either in the directory
where the \samp{.o} file lives or (if that can't be written) in a
temporary directory.  An existing \samp{.ld} file resulting from a
previous run (not from a temporary directory) is used, bypassing the
(costly) linking phase, provided its version matches the \samp{.o}
file and the current binary.  (See the \code{dl} man page for more
details.)


\input{ext.ind}

\end{document}