[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / ext / methodTable.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="ext.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="ext.html" title='Extending and Embedding the Python Interpreter' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="compilation.html" />
<link rel="prev" href="backToExample.html" />
<link rel="parent" href="intro.html" />
<link rel="next" href="compilation.html" />
<meta name='aesop' content='information' />
<title>1.4 The Module's Method Table and Initialization Function
</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="1.3 Back to the"
  href="backToExample.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="1. Extending Python with"
  href="intro.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="1.5 Compilation and Linkage"
  href="compilation.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="backToExample.html">1.3 Back to the</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="compilation.html">1.5 Compilation and Linkage</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION003400000000000000000"></A><A NAME="methodTable"></A>
<BR>
1.4 The Module's Method Table and Initialization Function
         
</H1>

<P>
I promised to show how <tt class="cfunction">spam_system()</tt> is called from Python
programs.  First, we need to list its name and address in a ``method
table'':

<P>
<div class="verbatim"><pre>
static PyMethodDef SpamMethods[] = {
    ...
    {"system",  spam_system, METH_VARARGS,
     "Execute a shell command."},
    ...
    {NULL, NULL, 0, NULL}        /* Sentinel */
};
</pre></div>

<P>
Note the third entry ("<tt class="samp">METH_VARARGS</tt>").  This is a flag telling
the interpreter the calling convention to be used for the C
function.  It should normally always be "<tt class="samp">METH_VARARGS</tt>" or
"<tt class="samp">METH_VARARGS | METH_KEYWORDS</tt>"; a value of <code>0</code> means that an
obsolete variant of <tt class="cfunction">PyArg_ParseTuple()</tt> is used.

<P>
When using only "<tt class="samp">METH_VARARGS</tt>", the function should expect
the Python-level parameters to be passed in as a tuple acceptable for
parsing via <tt class="cfunction">PyArg_ParseTuple()</tt>; more information on this
function is provided below.

<P>
The <tt class="constant">METH_KEYWORDS</tt> bit may be set in the third field if
keyword arguments should be passed to the function.  In this case, the
C function should accept a third "<tt class="samp">PyObject *</tt>" parameter which
will be a dictionary of keywords.  Use
<tt class="cfunction">PyArg_ParseTupleAndKeywords()</tt> to parse the arguments to
such a function.

<P>
The method table must be passed to the interpreter in the module's
initialization function.  The initialization function must be named
<tt class="cfunction">init<var>name</var>()</tt>, where <var>name</var> is the name of the
module, and should be the only non-<tt class="keyword">static</tt> item defined in
the module file:

<P>
<div class="verbatim"><pre>
PyMODINIT_FUNC
initspam(void)
{
    (void) Py_InitModule("spam", SpamMethods);
}
</pre></div>

<P>
Note that PyMODINIT_FUNC declares the function as <code>void</code> return type, 
declares any special linkage declarations required by the platform, and for 
C++ declares the function as <code>extern "C"</code>.

<P>
When the Python program imports module <tt class="module">spam</tt> for the first
time, <tt class="cfunction">initspam()</tt> is called. (See below for comments about
embedding Python.)  It calls
<tt class="cfunction">Py_InitModule()</tt>, which creates a ``module object'' (which
is inserted in the dictionary <code>sys.modules</code> under the key
<code>"spam"</code>), and inserts built-in function objects into the newly
created module based upon the table (an array of <tt class="ctype">PyMethodDef</tt>
structures) that was passed as its second argument.
<tt class="cfunction">Py_InitModule()</tt> returns a pointer to the module object
that it creates (which is unused here).  It aborts with a fatal error
if the module could not be initialized satisfactorily, so the caller
doesn't need to check for errors.

<P>
When embedding Python, the <tt class="cfunction">initspam()</tt> function is not
called automatically unless there's an entry in the
<tt class="cdata">_PyImport_Inittab</tt> table.  The easiest way to handle this is to 
statically initialize your statically-linked modules by directly
calling <tt class="cfunction">initspam()</tt> after the call to
<tt class="cfunction">Py_Initialize()</tt>:

<P>
<div class="verbatim"><pre>
int
main(int argc, char *argv[])
{
    /* Pass argv[0] to the Python interpreter */
    Py_SetProgramName(argv[0]);

    /* Initialize the Python interpreter.  Required. */
    Py_Initialize();

    /* Add a static module */
    initspam();
</pre></div>

<P>
An example may be found in the file <span class="file">Demo/embed/demo.c</span> in the
Python source distribution.

<P>
<span class="note"><b class="label">Note:</b>
Removing entries from <code>sys.modules</code> or importing
compiled modules into multiple interpreters within a process (or
following a <tt class="cfunction">fork()</tt> without an intervening
<tt class="cfunction">exec()</tt>) can create problems for some extension modules.
Extension module authors should exercise caution when initializing
internal data structures.
Note also that the <tt class="function">reload()</tt> function can be used with
extension modules, and will call the module initialization function
(<tt class="cfunction">initspam()</tt> in the example), but will not load the module
again if it was loaded from a dynamically loadable object file
(<span class="file">.so</span> on <span class="Unix">Unix</span>, <span class="file">.dll</span> on Windows).</span>

<P>
A more substantial example module is included in the Python source
distribution as <span class="file">Modules/xxmodule.c</span>.  This file may be used as a 
template or simply read as an example.  The <b class="program">modulator.py</b>
script included in the source distribution or Windows install provides 
a simple graphical user interface for declaring the functions and
objects which a module should implement, and can generate a template
which can be filled in.  The script lives in the
<span class="file">Tools/modulator/</span> directory; see the <span class="file">README</span> file there
for more information.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="1.3 Back to the"
  href="backToExample.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="1. Extending Python with"
  href="intro.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="1.5 Compilation and Linkage"
  href="compilation.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="backToExample.html">1.3 Back to the</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="compilation.html">1.5 Compilation and Linkage</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="ext.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="ext.html" title='Extending and Embedding the Python Interpreter' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='last' href='about.html' title='About this document...' />
	10	<link rel='help' href='about.html' title='About this document...' />
	11	<link rel="next" href="compilation.html" />
	12	<link rel="prev" href="backToExample.html" />
	13	<link rel="parent" href="intro.html" />
	14	<link rel="next" href="compilation.html" />
	15	<meta name='aesop' content='information' />
	16	<title>1.4 The Module's Method Table and Initialization Function
	17	</title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="1.3 Back to the"
	25	href="backToExample.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="1. Extending Python with"
	28	href="intro.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="1.5 Compilation and Linkage"
	31	href="compilation.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><img src='../icons/blank.png'
	38	border='0' height='32' alt='' width='32' /></td>
	39	<td class='online-navigation'><img src='../icons/blank.png'
	40	border='0' height='32' alt='' width='32' /></td>
	41	</tr></table>
	42	<div class='online-navigation'>
	43	<b class="navlabel">Previous:</b>
	44	<a class="sectref" rel="prev" href="backToExample.html">1.3 Back to the</A>
	45	<b class="navlabel">Up:</b>
	46	<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
	47	<b class="navlabel">Next:</b>
	48	<a class="sectref" rel="next" href="compilation.html">1.5 Compilation and Linkage</A>
	49	</div>
	50	<hr /></div>
	51	</DIV>
	52	<!--End of Navigation Panel-->
	53
	54	<H1><A NAME="SECTION003400000000000000000"></A><A NAME="methodTable"></A>
	55	<BR>
	56	1.4 The Module's Method Table and Initialization Function
	57
	58	</H1>
	59
	60	<P>
	61	I promised to show how <tt class="cfunction">spam_system()</tt> is called from Python
	62	programs. First, we need to list its name and address in a ``method
	63	table'':
	64
65	<P>
66	<div class="verbatim"><pre>
67	static PyMethodDef SpamMethods[] = {
68	...
69	{"system", spam_system, METH_VARARGS,
70	"Execute a shell command."},
71	...
72	{NULL, NULL, 0, NULL} /* Sentinel */
73	};
74	</pre></div>
75
76	<P>
77	Note the third entry ("<tt class="samp">METH_VARARGS</tt>"). This is a flag telling
78	the interpreter the calling convention to be used for the C
79	function. It should normally always be "<tt class="samp">METH_VARARGS</tt>" or
80	"<tt class="samp">METH_VARARGS \| METH_KEYWORDS</tt>"; a value of <code>0</code> means that an
81	obsolete variant of <tt class="cfunction">PyArg_ParseTuple()</tt> is used.
82
83	<P>
84	When using only "<tt class="samp">METH_VARARGS</tt>", the function should expect
85	the Python-level parameters to be passed in as a tuple acceptable for
86	parsing via <tt class="cfunction">PyArg_ParseTuple()</tt>; more information on this
87	function is provided below.
88
89	<P>
90	The <tt class="constant">METH_KEYWORDS</tt> bit may be set in the third field if
91	keyword arguments should be passed to the function. In this case, the
92	C function should accept a third "<tt class="samp">PyObject *</tt>" parameter which
93	will be a dictionary of keywords. Use
94	<tt class="cfunction">PyArg_ParseTupleAndKeywords()</tt> to parse the arguments to
95	such a function.
96
97	<P>
98	The method table must be passed to the interpreter in the module's
99	initialization function. The initialization function must be named
100	<tt class="cfunction">init<var>name</var>()</tt>, where <var>name</var> is the name of the
101	module, and should be the only non-<tt class="keyword">static</tt> item defined in
102	the module file:
103
104	<P>
105	<div class="verbatim"><pre>
106	PyMODINIT_FUNC
107	initspam(void)
108	{
109	(void) Py_InitModule("spam", SpamMethods);
110	}
111	</pre></div>
112
113	<P>
114	Note that PyMODINIT_FUNC declares the function as <code>void</code> return type,
115	declares any special linkage declarations required by the platform, and for
116	C++ declares the function as <code>extern "C"</code>.
117
118	<P>
119	When the Python program imports module <tt class="module">spam</tt> for the first
120	time, <tt class="cfunction">initspam()</tt> is called. (See below for comments about
121	embedding Python.) It calls
122	<tt class="cfunction">Py_InitModule()</tt>, which creates a ``module object'' (which
123	is inserted in the dictionary <code>sys.modules</code> under the key
124	<code>"spam"</code>), and inserts built-in function objects into the newly
125	created module based upon the table (an array of <tt class="ctype">PyMethodDef</tt>
126	structures) that was passed as its second argument.
127	<tt class="cfunction">Py_InitModule()</tt> returns a pointer to the module object
128	that it creates (which is unused here). It aborts with a fatal error
129	if the module could not be initialized satisfactorily, so the caller
130	doesn't need to check for errors.
131
132	<P>
133	When embedding Python, the <tt class="cfunction">initspam()</tt> function is not
134	called automatically unless there's an entry in the
135	<tt class="cdata">_PyImport_Inittab</tt> table. The easiest way to handle this is to
136	statically initialize your statically-linked modules by directly
137	calling <tt class="cfunction">initspam()</tt> after the call to
138	<tt class="cfunction">Py_Initialize()</tt>:
139
140	<P>
141	<div class="verbatim"><pre>
142	int
143	main(int argc, char *argv[])
144	{
145	/* Pass argv[0] to the Python interpreter */
146	Py_SetProgramName(argv[0]);
147
148	/* Initialize the Python interpreter. Required. */
149	Py_Initialize();
150
151	/* Add a static module */
152	initspam();
153	</pre></div>
154
155	<P>
156	An example may be found in the file <span class="file">Demo/embed/demo.c</span> in the
157	Python source distribution.
158
159	<P>
160	<span class="note"><b class="label">Note:</b>
161	Removing entries from <code>sys.modules</code> or importing
162	compiled modules into multiple interpreters within a process (or
163	following a <tt class="cfunction">fork()</tt> without an intervening
164	<tt class="cfunction">exec()</tt>) can create problems for some extension modules.
165	Extension module authors should exercise caution when initializing
166	internal data structures.
167	Note also that the <tt class="function">reload()</tt> function can be used with
168	extension modules, and will call the module initialization function
169	(<tt class="cfunction">initspam()</tt> in the example), but will not load the module
170	again if it was loaded from a dynamically loadable object file
171	(<span class="file">.so</span> on <span class="Unix">Unix</span>, <span class="file">.dll</span> on Windows).</span>
172
173	<P>
174	A more substantial example module is included in the Python source
175	distribution as <span class="file">Modules/xxmodule.c</span>. This file may be used as a
176	template or simply read as an example. The <b class="program">modulator.py</b>
177	script included in the source distribution or Windows install provides
178	a simple graphical user interface for declaring the functions and
179	objects which a module should implement, and can generate a template
180	which can be filled in. The script lives in the
181	<span class="file">Tools/modulator/</span> directory; see the <span class="file">README</span> file there
182	for more information.
183
184	<P>
185
186	<DIV CLASS="navigation">
187	<div class='online-navigation'>
188	<p></p><hr />
189	<table align="center" width="100%" cellpadding="0" cellspacing="2">
190	<tr>
191	<td class='online-navigation'><a rel="prev" title="1.3 Back to the"
192	href="backToExample.html"><img src='../icons/previous.png'
193	border='0' height='32' alt='Previous Page' width='32' /></A></td>
194	<td class='online-navigation'><a rel="parent" title="1. Extending Python with"
195	href="intro.html"><img src='../icons/up.png'
196	border='0' height='32' alt='Up One Level' width='32' /></A></td>
197	<td class='online-navigation'><a rel="next" title="1.5 Compilation and Linkage"
198	href="compilation.html"><img src='../icons/next.png'
199	border='0' height='32' alt='Next Page' width='32' /></A></td>
200	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
201	<td class='online-navigation'><a rel="contents" title="Table of Contents"
202	href="contents.html"><img src='../icons/contents.png'
203	border='0' height='32' alt='Contents' width='32' /></A></td>
204	<td class='online-navigation'><img src='../icons/blank.png'
205	border='0' height='32' alt='' width='32' /></td>
206	<td class='online-navigation'><img src='../icons/blank.png'
207	border='0' height='32' alt='' width='32' /></td>
208	</tr></table>
209	<div class='online-navigation'>
210	<b class="navlabel">Previous:</b>
211	<a class="sectref" rel="prev" href="backToExample.html">1.3 Back to the</A>
212	<b class="navlabel">Up:</b>
213	<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
214	<b class="navlabel">Next:</b>
215	<a class="sectref" rel="next" href="compilation.html">1.5 Compilation and Linkage</A>
216	</div>
217	</div>
218	<hr />
219	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
220	</DIV>
221	<!--End of Navigation Panel-->
222	<ADDRESS>
223	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
224	</ADDRESS>
225	</BODY>
226	</HTML>