[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / ext / node24.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="prev" href="node23.html" />
<link rel="parent" href="dnt-basics.html" />
<link rel="next" href="dnt-type-methods.html" />
<meta name='aesop' content='information' />
<title>2.1.3 Supporting cyclic garbage collection</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="2.1.2 Providing finer control"
  href="node23.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="2.1 The Basics"
  href="dnt-basics.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="2.2 Type Methods"
  href="dnt-type-methods.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="node23.html">2.1.2 Providing finer control</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="dnt-basics.html">2.1 The Basics</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="dnt-type-methods.html">2.2 Type Methods</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION004130000000000000000">
2.1.3 Supporting cyclic garbage collection</A>
</H2>

<P>
Python has a cyclic-garbage collector that can identify unneeded
objects even when their reference counts are not zero. This can happen
when objects are involved in cycles.  For example, consider:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; l = []
&gt;&gt;&gt; l.append(l)
&gt;&gt;&gt; del l
</pre></div>

<P>
In this example, we create a list that contains itself. When we delete
it, it still has a reference from itself. Its reference count doesn't
drop to zero.  Fortunately, Python's cyclic-garbage collector will
eventually figure out that the list is garbage and free it.

<P>
In the second version of the <tt class="class">Noddy</tt> example, we allowed any
kind of object to be stored in the <tt class="member">first</tt> or <tt class="member">last</tt>
attributes<A NAME="tex2html8"
  HREF="#foot1173"><SUP>2.4</SUP></A>. This
means that <tt class="class">Noddy</tt> objects can participate in cycles:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; import noddy2
&gt;&gt;&gt; n = noddy2.Noddy()
&gt;&gt;&gt; l = [n]
&gt;&gt;&gt; n.first = l
</pre></div>

<P>
This is pretty silly, but it gives us an excuse to add support for the
cyclic-garbage collector to the <tt class="class">Noddy</tt> example.  To support
cyclic garbage collection, types need to fill two slots and set a
class flag that enables these slots:

<P>
<div class="verbatim">
<pre>#include &lt;Python.h&gt;
#include "structmember.h"

typedef struct {
    PyObject_HEAD
    PyObject *first;
    PyObject *last;
    int number;
} Noddy;

static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
    int vret;

    if (self-&gt;first) {
        vret = visit(self-&gt;first, arg);
        if (vret != 0)
            return vret;
    }
    if (self-&gt;last) {
        vret = visit(self-&gt;last, arg);
        if (vret != 0)
            return vret;
    }

    return 0;
}

static int 
Noddy_clear(Noddy *self)
{
    PyObject *tmp;

    tmp = self-&gt;first;
    self-&gt;first = NULL;
    Py_XDECREF(tmp);

    tmp = self-&gt;last;
    self-&gt;last = NULL;
    Py_XDECREF(tmp);

    return 0;
}

static void
Noddy_dealloc(Noddy* self)
{
    Noddy_clear(self);
    self-&gt;ob_type-&gt;tp_free((PyObject*)self);
}

static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
    Noddy *self;

    self = (Noddy *)type-&gt;tp_alloc(type, 0);
    if (self != NULL) {
        self-&gt;first = PyString_FromString("");
        if (self-&gt;first == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }
        
        self-&gt;last = PyString_FromString("");
        if (self-&gt;last == NULL)
          {
            Py_DECREF(self);
            return NULL;
          }

        self-&gt;number = 0;
    }

    return (PyObject *)self;
}

static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
    PyObject *first=NULL, *last=NULL, *tmp;

    static char *kwlist[] = {"first", "last", "number", NULL};

    if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist, 
                                      &amp;first, &amp;last, 
                                      &amp;self-&gt;number))
        return -1; 

    if (first) {
        tmp = self-&gt;first;
        Py_INCREF(first);
        self-&gt;first = first;
        Py_XDECREF(tmp);
    }

    if (last) {
        tmp = self-&gt;last;
        Py_INCREF(last);
        self-&gt;last = last;
        Py_XDECREF(tmp);
    }

    return 0;
}

static PyMemberDef Noddy_members[] = {
    {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
     "first name"},
    {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
     "last name"},
    {"number", T_INT, offsetof(Noddy, number), 0,
     "noddy number"},
    {NULL}  /* Sentinel */
};

