cpython-lru_cache-weakref: Doc/ext.tex annotate

annotate Doc/ext.tex @ 4566:6403c94de50d legacy-trunk

Added safeguard against failure in __del__.

author	Guido van Rossum <guido@python.org>
date	Wed, 27 Nov 1996 19:39:58 +0000
parents	a2dc7ce4dfbe
children	6ccf5dba8b0b

rev	line source
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1 \documentstyle[twoside,11pt,myformat]{report}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	2
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	3 % XXX PM Modulator
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	4
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	5 \title{Extending and Embedding the Python Interpreter}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	6
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1767 diff changeset	7 \input{boilerplate}
1412 00f1e8864dcc * {lib,ref,ext,tut}.tex: added explicit \date{<date> \\ <release>}. Guido van Rossum <guido@python.org> parents: 1411 diff changeset	8
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	9 % Tell \index to actually write the .idx file
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	10 \makeindex
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	11
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	12 \begin{document}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	13
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	14 \pagenumbering{roman}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	15
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	16 \maketitle
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	17
1934 f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1767 diff changeset	18 \input{copyright}
f3ae7c17ac08 Moved author and date to boilerplate.tex. Guido van Rossum <guido@python.org> parents: 1767 diff changeset	19
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	20 \begin{abstract}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	21
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	22 \noindent
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	23 Python is an interpreted, object-oriented programming language. This
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	24 document describes how to write modules in C or \Cpp{} to extend the
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	25 Python interpreter with new modules. Those modules can define new
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	26 functions but also new object types and their methods. The document
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	27 also describes how to embed the Python interpreter in another
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	28 application, for use as an extension language. Finally, it shows how
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	29 to compile and link extension modules so that they can be loaded
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	30 dynamically (at run time) into the interpreter, if the underlying
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	31 operating system supports this feature.
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	32
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	33 This document assumes basic knowledge about Python. For an informal
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	34 introduction to the language, see the Python Tutorial. The Python
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	35 Reference Manual gives a more formal definition of the language. The
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	36 Python Library Reference documents the existing object types,
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	37 functions and modules (both built-in and written in Python) that give
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	38 the language its wide application range.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	39
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	40 \end{abstract}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	41
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	42 \pagebreak
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	43
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	44 {
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	45 \parskip = 0mm
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	46 \tableofcontents
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	47 }
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	48
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	49 \pagebreak
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	50
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	51 \pagenumbering{arabic}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	52
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	53
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	54 \chapter{Extending Python with C or \Cpp{} code}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	55
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	56
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	57 \section{Introduction}
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	58
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	59 It is quite easy to add new built-in modules to Python, if you know
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	60 how to program in C. Such \dfn{extension modules} can do two things
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	61 that can't be done directly in Python: they can implement new built-in
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	62 object types, and they can call C library functions and system calls.
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	63
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	64 To support extensions, the Python API (Application Programmers
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	65 Interface) defines a set of functions, macros and variables that
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	66 provide access to most aspects of the Python run-time system. The
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	67 Python API is incorporated in a C source file by including the header
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	68 \code{"Python.h"}.
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	69
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	70 The compilation of an extension module depends on its intended use as
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	71 well as on your system setup; details are given in a later section.
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	72
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	73
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	74 \section{A Simple Example}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	75
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	76 Let's create an extension module called \samp{spam} (the favorite food
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	77 of Monty Python fans...) and let's say we want to create a Python
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	78 interface to the C library function \code{system()}.\footnote{An
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	79 interface for this function already exists in the standard module
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	80 \code{os} --- it was chosen as a simple and straightfoward example.}
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	81 This function takes a null-terminated character string as argument and
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	82 returns an integer. We want this function to be callable from Python
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	83 as follows:
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	84
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	85 \begin{verbatim}
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	86 >>> import spam
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	87 >>> status = spam.system("ls -l")
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	88 \end{verbatim}
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	89
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	90 Begin by creating a file \samp{spammodule.c}. (In general, if a
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	91 module is called \samp{spam}, the C file containing its implementation
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	92 is called \file{spammodule.c}; if the module name is very long, like
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	93 \samp{spammify}, the module name can be just \file{spammify.c}.)
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	94
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	95 The first line of our file can be:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	96
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	97 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	98 #include "Python.h"
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	99 \end{verbatim}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	100
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	101 which pulls in the Python API (you can add a comment describing the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	102 purpose of the module and a copyright notice if you like).
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	103
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	104 All user-visible symbols defined by \code{"Python.h"} have a prefix of
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	105 \samp{Py} or \samp{PY}, except those defined in standard header files.
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	106 For convenience, and since they are used extensively by the Python
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	107 interpreter, \code{"Python.h"} includes a few standard header files:
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	108 \code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, and
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	109 \code{<stdlib.h>}. If the latter header file does not exist on your
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	110 system, it declares the functions \code{malloc()}, \code{free()} and
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	111 \code{realloc()} directly.
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	112
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	113 The next thing we add to our module file is the C function that will
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	114 be called when the Python expression \samp{spam.system(\var{string})}
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	115 is evaluated (we'll see shortly how it ends up being called):
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	116
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	117 \begin{verbatim}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	118 static PyObject *
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	119 spam_system(self, args)
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	120 PyObject *self;
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	121 PyObject *args;
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	122 {
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	123 char *command;
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	124 int sts;
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	125 if (!PyArg_ParseTuple(args, "s", &command))
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	126 return NULL;
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	127 sts = system(command);
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	128 return Py_BuildValue("i", sts);
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	129 }
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	130 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	131
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	132 There is a straightforward translation from the argument list in
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	133 Python (e.g.\ the single expression \code{"ls -l"}) to the arguments
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	134 passed to the C function. The C function always has two arguments,
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	135 conventionally named \var{self} and \var{args}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	136
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	137 The \var{self} argument is only used when the C function implements a
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	138 builtin method. This will be discussed later. In the example,
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	139 \var{self} will always be a \code{NULL} pointer, since we are defining
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	140 a function, not a method. (This is done so that the interpreter
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	141 doesn't have to understand two different types of C functions.)
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	142
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	143 The \var{args} argument will be a pointer to a Python tuple object
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	144 containing the arguments. Each item of the tuple corresponds to an
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	145 argument in the call's argument list. The arguments are Python
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	146 objects -- in order to do anything with them in our C function we have
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	147 to convert them to C values. The function \code{PyArg_ParseTuple()}
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	148 in the Python API checks the argument types and converts them to C
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	149 values. It uses a template string to determine the required types of
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	150 the arguments as well as the types of the C variables into which to
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	151 store the converted values. More about this later.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	152
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	153 \code{PyArg_ParseTuple()} returns true (nonzero) if all arguments have
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	154 the right type and its components have been stored in the variables
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	155 whose addresses are passed. It returns false (zero) if an invalid
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	156 argument list was passed. In the latter case it also raises an
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	157 appropriate exception by so the calling function can return
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	158 \code{NULL} immediately (as we saw in the example).
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	159
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	160
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	161 \section{Intermezzo: Errors and Exceptions}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	162
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	163 An important convention throughout the Python interpreter is the
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	164 following: when a function fails, it should set an exception condition
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	165 and return an error value (usually a \code{NULL} pointer). Exceptions
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	166 are stored in a static global variable inside the interpreter; if this
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	167 variable is \code{NULL} no exception has occurred. A second global
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	168 variable stores the ``associated value'' of the exception (the second
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	169 argument to \code{raise}). A third variable contains the stack
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	170 traceback in case the error originated in Python code. These three
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	171 variables are the C equivalents of the Python variables
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	172 \code{sys.exc_type}, \code{sys.exc_value} and \code{sys.exc_traceback}
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	173 (see the section on module \code{sys} in the Library Reference
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	174 Manual). It is important to know about them to understand how errors
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	175 are passed around.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	176
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	177 The Python API defines a number of functions to set various types of
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	178 exceptions.
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	179
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	180 The most common one is \code{PyErr_SetString()}. Its arguments are an
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	181 exception object and a C string. The exception object is usually a
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	182 predefined object like \code{PyExc_ZeroDivisionError}. The C string
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	183 indicates the cause of the error and is converted to a Python string
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	184 object and stored as the ``associated value'' of the exception.
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	185
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	186 Another useful function is \code{PyErr_SetFromErrno()}, which only
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	187 takes an exception argument and constructs the associated value by
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	188 inspection of the (\UNIX{}) global variable \code{errno}. The most
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	189 general function is \code{PyErr_SetObject()}, which takes two object
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	190 arguments, the exception and its associated value. You don't need to
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	191 \code{Py_INCREF()} the objects passed to any of these functions.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	192
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	193 You can test non-destructively whether an exception has been set with
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	194 \code{PyErr_Occurred()}. This returns the current exception object,
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	195 or \code{NULL} if no exception has occurred. You normally don't need
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	196 to call \code{PyErr_Occurred()} to see whether an error occurred in a
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	197 function call, since you should be able to tell from the return value.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	198
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	199 When a function \var{f} that calls another function var{g} detects
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	200 that the latter fails, \var{f} should itself return an error value
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	201 (e.g. \code{NULL} or \code{-1}). It should \emph{not} call one of the
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	202 \code{PyErr_*()} functions --- one has already been called by \var{g}.
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	203 \var{f}'s caller is then supposed to also return an error indication
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	204 to \emph{its} caller, again \emph{without} calling \code{PyErr_*()},
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	205 and so on --- the most detailed cause of the error was already
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	206 reported by the function that first detected it. Once the error
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	207 reaches the Python interpreter's main loop, this aborts the currently
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	208 executing Python code and tries to find an exception handler specified
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	209 by the Python programmer.
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	210
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	211 (There are situations where a module can actually give a more detailed
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	212 error message by calling another \code{PyErr_*()} function, and in
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	213 such cases it is fine to do so. As a general rule, however, this is
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	214 not necessary, and can cause information about the cause of the error
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	215 to be lost: most operations can fail for a variety of reasons.)
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	216
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	217 To ignore an exception set by a function call that failed, the exception
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	218 condition must be cleared explicitly by calling \code{PyErr_Clear()}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	219 The only time C code should call \code{PyErr_Clear()} is if it doesn't
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	220 want to pass the error on to the interpreter but wants to handle it
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	221 completely by itself (e.g. by trying something else or pretending
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	222 nothing happened).
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	223
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	224 Note that a failing \code{malloc()} call must be turned into an
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	225 exception --- the direct caller of \code{malloc()} (or
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	226 \code{realloc()}) must call \code{PyErr_NoMemory()} and return a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	227 failure indicator itself. All the object-creating functions
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	228 (\code{PyInt_FromLong()} etc.) already do this, so only if you call
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	229 \code{malloc()} directly this note is of importance.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	230
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	231 Also note that, with the important exception of
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	232 \code{PyArg_ParseTuple()} and friends, functions that return an
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	233 integer status usually return a positive value or zero for success and
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	234 \code{-1} for failure, like \UNIX{} system calls.
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	235
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	236 Finally, be careful to clean up garbage (by making \code{Py_XDECREF()}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	237 or \code{Py_DECREF()} calls for objects you have already created) when
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	238 you return an error indicator!
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	239
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	240 The choice of which exception to raise is entirely yours. There are
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	241 predeclared C objects corresponding to all built-in Python exceptions,
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	242 e.g. \code{PyExc_ZeroDevisionError} which you can use directly. Of
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	243 course, you should choose exceptions wisely --- don't use
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	244 \code{PyExc_TypeError} to mean that a file couldn't be opened (that
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	245 should probably be \code{PyExc_IOError}). If something's wrong with
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	246 the argument list, the \code{PyArg_ParseTuple()} function usually
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	247 raises \code{PyExc_TypeError}. If you have an argument whose value
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	248 which must be in a particular range or must satisfy other conditions,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	249 \code{PyExc_ValueError} is appropriate.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	250
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	251 You can also define a new exception that is unique to your module.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	252 For this, you usually declare a static object variable at the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	253 beginning of your file, e.g.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	254
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	255 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	256 static PyObject *SpamError;
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	257 \end{verbatim}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	258
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	259 and initialize it in your module's initialization function
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	260 (\code{initspam()}) with a string object, e.g. (leaving out the error
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	261 checking for now):
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	262
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	263 \begin{verbatim}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	264 void
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	265 initspam()
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	266 {
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	267 PyObject m, d;
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	268 m = Py_InitModule("spam", SpamMethods);
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	269 d = PyModule_GetDict(m);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	270 SpamError = PyString_FromString("spam.error");
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	271 PyDict_SetItemString(d, "error", SpamError);
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	272 }
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	273 \end{verbatim}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	274
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	275 Note that the Python name for the exception object is
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	276 \code{spam.error}. It is conventional for module and exception names
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	277 to be spelled in lower case. It is also conventional that the
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	278 \emph{value} of the exception object is the same as its name, e.g.\
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	279 the string \code{"spam.error"}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	280
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	281
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	282 \section{Back to the Example}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	283
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	284 Going back to our example function, you should now be able to
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	285 understand this statement:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	286
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	287 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	288 if (!PyArg_ParseTuple(args, "s", &command))
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	289 return NULL;
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	290 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	291
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	292 It returns \code{NULL} (the error indicator for functions returning
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	293 object pointers) if an error is detected in the argument list, relying
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	294 on the exception set by \code{PyArg_ParseTuple()}. Otherwise the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	295 string value of the argument has been copied to the local variable
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	296 \code{command}. This is a pointer assignment and you are not supposed
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	297 to modify the string to which it points (so in Standard C, the variable
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	298 \code{command} should properly be declared as \samp{const char
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	299 *command}).
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	300
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	301 The next statement is a call to the \UNIX{} function \code{system()},
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	302 passing it the string we just got from \code{PyArg_ParseTuple()}:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	303
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	304 \begin{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	305 sts = system(command);
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	306 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	307
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	308 Our \code{spam.system()} function must return the value of \code{sys}
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	309 as a Python object. This is done using the function
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	310 \code{Py_BuildValue()}, which is something like the inverse of
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	311 \code{PyArg_ParseTuple()}: it takes a format string and an arbitrary
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	312 number of C values, and returns a new Python object. More info on
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	313 \code{Py_BuildValue()} is given later.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	314
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	315 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	316 return Py_BuildValue("i", sts);
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	317 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	318
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	319 In this case, it will return an integer object. (Yes, even integers
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	320 are objects on the heap in Python!)
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	321
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	322 If you have a C function that returns no useful argument (a function
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	323 returning \code{void}), the corresponding Python function must return
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	324 \code{None}. You need this idiom to do so:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	325
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	326 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	327 Py_INCREF(Py_None);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	328 return Py_None;
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	329 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	330
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	331 \code{Py_None} is the C name for the special Python object
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	332 \code{None}. It is a genuine Python object (not a \code{NULL}
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	333 pointer, which means ``error'' in most contexts, as we have seen).
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	334
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	335
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	336 \section{The Module's Method Table and Initialization Function}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	337
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	338 I promised to show how \code{spam_system()} is called from Python
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	339 programs. First, we need to list its name and address in a ``method
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	340 table'':
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	341
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	342 \begin{verbatim}
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	343 static PyMethodDef SpamMethods[] = {
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	344 ...
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	345 {"system", spam_system, 1},
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	346 ...
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	347 {NULL, NULL} /* Sentinel */
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	348 };
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	349 \end{verbatim}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	350
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	351 Note the third entry (\samp{1}). This is a flag telling the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	352 interpreter the calling convention to be used for the C function. It
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	353 should normally always be \samp{1}; a value of \samp{0} means that an
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	354 obsolete variant of \code{PyArg_ParseTuple()} is used.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	355
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	356 The method table must be passed to the interpreter in the module's
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	357 initialization function (which should be the only non-\code{static}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	358 item defined in the module file):
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	359
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	360 \begin{verbatim}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	361 void
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	362 initspam()
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	363 {
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	364 (void) Py_InitModule("spam", SpamMethods);
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	365 }
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	366 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	367
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	368 When the Python program imports module \code{spam} for the first time,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	369 \code{initspam()} is called. It calls \code{Py_InitModule()}, which
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	370 creates a ``module object'' (which is inserted in the dictionary
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	371 \code{sys.modules} under the key \code{"spam"}), and inserts built-in
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	372 function objects into the newly created module based upon the table
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	373 (an array of \code{PyMethodDef} structures) that was passed as its
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	374 second argument. \code{Py_InitModule()} returns a pointer to the
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	375 module object that it creates (which is unused here). It aborts with
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	376 a fatal error if the module could not be initialized satisfactorily,
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	377 so the caller doesn't need to check for errors.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	378
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	379
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	380 \section{Compilation and Linkage}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	381
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	382 There are two more things to do before you can use your new extension:
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	383 compiling and linking it with the Python system. If you use dynamic
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	384 loading, the details depend on the style of dynamic loading your
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	385 system uses; see the chapter on Dynamic Loading for more info about
4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	386 this.
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	387
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	388 If you can't use dynamic loading, or if you want to make your module a
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	389 permanent part of the Python interpreter, you will have to change the
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	390 configuration setup and rebuild the interpreter. Luckily, this is
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	391 very simple: just place your file (\file{spammodule.c} for example) in
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	392 the \file{Modules} directory, add a line to the file
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	393 \file{Modules/Setup} describing your file:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	394
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	395 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	396 spam spammodule.o
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	397 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	398
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	399 and rebuild the interpreter by running \code{make} in the toplevel
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	400 directory. You can also run \code{make} in the \file{Modules}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	401 subdirectory, but then you must first rebuilt the \file{Makefile}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	402 there by running \code{make Makefile}. (This is necessary each time
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	403 you change the \file{Setup} file.)
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	404
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	405 If your module requires additional libraries to link with, these can
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	406 be listed on the line in the \file{Setup} file as well, for instance:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	407
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	408 \begin{verbatim}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	409 spam spammodule.o -lX11
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	410 \end{verbatim}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	411
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	412
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	413 \section{Calling Python Functions From C}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	414
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	415 So far we have concentrated on making C functions callable from
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	416 Python. The reverse is also useful: calling Python functions from C.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	417 This is especially the case for libraries that support so-called
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	418 ``callback'' functions. If a C interface makes use of callbacks, the
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	419 equivalent Python often needs to provide a callback mechanism to the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	420 Python programmer; the implementation will require calling the Python
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	421 callback functions from a C callback. Other uses are also imaginable.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	422
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	423 Fortunately, the Python interpreter is easily called recursively, and
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	424 there is a standard interface to call a Python function. (I won't
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	425 dwell on how to call the Python parser with a particular string as
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	426 input --- if you're interested, have a look at the implementation of
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	427 the \samp{-c} command line option in \file{Python/pythonmain.c}.)
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	428
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	429 Calling a Python function is easy. First, the Python program must
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	430 somehow pass you the Python function object. You should provide a
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	431 function (or some other interface) to do this. When this function is
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	432 called, save a pointer to the Python function object (be careful to
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	433 \code{Py_INCREF()} it!) in a global variable --- or whereever you see fit.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	434 For example, the following function might be part of a module
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	435 definition:
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	436
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	437 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	438 static PyObject *my_callback = NULL;
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	439
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	440 static PyObject *
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	441 my_set_callback(dummy, arg)
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	442 PyObject dummy, arg;
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	443 {
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	444 Py_XDECREF(my_callback); /* Dispose of previous callback */
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	445 Py_XINCREF(arg); /* Add a reference to new callback */
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	446 my_callback = arg; /* Remember new callback */
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	447 /* Boilerplate to return "None" */
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	448 Py_INCREF(Py_None);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	449 return Py_None;
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	450 }
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	451 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	452
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	453 The macros \code{Py_XINCREF()} and \code{Py_XDECREF()} increment/decrement
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	454 the reference count of an object and are safe in the presence of
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	455 \code{NULL} pointers. More info on them in the section on Reference
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	456 Counts below.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	457
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	458 Later, when it is time to call the function, you call the C function
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	459 \code{PyEval_CallObject()}. This function has two arguments, both
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	460 pointers to arbitrary Python objects: the Python function, and the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	461 argument list. The argument list must always be a tuple object, whose
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	462 length is the number of arguments. To call the Python function with
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	463 no arguments, pass an empty tuple; to call it with one argument, pass
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	464 a singleton tuple. \code{Py_BuildValue()} returns a tuple when its
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	465 format string consists of zero or more format codes between
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	466 parentheses. For example:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	467
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	468 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	469 int arg;
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	470 PyObject *arglist;
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	471 PyObject *result;
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	472 ...
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	473 arg = 123;
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	474 ...
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	475 /* Time to call the callback */
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	476 arglist = Py_BuildValue("(i)", arg);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	477 result = PyEval_CallObject(my_callback, arglist);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	478 Py_DECREF(arglist);
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	479 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	480
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	481 \code{PyEval_CallObject()} returns a Python object pointer: this is
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	482 the return value of the Python function. \code{PyEval_CallObject()} is
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	483 ``reference-count-neutral'' with respect to its arguments. In the
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	484 example a new tuple was created to serve as the argument list, which
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	485 is \code{Py_DECREF()}-ed immediately after the call.
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	486
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	487 The return value of \code{PyEval_CallObject()} is ``new'': either it
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	488 is a brand new object, or it is an existing object whose reference
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	489 count has been incremented. So, unless you want to save it in a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	490 global variable, you should somehow \code{Py_DECREF()} the result,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	491 even (especially!) if you are not interested in its value.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	492
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	493 Before you do this, however, it is important to check that the return
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	494 value isn't \code{NULL}. If it is, the Python function terminated by raising
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	495 an exception. If the C code that called \code{PyEval_CallObject()} is
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	496 called from Python, it should now return an error indication to its
af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	497 Python caller, so the interpreter can print a stack trace, or the
af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	498 calling Python code can handle the exception. If this is not possible
af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	499 or desirable, the exception should be cleared by calling
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	500 \code{PyErr_Clear()}. For example:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	501
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	502 \begin{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	503 if (result == NULL)
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	504 return NULL; /* Pass error back */
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	505 ...use result...
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	506 Py_DECREF(result);
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	507 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	508
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	509 Depending on the desired interface to the Python callback function,
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	510 you may also have to provide an argument list to \code{PyEval_CallObject()}.
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	511 In some cases the argument list is also provided by the Python
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	512 program, through the same interface that specified the callback
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	513 function. It can then be saved and used in the same manner as the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	514 function object. In other cases, you may have to construct a new
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	515 tuple to pass as the argument list. The simplest way to do this is to
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	516 call \code{Py_BuildValue()}. For example, if you want to pass an integral
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	517 event code, you might use the following code:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	518
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	519 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	520 PyObject *arglist;
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	521 ...
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	522 arglist = Py_BuildValue("(l)", eventcode);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	523 result = PyEval_CallObject(my_callback, arglist);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	524 Py_DECREF(arglist);
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	525 if (result == NULL)
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	526 return NULL; /* Pass error back */
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	527 /* Here maybe use the result */
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	528 Py_DECREF(result);
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	529 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	530
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	531 Note the placement of \code{Py_DECREF(argument)} immediately after the call,
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	532 before the error check! Also note that strictly spoken this code is
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	533 not complete: \code{Py_BuildValue()} may run out of memory, and this should
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	534 be checked.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	535
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	536
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	537 \section{Format Strings for {\tt PyArg_ParseTuple()}}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	538
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	539 The \code{PyArg_ParseTuple()} function is declared as follows:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	540
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	541 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	542 int PyArg_ParseTuple(PyObject arg, char format, ...);
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	543 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	544
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	545 The \var{arg} argument must be a tuple object containing an argument
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	546 list passed from Python to a C function. The \var{format} argument
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	547 must be a format string, whose syntax is explained below. The
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	548 remaining arguments must be addresses of variables whose type is
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	549 determined by the format string. For the conversion to succeed, the
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	550 \var{arg} object must match the format and the format must be
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	551 exhausted.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	552
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	553 Note that while \code{PyArg_ParseTuple()} checks that the Python
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	554 arguments have the required types, it cannot check the validity of the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	555 addresses of C variables passed to the call: if you make mistakes
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	556 there, your code will probably crash or at least overwrite random bits
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	557 in memory. So be careful!
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	558
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	559 A format string consists of zero or more ``format units''. A format
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	560 unit describes one Python object; it is usually a single character or
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	561 a parenthesized sequence of format units. With a few exceptions, a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	562 format unit that is not a parenthesized sequence normally corresponds
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	563 to a single address argument to \code{PyArg_ParseTuple()}. In the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	564 following description, the quoted form is the format unit; the entry
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	565 in (round) parentheses is the Python object type that matches the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	566 format unit; and the entry in [square] brackets is the type of the C
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	567 variable(s) whose address should be passed. (Use the \samp{\&}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	568 operator to pass a variable's address.)
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	569
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	570 \begin{description}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	571
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	572 \item[\samp{s} (string) [char *]]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	573 Convert a Python string to a C pointer to a character string. You
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	574 must not provide storage for the string itself; a pointer to an
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	575 existing string is stored into the character pointer variable whose
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	576 address you pass. The C string is null-terminated. The Python string
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	577 must not contain embedded null bytes; if it does, a \code{TypeError}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	578 exception is raised.
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	579
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	580 \item[\samp{s\#} (string) {[char *, int]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	581 This variant on \code{'s'} stores into two C variables, the first one
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	582 a pointer to a character string, the second one its length. In this
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	583 case the Python string may contain embedded null bytes.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	584
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	585 \item[\samp{z} (string or \code{None}) {[char *]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	586 Like \samp{s}, but the Python object may also be \code{None}, in which
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	587 case the C pointer is set to \code{NULL}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	588
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	589 \item[\samp{z\#} (string or \code{None}) {[char *, int]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	590 This is to \code{'s\#'} as \code{'z'} is to \code{'s'}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	591
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	592 \item[\samp{b} (integer) {[char]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	593 Convert a Python integer to a tiny int, stored in a C \code{char}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	594
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	595 \item[\samp{h} (integer) {[short int]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	596 Convert a Python integer to a C \code{short int}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	597
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	598 \item[\samp{i} (integer) {[int]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	599 Convert a Python integer to a plain C \code{int}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	600
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	601 \item[\samp{l} (integer) {[long int]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	602 Convert a Python integer to a C \code{long int}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	603
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	604 \item[\samp{c} (string of length 1) {[char]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	605 Convert a Python character, represented as a string of length 1, to a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	606 C \code{char}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	607
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	608 \item[\samp{f} (float) {[float]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	609 Convert a Python floating point number to a C \code{float}.
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	610
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	611 \item[\samp{d} (float) {[double]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	612 Convert a Python floating point number to a C \code{double}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	613
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	614 \item[\samp{O} (object) {[PyObject *]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	615 Store a Python object (without any conversion) in a C object pointer.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	616 The C program thus receives the actual object that was passed. The
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	617 object's reference count is not increased. The pointer stored is not
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	618 \code{NULL}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	619
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	620 \item[\samp{O!} (object) {[\var{typeobject}, PyObject *]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	621 Store a Python object in a C object pointer. This is similar to
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	622 \samp{O}, but takes two C arguments: the first is the address of a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	623 Python type object, the second is the address of the C variable (of
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	624 type \code{PyObject *}) into which the object pointer is stored.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	625 If the Python object does not have the required type, a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	626 \code{TypeError} exception is raised.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	627
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	628 \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	629 Convert a Python object to a C variable through a \var{converter}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	630 function. This takes two arguments: the first is a function, the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	631 second is the address of a C variable (of arbitrary type), converted
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	632 to \code{void *}. The \var{converter} function in turn is called as
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	633 follows:
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	634
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	635 \code{\var{status} = \var{converter}(\var{object}, \var{address});}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	636
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	637 where \var{object} is the Python object to be converted and
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	638 \var{address} is the \code{void *} argument that was passed to
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	639 \code{PyArg_ConvertTuple()}. The returned \var{status} should be
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	640 \code{1} for a successful conversion and \code{0} if the conversion
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	641 has failed. When the conversion fails, the \var{converter} function
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	642 should raise an exception.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	643
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	644 \item[\samp{S} (string) {[PyStringObject *]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	645 Like \samp{O} but raises a \code{TypeError} exception that the object
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	646 is a string object. The C variable may also be declared as
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	647 \code{PyObject *}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	648
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	649 \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	650 The object must be a Python tuple whose length is the number of format
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	651 units in \var{items}. The C arguments must correspond to the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	652 individual format units in \var{items}. Format units for tuples may
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	653 be nested.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	654
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	655 \end{description}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	656
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	657 It is possible to pass Python long integers where integers are
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	658 requested; however no proper range checking is done -- the most
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	659 significant bits are silently truncated when the receiving field is
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	660 too small to receive the value (actually, the semantics are inherited
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	661 from downcasts in C --- your milage may vary).
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	662
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	663 A few other characters have a meaning in a format string. These may
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	664 not occur inside nested parentheses. They are:
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	665
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	666 \begin{description}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	667
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	668 \item[\samp{\|}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	669 Indicates that the remaining arguments in the Python argument list are
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	670 optional. The C variables corresponding to optional arguments should
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	671 be initialized to their default value --- when an optional argument is
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	672 not specified, the \code{PyArg_ParseTuple} does not touch the contents
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	673 of the corresponding C variable(s).
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	674
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	675 \item[\samp{:}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	676 The list of format units ends here; the string after the colon is used
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	677 as the function name in error messages (the ``associated value'' of
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	678 the exceptions that \code{PyArg_ParseTuple} raises).
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	679
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	680 \item[\samp{;}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	681 The list of format units ends here; the string after the colon is used
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	682 as the error message \emph{instead} of the default error message.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	683 Clearly, \samp{:} and \samp{;} mutually exclude each other.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	684
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	685 \end{description}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	686
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	687 Some example calls:
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	688
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	689 \begin{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	690 int ok;
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	691 int i, j;
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	692 long k, l;
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	693 char *s;
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	694 int size;
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	695
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	696 ok = PyArg_ParseTuple(args, ""); /* No arguments */
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	697 /* Python call: f() */
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	698
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	699 ok = PyArg_ParseTuple(args, "s", &s); /* A string */
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	700 /* Possible Python call: f('whoops!') */
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	701
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	702 ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	703 /* Possible Python call: f(1, 2, 'three') */
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	704
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	705 ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	706 /* A pair of ints and a string, whose size is also returned */
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	707 /* Possible Python call: f(1, 2, 'three') */
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	708
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	709 {
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	710 char *file;
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	711 char *mode = "r";
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	712 int bufsize = 0;
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	713 ok = PyArg_ParseTuple(args, "s\|si", &file, &mode, &bufsize);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	714 /* A string, and optionally another string and an integer */
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	715 /* Possible Python calls:
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	716 f('spam')
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	717 f('spam', 'w')
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	718 f('spam', 'wb', 100000) */
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	719 }
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	720
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	721 {
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	722 int left, top, right, bottom, h, v;
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	723 ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	724 &left, &top, &right, &bottom, &h, &v);
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	725 /* A rectangle and a point */
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	726 /* Possible Python call:
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	727 f(((0, 0), (400, 300)), (10, 10)) */
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	728 }
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	729 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	730
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	731
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	732 \section{The {\tt Py_BuildValue()} Function}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	733
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	734 This function is the counterpart to \code{PyArg_ParseTuple()}. It is
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	735 declared as follows:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	736
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	737 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	738 PyObject Py_BuildValue(char format, ...);
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	739 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	740
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	741 It recognizes a set of format units similar to the ones recognized by
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	742 \code{PyArg_ParseTuple()}, but the arguments (which are input to the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	743 function, not output) must not be pointers, just values. It returns a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	744 new Python object, suitable for returning from a C function called
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	745 from Python.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	746
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	747 One difference with \code{PyArg_ParseTuple()}: while the latter
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	748 requires its first argument to be a tuple (since Python argument lists
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	749 are always represented as tuples internally), \code{BuildValue()} does
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	750 not always build a tuple. It builds a tuple only if its format string
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	751 contains two or more format units. If the format string is empty, it
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	752 returns \code{None}; if it contains exactly one format unit, it
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	753 returns whatever object is described by that format unit. To force it
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	754 to return a tuple of size 0 or one, parenthesize the format string.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	755
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	756 In the following description, the quoted form is the format unit; the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	757 entry in (round) parentheses is the Python object type that the format
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	758 unit will return; and the entry in [square] brackets is the type of
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	759 the C value(s) to be passed.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	760
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	761 The characters space, tab, colon and comma are ignored in format
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	762 strings (but not within format units such as \samp{s\#}). This can be
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	763 used to make long format strings a tad more readable.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	764
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	765 \begin{description}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	766
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	767 \item[\samp{s} (string) {[char *]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	768 Convert a null-terminated C string to a Python object. If the C
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	769 string pointer is \code{NULL}, \code{None} is returned.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	770
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	771 \item[\samp{s\#} (string) {[char *, int]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	772 Convert a C string and its length to a Python object. If the C string
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	773 pointer is \code{NULL}, the length is ignored and \code{None} is
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	774 returned.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	775
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	776 \item[\samp{z} (string or \code{None}) {[char *]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	777 Same as \samp{s}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	778
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	779 \item[\samp{z\#} (string or \code{None}) {[char *, int]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	780 Same as \samp{s\#}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	781
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	782 \item[\samp{i} (integer) {[int]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	783 Convert a plain C \code{int} to a Python integer object.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	784
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	785 \item[\samp{b} (integer) {[char]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	786 Same as \samp{i}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	787
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	788 \item[\samp{h} (integer) {[short int]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	789 Same as \samp{i}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	790
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	791 \item[\samp{l} (integer) {[long int]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	792 Convert a C \code{long int} to a Python integer object.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	793
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	794 \item[\samp{c} (string of length 1) {[char]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	795 Convert a C \code{int} representing a character to a Python string of
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	796 length 1.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	797
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	798 \item[\samp{d} (float) {[double]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	799 Convert a C \code{double} to a Python floating point number.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	800
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	801 \item[\samp{f} (float) {[float]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	802 Same as \samp{d}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	803
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	804 \item[\samp{O} (object) {[PyObject *]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	805 Pass a Python object untouched (except for its reference count, which
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	806 is incremented by one). If the object passed in is a \code{NULL}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	807 pointer, it is assumed that this was caused because the call producing
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	808 the argument found an error and set an exception. Therefore,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	809 \code{Py_BuildValue()} will return \code{NULL} but won't raise an
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	810 exception. If no exception has been raised yet,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	811 \code{PyExc_SystemError} is set.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	812
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	813 \item[\samp{S} (object) {[PyObject *]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	814 Same as \samp{O}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	815
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	816 \item[\samp{O\&} (object) {[\var{converter}, \var{anything}]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	817 Convert \var{anything} to a Python object through a \var{converter}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	818 function. The function is called with \var{anything} (which should be
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	819 compatible with \code{void *}) as its argument and should return a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	820 ``new'' Python object, or \code{NULL} if an error occurred.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	821
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	822 \item[\samp{(\var{items})} (tuple) {[\var{matching-items}]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	823 Convert a sequence of C values to a Python tuple with the same number
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	824 of items.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	825
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	826 \item[\samp{[\var{items}]} (list) {[\var{matching-items}]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	827 Convert a sequence of C values to a Python list with the same number
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	828 of items.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	829
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	830 \item[\samp{\{\var{items}\}} (dictionary) {[\var{matching-items}]}]
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	831 Convert a sequence of C values to a Python dictionary. Each pair of
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	832 consecutive C values adds one item to the dictionary, serving as key
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	833 and value, respectively.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	834
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	835 \end{description}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	836
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	837 If there is an error in the format string, the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	838 \code{PyExc_SystemError} exception is raised and \code{NULL} returned.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	839
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	840 Examples (to the left the call, to the right the resulting Python value):
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	841
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	842 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	843 Py_BuildValue("") None
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	844 Py_BuildValue("i", 123) 123
2578 0ac27ffd0579 micro change Guido van Rossum <guido@python.org> parents: 2528 diff changeset	845 Py_BuildValue("iii", 123, 456, 789) (123, 456, 789)
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	846 Py_BuildValue("s", "hello") 'hello'
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	847 Py_BuildValue("ss", "hello", "world") ('hello', 'world')
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	848 Py_BuildValue("s#", "hello", 4) 'hell'
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	849 Py_BuildValue("()") ()
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	850 Py_BuildValue("(i)", 123) (123,)
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	851 Py_BuildValue("(ii)", 123, 456) (123, 456)
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	852 Py_BuildValue("(i,i)", 123, 456) (123, 456)
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	853 Py_BuildValue("[i,i]", 123, 456) [123, 456]
2578 0ac27ffd0579 micro change Guido van Rossum <guido@python.org> parents: 2528 diff changeset	854 Py_BuildValue("{s:i,s:i}",
0ac27ffd0579 micro change Guido van Rossum <guido@python.org> parents: 2528 diff changeset	855 "abc", 123, "def", 456) {'abc': 123, 'def': 456}
0ac27ffd0579 micro change Guido van Rossum <guido@python.org> parents: 2528 diff changeset	856 Py_BuildValue("((ii)(ii)) (ii)",
0ac27ffd0579 micro change Guido van Rossum <guido@python.org> parents: 2528 diff changeset	857 1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	858 \end{verbatim}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	859
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	860
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	861 \section{Reference Counts}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	862
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	863 \subsection{Introduction}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	864
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	865 In languages like C or \Cpp{}, the programmer is responsible for
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	866 dynamic allocation and deallocation of memory on the heap. In C, this
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	867 is done using the functions \code{malloc()} and \code{free()}. In
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	868 \Cpp{}, the operators \code{new} and \code{delete} are used with
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	869 essentially the same meaning; they are actually implemented using
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	870 \code{malloc()} and \code{free()}, so we'll restrict the following
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	871 discussion to the latter.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	872
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	873 Every block of memory allocated with \code{malloc()} should eventually
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	874 be returned to the pool of available memory by exactly one call to
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	875 \code{free()}. It is important to call \code{free()} at the right
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	876 time. If a block's address is forgotten but \code{free()} is not
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	877 called for it, the memory it occupies cannot be reused until the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	878 program terminates. This is called a \dfn{memory leak}. On the other
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	879 hand, if a program calls \code{free()} for a block and then continues
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	880 to use the block, it creates a conflict with re-use of the block
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	881 through another \code{malloc()} call. This is called \dfn{using freed
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	882 memory} has the same bad consequences as referencing uninitialized
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	883 data --- core dumps, wrong results, mysterious crashes.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	884
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	885 Common causes of memory leaks are unusual paths through the code. For
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	886 instance, a function may allocate a block of memory, do some
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	887 calculation, and then free the block again. Now a change in the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	888 requirements for the function may add a test to the calculation that
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	889 detects an error condition and can return prematurely from the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	890 function. It's easy to forget to free the allocated memory block when
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	891 taking this premature exit, especially when it is added later to the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	892 code. Such leaks, once introduced, often go undetected for a long
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	893 time: the error exit is taken only in a small fraction of all calls,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	894 and most modern machines have plenty of virtual memory, so the leak
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	895 only becomes apparent in a long-running process that uses the leaking
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	896 function frequently. Therefore, it's important to prevent leaks from
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	897 happening by having a coding convention or strategy that minimizes
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	898 this kind of errors.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	899
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	900 Since Python makes heavy use of \code{malloc()} and \code{free()}, it
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	901 needs a strategy to avoid memory leaks as well as the use of freed
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	902 memory. The chosen method is called \dfn{reference counting}. The
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	903 principle is simple: every object contains a counter, which is
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	904 incremented when a reference to the object is stored somewhere, and
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	905 which is decremented when a reference to it is deleted. When the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	906 counter reaches zero, the last reference to the object has been
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	907 deleted and the object is freed.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	908
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	909 An alternative strategy is called \dfn{automatic garbage collection}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	910 (Sometimes, reference counting is also referred to as a garbage
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	911 collection strategy, hence my use of ``automatic'' to distinguish the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	912 two.) The big advantage of automatic garbage collection is that the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	913 user doesn't need to call \code{free()} explicitly. (Another claimed
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	914 advantage is an improvement in speed or memory usage --- this is no
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	915 hard fact however.) The disadvantage is that for C, there is no
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	916 truly portable automatic garbage collector, while reference counting
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	917 can be implemented portably (as long as the functions \code{malloc()}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	918 and \code{free()} are available --- which the C Standard guarantees).
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	919 Maybe some day a sufficiently portable automatic garbage collector
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	920 will be available for C. Until then, we'll have to live with
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	921 reference counts.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	922
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	923 \subsection{Reference Counting in Python}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	924
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	925 There are two macros, \code{Py_INCREF(x)} and \code{Py_DECREF(x)},
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	926 which handle the incrementing and decrementing of the reference count.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	927 \code{Py_DECREF()} also frees the object when the count reaches zero.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	928 For flexibility, it doesn't call \code{free()} directly --- rather, it
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	929 makes a call through a function pointer in the object's \dfn{type
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	930 object}. For this purpose (and others), every object also contains a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	931 pointer to its type object.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	932
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	933 The big question now remains: when to use \code{Py_INCREF(x)} and
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	934 \code{Py_DECREF(x)}? Let's first introduce some terms. Nobody
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	935 ``owns'' an object; however, you can \dfn{own a reference} to an
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	936 object. An object's reference count is now defined as the number of
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	937 owned references to it. The owner of a reference is responsible for
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	938 calling \code{Py_DECREF()} when the reference is no longer needed.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	939 Ownership of a reference can be transferred. There are three ways to
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	940 dispose of an owned reference: pass it on, store it, or call
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	941 \code{Py_DECREF()}. Forgetting to dispose of an owned reference creates
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	942 a memory leak.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	943
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	944 It is also possible to \dfn{borrow}\footnote{The metaphor of
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	945 ``borrowing'' a reference is not completely correct: the owner still
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	946 has a copy of the reference.} a reference to an object. The borrower
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	947 of a reference should not call \code{Py_DECREF()}. The borrower must
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	948 not hold on to the object longer than the owner from which it was
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	949 borrowed. Using a borrowed reference after the owner has disposed of
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	950 it risks using freed memory and should be avoided
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	951 completely.\footnote{Checking that the reference count is at least 1
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	952 \strong{does not work} --- the reference count itself could be in
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	953 freed memory and may thus be reused for another object!}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	954
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	955 The advantage of borrowing over owning a reference is that you don't
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	956 need to take care of disposing of the reference on all possible paths
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	957 through the code --- in other words, with a borrowed reference you
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	958 don't run the risk of leaking when a premature exit is taken. The
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	959 disadvantage of borrowing over leaking is that there are some subtle
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	960 situations where in seemingly correct code a borrowed reference can be
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	961 used after the owner from which it was borrowed has in fact disposed
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	962 of it.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	963
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	964 A borrowed reference can be changed into an owned reference by calling
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	965 \code{Py_INCREF()}. This does not affect the status of the owner from
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	966 which the reference was borrowed --- it creates a new owned reference,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	967 and gives full owner responsibilities (i.e., the new owner must
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	968 dispose of the reference properly, as well as the previous owner).
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	969
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	970 \subsection{Ownership Rules}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	971
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	972 Whenever an object reference is passed into or out of a function, it
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	973 is part of the function's interface specification whether ownership is
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	974 transferred with the reference or not.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	975
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	976 Most functions that return a reference to an object pass on ownership
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	977 with the reference. In particular, all functions whose function it is
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	978 to create a new object, e.g.\ \code{PyInt_FromLong()} and
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	979 \code{Py_BuildValue()}, pass ownership to the receiver. Even if in
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	980 fact, in some cases, you don't receive a reference to a brand new
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	981 object, you still receive ownership of the reference. For instance,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	982 \code{PyInt_FromLong()} maintains a cache of popular values and can
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	983 return a reference to a cached item.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	984
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	985 Many functions that extract objects from other objects also transfer
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	986 ownership with the reference, for instance
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	987 \code{PyObject_GetAttrString()}. The picture is less clear, here,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	988 however, since a few common routines are exceptions:
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	989 \code{PyTuple_GetItem()}, \code{PyList_GetItem()} and
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	990 \code{PyDict_GetItem()} (and \code{PyDict_GetItemString()}) all return
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	991 references that you borrow from the tuple, list or dictionary.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	992
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	993 The function \code{PyImport_AddModule()} also returns a borrowed
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	994 reference, even though it may actually create the object it returns:
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	995 this is possible because an owned reference to the object is stored in
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	996 \code{sys.modules}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	997
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	998 When you pass an object reference into another function, in general,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	999 the function borrows the reference from you --- if it needs to store
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1000 it, it will use \code{Py_INCREF()} to become an independent owner.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1001 There are exactly two important exceptions to this rule:
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1002 \code{PyTuple_SetItem()} and \code{PyList_SetItem()}. These functions
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1003 take over ownership of the item passed to them --- even if they fail!
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1004 (Note that \code{PyDict_SetItem()} and friends don't take over
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1005 ownership --- they are ``normal''.)
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1006
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1007 When a C function is called from Python, it borrows references to its
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1008 arguments from the caller. The caller owns a reference to the object,
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1009 so the borrowed reference's lifetime is guaranteed until the function
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1010 returns. Only when such a borrowed reference must be stored or passed
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1011 on, it must be turned into an owned reference by calling
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1012 \code{Py_INCREF()}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1013
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1014 The object reference returned from a C function that is called from
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1015 Python must be an owned reference --- ownership is tranferred from the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1016 function to its caller.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1017
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1018 \subsection{Thin Ice}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1019
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1020 There are a few situations where seemingly harmless use of a borrowed
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1021 reference can lead to problems. These all have to do with implicit
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1022 invocations of the interpreter, which can cause the owner of a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1023 reference to dispose of it.
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1024
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1025 The first and most important case to know about is using
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1026 \code{Py_DECREF()} on an unrelated object while borrowing a reference
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1027 to a list item. For instance:
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1028
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1029 \begin{verbatim}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1030 bug(PyObject *list) {
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1031 PyObject *item = PyList_GetItem(list, 0);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1032 PyList_SetItem(list, 1, PyInt_FromLong(0L));
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1033 PyObject_Print(item, stdout, 0); /* BUG! */
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1034 }
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1035 \end{verbatim}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1036
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1037 This function first borrows a reference to \code{list[0]}, then
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1038 replaces \code{list[1]} with the value \code{0}, and finally prints
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1039 the borrowed reference. Looks harmless, right? But it's not!
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1040
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1041 Let's follow the control flow into \code{PyList_SetItem()}. The list
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1042 owns references to all its items, so when item 1 is replaced, it has
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1043 to dispose of the original item 1. Now let's suppose the original
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1044 item 1 was an instance of a user-defined class, and let's further
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1045 suppose that the class defined a \code{__del__()} method. If this
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1046 class instance has a reference count of 1, disposing of it will call
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1047 its \code{__del__()} method.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1048
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1049 Since it is written in Python, the \code{__del__()} method can execute
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1050 arbitrary Python code. Could it perhaps do something to invalidate
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1051 the reference to \code{item} in \code{bug()}? You bet! Assuming that
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1052 the list passed into \code{bug()} is accessible to the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1053 \code{__del__()} method, it could execute a statement to the effect of
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1054 \code{del list[0]}, and assuming this was the last reference to that
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1055 object, it would free the memory associated with it, thereby
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1056 invalidating \code{item}.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1057
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1058 The solution, once you know the source of the problem, is easy:
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1059 temporarily increment the reference count. The correct version of the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1060 function reads:
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1061
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1062 \begin{verbatim}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1063 no_bug(PyObject *list) {
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1064 PyObject *item = PyList_GetItem(list, 0);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1065 Py_INCREF(item);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1066 PyList_SetItem(list, 1, PyInt_FromLong(0L));
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1067 PyObject_Print(item, stdout, 0);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1068 Py_DECREF(item);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1069 }
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1070 \end{verbatim}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1071
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1072 This is a true story. An older version of Python contained variants
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1073 of this bug and someone spent a considerable amount of time in a C
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1074 debugger to figure out why his \code{__del__()} methods would fail...
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1075
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1076 The second case of problems with a borrowed reference is a variant
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1077 involving threads. Normally, multiple threads in the Python
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1078 interpreter can't get in each other's way, because there is a global
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1079 lock protecting Python's entire object space. However, it is possible
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1080 to temporarily release this lock using the macro
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1081 \code{Py_BEGIN_ALLOW_THREADS}, and to re-acquire it using
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1082 \code{Py_END_ALLOW_THREADS}. This is common around blocking I/O
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1083 calls, to let other threads use the CPU while waiting for the I/O to
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1084 complete. Obviously, the following function has the same problem as
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1085 the previous one:
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1086
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1087 \begin{verbatim}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1088 bug(PyObject *list) {
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1089 PyObject *item = PyList_GetItem(list, 0);
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1090 Py_BEGIN_ALLOW_THREADS
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1091 ...some blocking I/O call...
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1092 Py_END_ALLOW_THREADS
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1093 PyObject_Print(item, stdout, 0); /* BUG! */
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1094 }
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1095 \end{verbatim}
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1096
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1097 \subsection{NULL Pointers}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1098
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1099 In general, functions that take object references as arguments don't
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1100 expect you to pass them \code{NULL} pointers, and will dump core (or
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1101 cause later core dumps) if you do so. Functions that return object
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1102 references generally return \code{NULL} only to indicate that an
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1103 exception occurred. The reason for not testing for \code{NULL}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1104 arguments is that functions often pass the objects they receive on to
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1105 other function --- if each function were to test for \code{NULL},
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1106 there would be a lot of redundant tests and the code would run slower.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1107
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1108 It is better to test for \code{NULL} only at the ``source'', i.e.\
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1109 when a pointer that may be \code{NULL} is received, e.g.\ from
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1110 \code{malloc()} or from a function that may raise an exception.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1111
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1112 The macros \code{Py_INCREF()} and \code{Py_DECREF()}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1113 don't check for \code{NULL} pointers --- however, their variants
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1114 \code{Py_XINCREF()} and \code{Py_XDECREF()} do.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1115
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1116 The macros for checking for a particular object type
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1117 (\code{Py\var{type}_Check()}) don't check for \code{NULL} pointers ---
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1118 again, there is much code that calls several of these in a row to test
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1119 an object against various different expected types, and this would
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1120 generate redundant tests. There are no variants with \code{NULL}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1121 checking.
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1122
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1123 The C function calling mechanism guarantees that the argument list
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1124 passed to C functions (\code{args} in the examples) is never
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1125 \code{NULL} --- in fact it guarantees that it is always a tuple.%
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1126 \footnote{These guarantees don't hold when you use the ``old'' style
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1127 calling convention --- this is still found in much existing code.}
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1128
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1129 It is a severe error to ever let a \code{NULL} pointer ``escape'' to
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1130 the Python user.
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1131
af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1132
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1133 \section{Writing Extensions in \Cpp{}}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1134
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	1135 It is possible to write extension modules in \Cpp{}. Some restrictions
3163 3172c39cdad8 change warning about C++ Guido van Rossum <guido@python.org> parents: 2645 diff changeset	1136 apply. If the main program (the Python interpreter) is compiled and
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1137 linked by the C compiler, global or static objects with constructors
3163 3172c39cdad8 change warning about C++ Guido van Rossum <guido@python.org> parents: 2645 diff changeset	1138 cannot be used. This is not a problem if the main program is linked
3172c39cdad8 change warning about C++ Guido van Rossum <guido@python.org> parents: 2645 diff changeset	1139 by the \Cpp{} compiler. All functions that will be called directly or
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1140 indirectly (i.e. via function pointers) by the Python interpreter will
af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1141 have to be declared using \code{extern "C"}; this applies to all
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	1142 ``methods'' as well as to the module's initialization function.
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1143 It is unnecessary to enclose the Python header files in
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1144 \code{extern "C" \{...\}} --- they use this form already if the symbol
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1145 \samp{__cplusplus} is defined (all recent C++ compilers define this
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1146 symbol).
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1147
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1148 \chapter{Embedding Python in another application}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1149
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1150 Embedding Python is similar to extending it, but not quite. The
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1151 difference is that when you extend Python, the main program of the
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	1152 application is still the Python interpreter, while if you embed
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1153 Python, the main program may have nothing to do with Python ---
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1154 instead, some parts of the application occasionally call the Python
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1155 interpreter to run some Python code.
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1156
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1157 So if you are embedding Python, you are providing your own main
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1158 program. One of the things this main program has to do is initialize
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1159 the Python interpreter. At the very least, you have to call the
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1160 function \code{Py_Initialize()}. There are optional calls to pass command
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1161 line arguments to Python. Then later you can call the interpreter
af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1162 from any part of the application.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1163
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1164 There are several different ways to call the interpreter: you can pass
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1165 a string containing Python statements to \code{PyRun_SimpleString()},
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1166 or you can pass a stdio file pointer and a file name (for
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1167 identification in error messages only) to \code{PyRun_SimpleFile()}. You
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1168 can also call the lower-level operations described in the previous
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1169 chapters to construct and use Python objects.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1170
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1171 A simple demo of embedding Python can be found in the directory
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1172 \file{Demo/embed}.
1402 af4e271d07b1 * ext.tex: did most of the tedious changes from plain ASCII text to LaTeX. Guido van Rossum <guido@python.org> parents: 1401 diff changeset	1173
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1174
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	1175 \section{Embedding Python in \Cpp{}}
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1176
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	1177 It is also possible to embed Python in a \Cpp{} program; precisely how this
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	1178 is done will depend on the details of the \Cpp{} system used; in general you
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	1179 will need to write the main program in \Cpp{}, and use the \Cpp{} compiler
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	1180 to compile and link your program. There is no need to recompile Python
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	1181 itself using \Cpp{}.
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1182
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1183
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1184 \chapter{Dynamic Loading}
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1185
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1186 On most modern systems it is possible to configure Python to support
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1187 dynamic loading of extension modules implemented in C. When shared
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1188 libraries are used dynamic loading is configured automatically;
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1189 otherwise you have to select it as a build option (see below). Once
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1190 configured, dynamic loading is trivial to use: when a Python program
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1191 executes \code{import spam}, the search for modules tries to find a
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1192 file \file{spammodule.o} (\file{spammodule.so} when using shared
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1193 libraries) in the module search path, and if one is found, it is
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1194 loaded into the executing binary and executed. Once loaded, the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1195 module acts just like a built-in extension module.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1196
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	1197 The advantages of dynamic loading are twofold: the ``core'' Python
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1198 binary gets smaller, and users can extend Python with their own
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1199 modules implemented in C without having to build and maintain their
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1200 own copy of the Python interpreter. There are also disadvantages:
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1201 dynamic loading isn't available on all systems (this just means that
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1202 on some systems you have to use static loading), and dynamically
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1203 loading a module that was compiled for a different version of Python
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1204 (e.g. with a different representation of objects) may dump core.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1205
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1206
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1207 \section{Configuring and Building the Interpreter for Dynamic Loading}
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1208
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1209 There are three styles of dynamic loading: one using shared libraries,
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1210 one using SGI IRIX 4 dynamic loading, and one using GNU dynamic
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1211 loading.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1212
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1213 \subsection{Shared Libraries}
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1214
1767 907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs) Guido van Rossum <guido@python.org> parents: 1751 diff changeset	1215 The following systems support dynamic loading using shared libraries:
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1216 SunOS 4; Solaris 2; SGI IRIX 5 (but not SGI IRIX 4!); and probably all
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1217 systems derived from SVR4, or at least those SVR4 derivatives that
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1218 support shared libraries (are there any that don't?).
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1219
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1220 You don't need to do anything to configure dynamic loading on these
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1221 systems --- the \file{configure} detects the presence of the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1222 \file{<dlfcn.h>} header file and automatically configures dynamic
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1223 loading.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1224
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1225 \subsection{SGI IRIX 4 Dynamic Loading}
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1226
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1227 Only SGI IRIX 4 supports dynamic loading of modules using SGI dynamic
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1228 loading. (SGI IRIX 5 might also support it but it is inferior to
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1229 using shared libraries so there is no reason to; a small test didn't
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1230 work right away so I gave up trying to support it.)
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1231
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1232 Before you build Python, you first need to fetch and build the \code{dl}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1233 package written by Jack Jansen. This is available by anonymous ftp
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1234 from host \file{ftp.cwi.nl}, directory \file{pub/dynload}, file
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1235 \file{dl-1.6.tar.Z}. (The version number may change.) Follow the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1236 instructions in the package's \file{README} file to build it.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1237
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1238 Once you have built \code{dl}, you can configure Python to use it. To
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1239 this end, you run the \file{configure} script with the option
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1240 \code{--with-dl=\var{directory}} where \var{directory} is the absolute
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1241 pathname of the \code{dl} directory.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1242
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1243 Now build and install Python as you normally would (see the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1244 \file{README} file in the toplevel Python directory.)
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1245
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1246 \subsection{GNU Dynamic Loading}
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1247
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1248 GNU dynamic loading supports (according to its \file{README} file) the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1249 following hardware and software combinations: VAX (Ultrix), Sun 3
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1250 (SunOS 3.4 and 4.0), Sparc (SunOS 4.0), Sequent Symmetry (Dynix), and
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1251 Atari ST. There is no reason to use it on a Sparc; I haven't seen a
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1252 Sun 3 for years so I don't know if these have shared libraries or not.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1253
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1254 You need to fetch and build two packages. One is GNU DLD 3.2.3,
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1255 available by anonymous ftp from host \file{ftp.cwi.nl}, directory
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1256 \file{pub/dynload}, file \file{dld-3.2.3.tar.Z}. (As far as I know,
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1257 no further development on GNU DLD is being done.) The other is an
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1258 emulation of Jack Jansen's \code{dl} package that I wrote on top of
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1259 GNU DLD 3.2.3. This is available from the same host and directory,
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1260 file dl-dld-1.1.tar.Z. (The version number may change --- but I doubt
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1261 it will.) Follow the instructions in each package's \file{README}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1262 file to configure build them.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1263
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1264 Now configure Python. Run the \file{configure} script with the option
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1265 \code{--with-dl-dld=\var{dl-directory},\var{dld-directory}} where
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1266 \var{dl-directory} is the absolute pathname of the directory where you
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1267 have built the \file{dl-dld} package, and \var{dld-directory} is that
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1268 of the GNU DLD package. The Python interpreter you build hereafter
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1269 will support GNU dynamic loading.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1270
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1271
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1272 \section{Building a Dynamically Loadable Module}
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1273
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1274 Since there are three styles of dynamic loading, there are also three
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1275 groups of instructions for building a dynamically loadable module.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1276 Instructions common for all three styles are given first. Assuming
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1277 your module is called \code{spam}, the source filename must be
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1278 \file{spammodule.c}, so the object name is \file{spammodule.o}. The
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1279 module must be written as a normal Python extension module (as
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1280 described earlier).
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1281
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1282 Note that in all cases you will have to create your own Makefile that
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1283 compiles your module file(s). This Makefile will have to pass two
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1284 \samp{-I} arguments to the C compiler which will make it find the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1285 Python header files. If the Make variable \var{PYTHONTOP} points to
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1286 the toplevel Python directory, your \var{CFLAGS} Make variable should
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1287 contain the options \samp{-I\$(PYTHONTOP) -I\$(PYTHONTOP)/Include}.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1288 (Most header files are in the \file{Include} subdirectory, but the
4049 a2dc7ce4dfbe Remove mention of HAVE_CONFIG_H Guido van Rossum <guido@python.org> parents: 3991 diff changeset	1289 \file{config.h} header lives in the toplevel directory.)
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1290
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1291
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1292 \subsection{Shared Libraries}
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1293
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1294 You must link the \samp{.o} file to produce a shared library. This is
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1295 done using a special invocation of the \UNIX{} loader/linker, {\em
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1296 ld}(1). Unfortunately the invocation differs slightly per system.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1297
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1298 On SunOS 4, use
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1299 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1300 ld spammodule.o -o spammodule.so
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1301 \end{verbatim}
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1302
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1303 On Solaris 2, use
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1304 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1305 ld -G spammodule.o -o spammodule.so
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1306 \end{verbatim}
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1307
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1308 On SGI IRIX 5, use
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1309 \begin{verbatim}
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1310 ld -shared spammodule.o -o spammodule.so
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1311 \end{verbatim}
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1312
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	1313 On other systems, consult the manual page for \code{ld}(1) to find what
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1314 flags, if any, must be used.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1315
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1316 If your extension module uses system libraries that haven't already
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1317 been linked with Python (e.g. a windowing system), these must be
2584 4b6c0762d659 yet a better introduction Guido van Rossum <guido@python.org> parents: 2578 diff changeset	1318 passed to the \code{ld} command as \samp{-l} options after the
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1319 \samp{.o} file.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1320
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1321 The resulting file \file{spammodule.so} must be copied into a directory
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1322 along the Python module search path.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1323
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1324
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1325 \subsection{SGI IRIX 4 Dynamic Loading}
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1326
2645 f876cd5c4417 typo bf should be \bf Guido van Rossum <guido@python.org> parents: 2584 diff changeset	1327 {\bf IMPORTANT:} You must compile your extension module with the
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1328 additional C flag \samp{-G0} (or \samp{-G 0}). This instruct the
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1329 assembler to generate position-independent code.
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1330
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1331 You don't need to link the resulting \file{spammodule.o} file; just
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1332 copy it into a directory along the Python module search path.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1333
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1334 The first time your extension is loaded, it takes some extra time and
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1335 a few messages may be printed. This creates a file
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1336 \file{spammodule.ld} which is an image that can be loaded quickly into
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1337 the Python interpreter process. When a new Python interpreter is
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1338 installed, the \code{dl} package detects this and rebuilds
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1339 \file{spammodule.ld}. The file \file{spammodule.ld} is placed in the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1340 directory where \file{spammodule.o} was found, unless this directory is
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1341 unwritable; in that case it is placed in a temporary
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1342 directory.\footnote{Check the manual page of the \code{dl} package for
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1343 details.}
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1344
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1345 If your extension modules uses additional system libraries, you must
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1346 create a file \file{spammodule.libs} in the same directory as the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1347 \file{spammodule.o}. This file should contain one or more lines with
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1348 whitespace-separated options that will be passed to the linker ---
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1349 normally only \samp{-l} options or absolute pathnames of libraries
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1350 (\samp{.a} files) should be used.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1351
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1352
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1353 \subsection{GNU Dynamic Loading}
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1354
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1355 Just copy \file{spammodule.o} into a directory along the Python module
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1356 search path.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1357
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1358 If your extension modules uses additional system libraries, you must
2528 ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1359 create a file \file{spammodule.libs} in the same directory as the
ae2b032445f9 another round (sigh :-( ) Guido van Rossum <guido@python.org> parents: 1934 diff changeset	1360 \file{spammodule.o}. This file should contain one or more lines with
1751 ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1361 whitespace-separated absolute pathnames of libraries (\samp{.a}
ec25aad43724 Merge alpha100 branch back to main trunk Guido van Rossum <guido@python.org> parents: 1466 diff changeset	1362 files). No \samp{-l} options can be used.
1411 1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1363
1691ea5d9d4b * text2latex.py: call main() instead of always processing ext.tex. Guido van Rossum <guido@python.org> parents: 1402 diff changeset	1364
3991 cfb8b7bc0233 Added doco for abstract interface Guido van Rossum <guido@python.org> parents: 3163 diff changeset	1365 \input{extref}
cfb8b7bc0233 Added doco for abstract interface Guido van Rossum <guido@python.org> parents: 3163 diff changeset	1366
1401 cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1367 \input{ext.ind}
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1368
cd5989a58bcf * ext.tex: documentation for extending, reference counts, and embedding Guido van Rossum <guido@python.org> parents: diff changeset	1369 \end{document}

Mercurial > cpython-lru_cache-weakref

annotate Doc/ext.tex @ 4566:6403c94de50d legacy-trunk