File: //usr/share/doc/python-docs-2.4.3/html/api/allocating-objects.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="api.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="api.html" title='Python/C API Reference Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="common-structs.html" />
<link rel="prev" href="newTypes.html" />
<link rel="parent" href="newTypes.html" />
<link rel="next" href="common-structs.html" />
<meta name='aesop' content='information' />
<title>10.1 Allocating Objects on the Heap </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="10. Object Implementation Support"
href="newTypes.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="10. Object Implementation Support"
href="newTypes.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="10.2 Common Object Structures"
href="common-structs.html"><img src='../icons/next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</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'><a rel="index" title="Index"
href="genindex.html"><img src='../icons/index.png'
border='0' height='32' alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="newTypes.html">10. Object Implementation Support</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="common-structs.html">10.2 Common Object Structures</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<H1><A NAME="SECTION0012100000000000000000"></A><A NAME="allocating-objects"></A>
<BR>
10.1 Allocating Objects on the Heap
</H1>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-904' xml:id='l2h-904' class="cfunction">_PyObject_New</tt></b>(</nobr></td><td>PyTypeObject *<var>type</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyVarObject* <b><tt id='l2h-905' xml:id='l2h-905' class="cfunction">_PyObject_NewVar</tt></b>(</nobr></td><td>PyTypeObject *<var>type</var>, int <var>size</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-906' xml:id='l2h-906' class="cfunction">_PyObject_Del</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
<dd>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-907' xml:id='l2h-907' class="cfunction">PyObject_Init</tt></b>(</nobr></td><td>PyObject *<var>op</var>,
PyTypeObject *<var>type</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">Borrowed reference.</span>
</div>
Initialize a newly-allocated object <var>op</var> with its type and
initial reference. Returns the initialized object. If <var>type</var>
indicates that the object participates in the cyclic garbage
detector, it is added to the detector's set of observed objects.
Other fields of the object are not affected.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyVarObject* <b><tt id='l2h-908' xml:id='l2h-908' class="cfunction">PyObject_InitVar</tt></b>(</nobr></td><td>PyVarObject *<var>op</var>,
PyTypeObject *<var>type</var>, int <var>size</var>)</td></tr></table></dt>
<dd>
This does everything <tt class="cfunction">PyObject_Init()</tt> does, and also
initializes the length information for a variable-size object.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr><var>TYPE</var>* <b><tt id='l2h-909' xml:id='l2h-909' class="cfunction">PyObject_New</tt></b>(</nobr></td><td>TYPE, PyTypeObject *<var>type</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
Allocate a new Python object using the C structure type <var>TYPE</var>
and the Python type object <var>type</var>. Fields not defined by the
Python object header are not initialized; the object's reference
count will be one. The size of the memory
allocation is determined from the <tt class="member">tp_basicsize</tt> field of the
type object.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr><var>TYPE</var>* <b><tt id='l2h-910' xml:id='l2h-910' class="cfunction">PyObject_NewVar</tt></b>(</nobr></td><td>TYPE, PyTypeObject *<var>type</var>,
int <var>size</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
Allocate a new Python object using the C structure type <var>TYPE</var>
and the Python type object <var>type</var>. Fields not defined by the
Python object header are not initialized. The allocated memory
allows for the <var>TYPE</var> structure plus <var>size</var> fields of the
size given by the <tt class="member">tp_itemsize</tt> field of <var>type</var>. This is
useful for implementing objects like tuples, which are able to
determine their size at construction time. Embedding the array of
fields into the same allocation decreases the number of allocations,
improving the memory management efficiency.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-911' xml:id='l2h-911' class="cfunction">PyObject_Del</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
<dd>
Releases memory allocated to an object using
<tt class="cfunction">PyObject_New()</tt> or <tt class="cfunction">PyObject_NewVar()</tt>. This
is normally called from the <tt class="member">tp_dealloc</tt> handler specified in
the object's type. The fields of the object should not be accessed
after this call as the memory is no longer a valid Python object.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr><var>TYPE</var>* <b><tt id='l2h-912' xml:id='l2h-912' class="cfunction">PyObject_NEW</tt></b>(</nobr></td><td>TYPE, PyTypeObject *<var>type</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
Macro version of <tt class="cfunction">PyObject_New()</tt>, to gain performance at
the expense of safety. This does not check <var>type</var> for a <tt class="constant">NULL</tt>
value.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr><var>TYPE</var>* <b><tt id='l2h-913' xml:id='l2h-913' class="cfunction">PyObject_NEW_VAR</tt></b>(</nobr></td><td>TYPE, PyTypeObject *<var>type</var>,
int <var>size</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">New reference.</span>
</div>
Macro version of <tt class="cfunction">PyObject_NewVar()</tt>, to gain performance
at the expense of safety. This does not check <var>type</var> for a
<tt class="constant">NULL</tt> value.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-914' xml:id='l2h-914' class="cfunction">PyObject_DEL</tt></b>(</nobr></td><td>PyObject *<var>op</var>)</td></tr></table></dt>
<dd>
Macro version of <tt class="cfunction">PyObject_Del()</tt>.
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-915' xml:id='l2h-915' class="cfunction">Py_InitModule</tt></b>(</nobr></td><td>char *<var>name</var>,
PyMethodDef *<var>methods</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">Borrowed reference.</span>
</div>
Create a new module object based on a name and table of functions,
returning the new module object.
<P>
<span class="versionnote">Changed in version 2.3:
Older versions of Python did not support <tt class="constant">NULL</tt> as
the value for the <var>methods</var> argument.</span>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-916' xml:id='l2h-916' class="cfunction">Py_InitModule3</tt></b>(</nobr></td><td>char *<var>name</var>,
PyMethodDef *<var>methods</var>,
char *<var>doc</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">Borrowed reference.</span>
</div>
Create a new module object based on a name and table of functions,
returning the new module object. If <var>doc</var> is non-<tt class="constant">NULL</tt>, it will
be used to define the docstring for the module.
<P>
<span class="versionnote">Changed in version 2.3:
Older versions of Python did not support <tt class="constant">NULL</tt> as
the value for the <var>methods</var> argument.</span>
</dd></dl>
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-917' xml:id='l2h-917' class="cfunction">Py_InitModule4</tt></b>(</nobr></td><td>char *<var>name</var>,
PyMethodDef *<var>methods</var>,
char *<var>doc</var>, PyObject *<var>self</var>,
int <var>apiver</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
<span class="label">Return value:</span>
<span class="value">Borrowed reference.</span>
</div>
Create a new module object based on a name and table of functions,
returning the new module object. If <var>doc</var> is non-<tt class="constant">NULL</tt>, it will
be used to define the docstring for the module. If <var>self</var> is
non-<tt class="constant">NULL</tt>, it will passed to the functions of the module as their
(otherwise <tt class="constant">NULL</tt>) first parameter. (This was added as an
experimental feature, and there are no known uses in the current
version of Python.) For <var>apiver</var>, the only value which should
be passed is defined by the constant <tt class="constant">PYTHON_API_VERSION</tt>.
<P>
<span class="note"><b class="label">Note:</b>
Most uses of this function should probably be using
the <tt class="cfunction">Py_InitModule3()</tt> instead; only use this if you are
sure you need it.</span>
<P>
<span class="versionnote">Changed in version 2.3:
Older versions of Python did not support <tt class="constant">NULL</tt> as
the value for the <var>methods</var> argument.</span>
</dd></dl>
<P>
DL_IMPORT
<P>
<dl><dt>PyObject <b><tt id='l2h-918' xml:id='l2h-918' class="cdata">_Py_NoneStruct</tt></b></dt>
<dd>
Object which is visible in Python as <code>None</code>. This should only
be accessed using the <code>Py_None</code> macro, which evaluates to a
pointer to this object.
</dd></dl>
<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="10. Object Implementation Support"
href="newTypes.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="10. Object Implementation Support"
href="newTypes.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="10.2 Common Object Structures"
href="common-structs.html"><img src='../icons/next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</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'><a rel="index" title="Index"
href="genindex.html"><img src='../icons/index.png'
border='0' height='32' alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="newTypes.html">10. Object Implementation Support</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="common-structs.html">10.2 Common Object Structures</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.3, documentation updated on 29 March 2006.</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>