static PyObject *
Noddy_name(Noddy* self)
{
    static PyObject *format = NULL;
    PyObject *args, *result;

    if (format == NULL) {
        format = PyString_FromString("%s %s");
        if (format == NULL)
            return NULL;
    }

    if (self-&gt;first == NULL) {
        PyErr_SetString(PyExc_AttributeError, "first");
        return NULL;
    }

    if (self-&gt;last == NULL) {
        PyErr_SetString(PyExc_AttributeError, "last");
        return NULL;
    }

    args = Py_BuildValue("OO", self-&gt;first, self-&gt;last);
    if (args == NULL)
        return NULL;

    result = PyString_Format(format, args);
    Py_DECREF(args);
    
    return result;
}

static PyMethodDef Noddy_methods[] = {
    {"name", (PyCFunction)Noddy_name, METH_NOARGS,
     "Return the name, combining the first and last name"
    },
    {NULL}  /* Sentinel */
};

static PyTypeObject NoddyType = {
    PyObject_HEAD_INIT(NULL)
    0,                         /*ob_size*/
    "noddy.Noddy",             /*tp_name*/
    sizeof(Noddy),             /*tp_basicsize*/
    0,                         /*tp_itemsize*/
    (destructor)Noddy_dealloc, /*tp_dealloc*/
    0,                         /*tp_print*/
    0,                         /*tp_getattr*/
    0,                         /*tp_setattr*/
    0,                         /*tp_compare*/
    0,                         /*tp_repr*/
    0,                         /*tp_as_number*/
    0,                         /*tp_as_sequence*/
    0,                         /*tp_as_mapping*/
    0,                         /*tp_hash */
    0,                         /*tp_call*/
    0,                         /*tp_str*/
    0,                         /*tp_getattro*/
    0,                         /*tp_setattro*/
    0,                         /*tp_as_buffer*/
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/
    "Noddy objects",           /* tp_doc */
    (traverseproc)Noddy_traverse,   /* tp_traverse */
    (inquiry)Noddy_clear,           /* tp_clear */
    0,		               /* tp_richcompare */
    0,		               /* tp_weaklistoffset */
    0,		               /* tp_iter */
    0,		               /* tp_iternext */
    Noddy_methods,             /* tp_methods */
    Noddy_members,             /* tp_members */
    0,                         /* tp_getset */
    0,                         /* tp_base */
    0,                         /* tp_dict */
    0,                         /* tp_descr_get */
    0,                         /* tp_descr_set */
    0,                         /* tp_dictoffset */
    (initproc)Noddy_init,      /* tp_init */
    0,                         /* tp_alloc */
    Noddy_new,                 /* tp_new */
};

static PyMethodDef module_methods[] = {
    {NULL}  /* Sentinel */
};

#ifndef PyMODINIT_FUNC	/* declarations for DLL import/export */
#define PyMODINIT_FUNC void
#endif
PyMODINIT_FUNC
initnoddy4(void) 
{
    PyObject* m;

    if (PyType_Ready(&amp;NoddyType) &lt; 0)
        return;

    m = Py_InitModule3("noddy4", module_methods,
                       "Example module that creates an extension type.");

    if (m == NULL)
      return;

    Py_INCREF(&amp;NoddyType);
    PyModule_AddObject(m, "Noddy", (PyObject *)&amp;NoddyType);
}
</pre>
<div class="footer">
<a href="noddy4.txt" type="text/plain">Download as text (original file name: <span class="file">noddy4.c</span>).</a>
</div></div>

<P>
The traversal method provides access to subobjects that
could participate in cycles:

<P>
<div class="verbatim"><pre>
static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
    int vret;

    if (self-&gt;first) {
        vret = visit(self-&gt;first, arg);
        if (vret != 0)
            return vret;
    }
    if (self-&gt;last) {
        vret = visit(self-&gt;last, arg);
        if (vret != 0)
            return vret;
    }

    return 0;
}
</pre></div>

<P>
For each subobject that can participate in cycles, we need to call the
<tt class="cfunction">visit()</tt> function, which is passed to the traversal method.
The <tt class="cfunction">visit()</tt> function takes as arguments the subobject and
the extra argument <var>arg</var> passed to the traversal method.  It
returns an integer value that must be returned if it is non-zero.

<P>
Python 2.4 and higher provide a <tt class="cfunction">Py_VISIT()</tt> macro that automates
calling visit functions.  With <tt class="cfunction">Py_VISIT()</tt>,
<tt class="cfunction">Noddy_traverse()</tt> can be simplified:

<P>
<div class="verbatim"><pre>
static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
    Py_VISIT(self-&gt;first);
    Py_VISIT(self-&gt;last);
    return 0;
}
</pre></div>

<P>
<span class="note"><b class="label">Note:</b>
Note that the <tt class="member">tp_traverse</tt> implementation must name its
    arguments exactly <var>visit</var> and <var>arg</var> in order to use
    <tt class="cfunction">Py_VISIT()</tt>.  This is to encourage uniformity
    across these boring implementations.</span>

<P>
We also need to provide a method for clearing any subobjects that can
participate in cycles.  We implement the method and reimplement the
deallocator to use it:

<P>
<div class="verbatim"><pre>
static int
Noddy_clear(Noddy *self)
{
    PyObject *tmp;

    tmp = self-&gt;first;
    self-&gt;first = NULL;
    Py_XDECREF(tmp);

    tmp = self-&gt;last;
    self-&gt;last = NULL;
    Py_XDECREF(tmp);

    return 0;
}

static void
Noddy_dealloc(Noddy* self)
{
    Noddy_clear(self);
    self-&gt;ob_type-&gt;tp_free((PyObject*)self);
}
</pre></div>

<P>
Notice the use of a temporary variable in <tt class="cfunction">Noddy_clear()</tt>.
We use the temporary variable so that we can set each member to <tt class="constant">NULL</tt>
before decrementing its reference count.  We do this because, as was
discussed earlier, if the reference count drops to zero, we might
cause code to run that calls back into the object.  In addition,
because we now support garbage collection, we also have to worry about
code being run that triggers garbage collection.  If garbage
collection is run, our <tt class="member">tp_traverse</tt> handler could get called.
We can't take a chance of having <tt class="cfunction">Noddy_traverse()</tt> called
when a member's reference count has dropped to zero and its value
hasn't been set to <tt class="constant">NULL</tt>.

<P>
Python 2.4 and higher provide a <tt class="cfunction">Py_CLEAR()</tt> that automates
the careful decrementing of reference counts.  With
<tt class="cfunction">Py_CLEAR()</tt>, the <tt class="cfunction">Noddy_clear()</tt> function can be
simplified:

<P>
<div class="verbatim"><pre>
static int
Noddy_clear(Noddy *self)
{
    Py_CLEAR(self-&gt;first);
    Py_CLEAR(self-&gt;last);
    return 0;
}
</pre></div>

<P>
Finally, we add the <tt class="constant">Py_TPFLAGS_HAVE_GC</tt> flag to the class
flags:

<P>
<div class="verbatim"><pre>
    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/
</pre></div>

<P>
That's pretty much it.  If we had written custom <tt class="member">tp_alloc</tt> or
<tt class="member">tp_free</tt> slots, we'd need to modify them for cyclic-garbage
collection. Most extensions will use the versions automatically
provided.

<P>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot1173">...
attributes</A><A
 HREF="node24.html#tex2html8"><SUP>2.4</SUP></A></DT>
<DD>Even in the third version, we aren't guaranteed to
avoid cycles.  Instances of string subclasses are allowed and string
subclasses could allow cycles even if normal strings don't.

</DD>
</DL>
<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="2.1.2 Providing finer control"
  href="node23.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="2.1 The Basics"
  href="dnt-basics.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="2.2 Type Methods"
  href="dnt-type-methods.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="node23.html">2.1.2 Providing finer control</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="dnt-basics.html">2.1 The Basics</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="dnt-type-methods.html">2.2 Type Methods</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="prev" href="node23.html" />
	12	<link rel="parent" href="dnt-basics.html" />
	13	<link rel="next" href="dnt-type-methods.html" />
	14	<meta name='aesop' content='information' />
	15	<title>2.1.3 Supporting cyclic garbage collection</title>
	16	</head>
	17	<body>
	18	<DIV CLASS="navigation">
	19	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	20	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	21	<tr>
	22	<td class='online-navigation'><a rel="prev" title="2.1.2 Providing finer control"
	23	href="node23.html"><img src='../icons/previous.png'
	24	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	25	<td class='online-navigation'><a rel="parent" title="2.1 The Basics"
	26	href="dnt-basics.html"><img src='../icons/up.png'
	27	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	28	<td class='online-navigation'><a rel="next" title="2.2 Type Methods"
	29	href="dnt-type-methods.html"><img src='../icons/next.png'
	30	border='0' height='32' alt='Next Page' width='32' /></A></td>
	31	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
	32	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	33	href="contents.html"><img src='../icons/contents.png'
	34	border='0' height='32' alt='Contents' width='32' /></A></td>
	35	<td class='online-navigation'><img src='../icons/blank.png'
	36	border='0' height='32' alt='' width='32' /></td>
	37	<td class='online-navigation'><img src='../icons/blank.png'
	38	border='0' height='32' alt='' width='32' /></td>
	39	</tr></table>
	40	<div class='online-navigation'>
	41	<b class="navlabel">Previous:</b>
	42	<a class="sectref" rel="prev" href="node23.html">2.1.2 Providing finer control</A>
	43	<b class="navlabel">Up:</b>
	44	<a class="sectref" rel="parent" href="dnt-basics.html">2.1 The Basics</A>
	45	<b class="navlabel">Next:</b>
	46	<a class="sectref" rel="next" href="dnt-type-methods.html">2.2 Type Methods</A>
	47	</div>
	48	<hr /></div>
	49	</DIV>
	50	<!--End of Navigation Panel-->
	51
	52	<H2><A NAME="SECTION004130000000000000000">
	53	2.1.3 Supporting cyclic garbage collection</A>
	54	</H2>
	55
	56	<P>
	57	Python has a cyclic-garbage collector that can identify unneeded
	58	objects even when their reference counts are not zero. This can happen
	59	when objects are involved in cycles. For example, consider:
	60
	61	<P>
	62	<div class="verbatim"><pre>
	63	>>> l = []
	64	>>> l.append(l)
65	>>> del l
66	</pre></div>
67
68	<P>
69	In this example, we create a list that contains itself. When we delete
70	it, it still has a reference from itself. Its reference count doesn't
71	drop to zero. Fortunately, Python's cyclic-garbage collector will
72	eventually figure out that the list is garbage and free it.
73
74	<P>
75	In the second version of the <tt class="class">Noddy</tt> example, we allowed any
76	kind of object to be stored in the <tt class="member">first</tt> or <tt class="member">last</tt>
77	attributes<A NAME="tex2html8"
78	HREF="#foot1173"><SUP>2.4</SUP></A>. This
79	means that <tt class="class">Noddy</tt> objects can participate in cycles:
80
81	<P>
82	<div class="verbatim"><pre>
83	>>> import noddy2
84	>>> n = noddy2.Noddy()
85	>>> l = [n]
86	>>> n.first = l
87	</pre></div>
88
89	<P>
90	This is pretty silly, but it gives us an excuse to add support for the
91	cyclic-garbage collector to the <tt class="class">Noddy</tt> example. To support
92	cyclic garbage collection, types need to fill two slots and set a
93	class flag that enables these slots:
94
95	<P>
96	<div class="verbatim">
97	<pre>#include <Python.h>
98	#include "structmember.h"
99
100	typedef struct {
101	PyObject_HEAD
102	PyObject *first;
103	PyObject *last;
104	int number;
105	} Noddy;
106
107	static int
108	Noddy_traverse(Noddy self, visitproc visit, void arg)
109	{
110	int vret;
111
112	if (self->first) {
113	vret = visit(self->first, arg);
114	if (vret != 0)
115	return vret;
116	}
117	if (self->last) {
118	vret = visit(self->last, arg);
119	if (vret != 0)
120	return vret;
121	}
122
123	return 0;
124	}
125
126	static int
127	Noddy_clear(Noddy *self)
128	{
129	PyObject *tmp;
130
131	tmp = self->first;
132	self->first = NULL;
133	Py_XDECREF(tmp);
134
135	tmp = self->last;
136	self->last = NULL;
137	Py_XDECREF(tmp);
138
139	return 0;
140	}
141
142	static void
143	Noddy_dealloc(Noddy* self)
144	{
145	Noddy_clear(self);
146	self->ob_type->tp_free((PyObject*)self);
147	}
148
149	static PyObject *
150	Noddy_new(PyTypeObject type, PyObject args, PyObject *kwds)
151	{
152	Noddy *self;
153
154	self = (Noddy *)type->tp_alloc(type, 0);
155	if (self != NULL) {
156	self->first = PyString_FromString("");
157	if (self->first == NULL)
158	{
159	Py_DECREF(self);
160	return NULL;
161	}
162
163	self->last = PyString_FromString("");
164	if (self->last == NULL)
165	{
166	Py_DECREF(self);
167	return NULL;
168	}
169
170	self->number = 0;
171	}
172
173	return (PyObject *)self;
174	}
175
176	static int
177	Noddy_init(Noddy self, PyObject args, PyObject *kwds)
178	{
179	PyObject first=NULL, last=NULL, *tmp;
180
181	static char *kwlist[] = {"first", "last", "number", NULL};
182
183	if (! PyArg_ParseTupleAndKeywords(args, kwds, "\|OOi", kwlist,
184	&first, &last,
185	&self->number))
186	return -1;
187
188	if (first) {
189	tmp = self->first;
190	Py_INCREF(first);
191	self->first = first;
192	Py_XDECREF(tmp);
193	}
194
195	if (last) {
196	tmp = self->last;
197	Py_INCREF(last);
198	self->last = last;
199	Py_XDECREF(tmp);
200	}
201
202	return 0;
203	}
204
205	static PyMemberDef Noddy_members[] = {
206	{"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
207	"first name"},
208	{"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
209	"last name"},
210	{"number", T_INT, offsetof(Noddy, number), 0,
211	"noddy number"},
212	{NULL} /* Sentinel */
213	};
214
215	static PyObject *
216	Noddy_name(Noddy* self)
217	{
218	static PyObject *format = NULL;
219	PyObject args, result;
220
221	if (format == NULL) {
222	format = PyString_FromString("%s %s");
223	if (format == NULL)
224	return NULL;
225	}
226
227	if (self->first == NULL) {
228	PyErr_SetString(PyExc_AttributeError, "first");
229	return NULL;
230	}
231
232	if (self->last == NULL) {
233	PyErr_SetString(PyExc_AttributeError, "last");
234	return NULL;
235	}
236
237	args = Py_BuildValue("OO", self->first, self->last);
238	if (args == NULL)
239	return NULL;
240
241	result = PyString_Format(format, args);
242	Py_DECREF(args);
243
244	return result;
245	}
246
247	static PyMethodDef Noddy_methods[] = {
248	{"name", (PyCFunction)Noddy_name, METH_NOARGS,
249	"Return the name, combining the first and last name"
250	},
251	{NULL} /* Sentinel */
252	};
253
254	static PyTypeObject NoddyType = {
255	PyObject_HEAD_INIT(NULL)
256	0, /ob_size/
257	"noddy.Noddy", /tp_name/
258	sizeof(Noddy), /tp_basicsize/
259	0, /tp_itemsize/
260	(destructor)Noddy_dealloc, /tp_dealloc/
261	0, /tp_print/
262	0, /tp_getattr/
263	0, /tp_setattr/
264	0, /tp_compare/
265	0, /tp_repr/
266	0, /tp_as_number/
267	0, /tp_as_sequence/
268	0, /tp_as_mapping/
269	0, /tp_hash /
270	0, /tp_call/
271	0, /tp_str/
272	0, /tp_getattro/
273	0, /tp_setattro/
274	0, /tp_as_buffer/
275	Py_TPFLAGS_DEFAULT \| Py_TPFLAGS_BASETYPE \| Py_TPFLAGS_HAVE_GC, /tp_flags/
276	"Noddy objects", /* tp_doc */
277	(traverseproc)Noddy_traverse, /* tp_traverse */
278	(inquiry)Noddy_clear, /* tp_clear */
279	0, /* tp_richcompare */
280	0, /* tp_weaklistoffset */
281	0, /* tp_iter */
282	0, /* tp_iternext */
283	Noddy_methods, /* tp_methods */
284	Noddy_members, /* tp_members */
285	0, /* tp_getset */
286	0, /* tp_base */
287	0, /* tp_dict */
288	0, /* tp_descr_get */
289	0, /* tp_descr_set */
290	0, /* tp_dictoffset */
291	(initproc)Noddy_init, /* tp_init */
292	0, /* tp_alloc */
293	Noddy_new, /* tp_new */
294	};
295
296	static PyMethodDef module_methods[] = {
297	{NULL} /* Sentinel */
298	};
299
300	#ifndef PyMODINIT_FUNC /* declarations for DLL import/export */
301	#define PyMODINIT_FUNC void
302	#endif
303	PyMODINIT_FUNC
304	initnoddy4(void)
305	{
306	PyObject* m;
307
308	if (PyType_Ready(&NoddyType) < 0)
309	return;
310
311	m = Py_InitModule3("noddy4", module_methods,
312	"Example module that creates an extension type.");
313
314	if (m == NULL)
315	return;
316
317	Py_INCREF(&NoddyType);
318	PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
319	}
320	</pre>
321	<div class="footer">
322	<a href="noddy4.txt" type="text/plain">Download as text (original file name: <span class="file">noddy4.c</span>).</a>
323	</div></div>
324
325	<P>
326	The traversal method provides access to subobjects that
327	could participate in cycles:
328
329	<P>
330	<div class="verbatim"><pre>
331	static int
332	Noddy_traverse(Noddy self, visitproc visit, void arg)
333	{
334	int vret;
335
336	if (self->first) {
337	vret = visit(self->first, arg);
338	if (vret != 0)
339	return vret;
340	}
341	if (self->last) {
342	vret = visit(self->last, arg);
343	if (vret != 0)
344	return vret;
345	}
346
347	return 0;
348	}
349	</pre></div>
350
351	<P>
352	For each subobject that can participate in cycles, we need to call the
353	<tt class="cfunction">visit()</tt> function, which is passed to the traversal method.
354	The <tt class="cfunction">visit()</tt> function takes as arguments the subobject and
355	the extra argument <var>arg</var> passed to the traversal method. It
356	returns an integer value that must be returned if it is non-zero.
357
358	<P>
359	Python 2.4 and higher provide a <tt class="cfunction">Py_VISIT()</tt> macro that automates
360	calling visit functions. With <tt class="cfunction">Py_VISIT()</tt>,
361	<tt class="cfunction">Noddy_traverse()</tt> can be simplified:
362
363	<P>
364	<div class="verbatim"><pre>
365	static int
366	Noddy_traverse(Noddy self, visitproc visit, void arg)
367	{
368	Py_VISIT(self->first);
369	Py_VISIT(self->last);
370	return 0;
371	}
372	</pre></div>
373
374	<P>
375	<span class="note"><b class="label">Note:</b>
376	Note that the <tt class="member">tp_traverse</tt> implementation must name its
377	arguments exactly <var>visit</var> and <var>arg</var> in order to use
378	<tt class="cfunction">Py_VISIT()</tt>. This is to encourage uniformity
379	across these boring implementations.</span>
380
381	<P>
382	We also need to provide a method for clearing any subobjects that can
383	participate in cycles. We implement the method and reimplement the
384	deallocator to use it:
385
386	<P>
387	<div class="verbatim"><pre>
388	static int
389	Noddy_clear(Noddy *self)
390	{
391	PyObject *tmp;
392
393	tmp = self->first;
394	self->first = NULL;
395	Py_XDECREF(tmp);
396
397	tmp = self->last;
398	self->last = NULL;
399	Py_XDECREF(tmp);
400
401	return 0;
402	}
403
404	static void
405	Noddy_dealloc(Noddy* self)
406	{
407	Noddy_clear(self);
408	self->ob_type->tp_free((PyObject*)self);
409	}
410	</pre></div>
411
412	<P>
413	Notice the use of a temporary variable in <tt class="cfunction">Noddy_clear()</tt>.
414	We use the temporary variable so that we can set each member to <tt class="constant">NULL</tt>
415	before decrementing its reference count. We do this because, as was
416	discussed earlier, if the reference count drops to zero, we might
417	cause code to run that calls back into the object. In addition,
418	because we now support garbage collection, we also have to worry about
419	code being run that triggers garbage collection. If garbage
420	collection is run, our <tt class="member">tp_traverse</tt> handler could get called.
421	We can't take a chance of having <tt class="cfunction">Noddy_traverse()</tt> called
422	when a member's reference count has dropped to zero and its value
423	hasn't been set to <tt class="constant">NULL</tt>.
424
425	<P>
426	Python 2.4 and higher provide a <tt class="cfunction">Py_CLEAR()</tt> that automates
427	the careful decrementing of reference counts. With
428	<tt class="cfunction">Py_CLEAR()</tt>, the <tt class="cfunction">Noddy_clear()</tt> function can be
429	simplified:
430
431	<P>
432	<div class="verbatim"><pre>
433	static int
434	Noddy_clear(Noddy *self)
435	{
436	Py_CLEAR(self->first);
437	Py_CLEAR(self->last);
438	return 0;
439	}
440	</pre></div>
441
442	<P>
443	Finally, we add the <tt class="constant">Py_TPFLAGS_HAVE_GC</tt> flag to the class
444	flags:
445
446	<P>
447	<div class="verbatim"><pre>
448	Py_TPFLAGS_DEFAULT \| Py_TPFLAGS_BASETYPE \| Py_TPFLAGS_HAVE_GC, /tp_flags/
449	</pre></div>
450
451	<P>
452	That's pretty much it. If we had written custom <tt class="member">tp_alloc</tt> or
453	<tt class="member">tp_free</tt> slots, we'd need to modify them for cyclic-garbage
454	collection. Most extensions will use the versions automatically
455	provided.
456
457	<P>
458	<BR><HR><H4>Footnotes</H4>
459	<DL>
460	<DT><A NAME="foot1173">...
461	attributes</A><A
462	HREF="node24.html#tex2html8"><SUP>2.4</SUP></A></DT>
463	<DD>Even in the third version, we aren't guaranteed to
464	avoid cycles. Instances of string subclasses are allowed and string
465	subclasses could allow cycles even if normal strings don't.
466
467	</DD>
468	</DL>
469	<DIV CLASS="navigation">
470	<div class='online-navigation'>
471	<p></p><hr />
472	<table align="center" width="100%" cellpadding="0" cellspacing="2">
473	<tr>
474	<td class='online-navigation'><a rel="prev" title="2.1.2 Providing finer control"
475	href="node23.html"><img src='../icons/previous.png'
476	border='0' height='32' alt='Previous Page' width='32' /></A></td>
477	<td class='online-navigation'><a rel="parent" title="2.1 The Basics"
478	href="dnt-basics.html"><img src='../icons/up.png'
479	border='0' height='32' alt='Up One Level' width='32' /></A></td>
480	<td class='online-navigation'><a rel="next" title="2.2 Type Methods"
481	href="dnt-type-methods.html"><img src='../icons/next.png'
482	border='0' height='32' alt='Next Page' width='32' /></A></td>
483	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
484	<td class='online-navigation'><a rel="contents" title="Table of Contents"
485	href="contents.html"><img src='../icons/contents.png'
486	border='0' height='32' alt='Contents' width='32' /></A></td>
487	<td class='online-navigation'><img src='../icons/blank.png'
488	border='0' height='32' alt='' width='32' /></td>
489	<td class='online-navigation'><img src='../icons/blank.png'
490	border='0' height='32' alt='' width='32' /></td>
491	</tr></table>
492	<div class='online-navigation'>
493	<b class="navlabel">Previous:</b>
494	<a class="sectref" rel="prev" href="node23.html">2.1.2 Providing finer control</A>
495	<b class="navlabel">Up:</b>
496	<a class="sectref" rel="parent" href="dnt-basics.html">2.1 The Basics</A>
497	<b class="navlabel">Next:</b>
498	<a class="sectref" rel="next" href="dnt-type-methods.html">2.2 Type Methods</A>
499	</div>
500	</div>
501	<hr />
502	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
503	</DIV>
504	<!--End of Navigation Panel-->
505	<ADDRESS>
506	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
507	</ADDRESS>
508	</BODY>
509	</HTML>