[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / ext / node26.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="node27.html" />
<link rel="prev" href="dnt-type-methods.html" />
<link rel="parent" href="dnt-type-methods.html" />
<link rel="next" href="node27.html" />
<meta name='aesop' content='information' />
<title>2.2.1 Finalization and De-allocation</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.2 Type Methods"
  href="dnt-type-methods.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.2 Type Methods"
  href="dnt-type-methods.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.2 Object Presentation"
  href="node27.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="dnt-type-methods.html">2.2 Type Methods</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="dnt-type-methods.html">2.2 Type Methods</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node27.html">2.2.2 Object Presentation</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION004210000000000000000">
2.2.1 Finalization and De-allocation</A>
</H2>

<P>
<a id='l2h-5' xml:id='l2h-5'></a>

<P>
<div class="verbatim"><pre>
    destructor tp_dealloc;
</pre></div>

<P>
This function is called when the reference count of the instance of
your type is reduced to zero and the Python interpreter wants to
reclaim it.  If your type has memory to free or other clean-up to
perform, put it here.  The object itself needs to be freed here as
well.  Here is an example of this function:

<P>
<div class="verbatim"><pre>
static void
newdatatype_dealloc(newdatatypeobject * obj)
{
    free(obj-&gt;obj_UnderlyingDatatypePtr);
    obj-&gt;ob_type-&gt;tp_free(obj);
}
</pre></div>

<P>
One important requirement of the deallocator function is that it
leaves any pending exceptions alone.  This is important since
deallocators are frequently called as the interpreter unwinds the
Python stack; when the stack is unwound due to an exception (rather
than normal returns), nothing is done to protect the deallocators from
seeing that an exception has already been set.  Any actions which a
deallocator performs which may cause additional Python code to be
executed may detect that an exception has been set.  This can lead to
misleading errors from the interpreter.  The proper way to protect
against this is to save a pending exception before performing the
unsafe action, and restoring it when done.  This can be done using the
<tt class="cfunction">PyErr_Fetch()</tt><a id='l2h-6' xml:id='l2h-6'></a> and
<tt class="cfunction">PyErr_Restore()</tt><a id='l2h-7' xml:id='l2h-7'></a> functions:

<P>
<div class="verbatim"><pre>
static void
my_dealloc(PyObject *obj)
{
    MyObject *self = (MyObject *) obj;
    PyObject *cbresult;

    if (self-&gt;my_callback != NULL) {
        PyObject *err_type, *err_value, *err_traceback;
        int have_error = PyErr_Occurred() ? 1 : 0;

        if (have_error)
            PyErr_Fetch(&amp;err_type, &amp;err_value, &amp;err_traceback);

        cbresult = PyObject_CallObject(self-&gt;my_callback, NULL);
        if (cbresult == NULL)
            PyErr_WriteUnraisable(self-&gt;my_callback);
        else
            Py_DECREF(cbresult);

        if (have_error)
            PyErr_Restore(err_type, err_value, err_traceback);

        Py_DECREF(self-&gt;my_callback);
    }
    obj-&gt;ob_type-&gt;tp_free((PyObject*)self);
}
</pre></div>

<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="2.2 Type Methods"
  href="dnt-type-methods.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.2 Type Methods"
  href="dnt-type-methods.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.2 Object Presentation"
  href="node27.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="dnt-type-methods.html">2.2 Type Methods</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="dnt-type-methods.html">2.2 Type Methods</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="node27.html">2.2.2 Object Presentation</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
86530b38 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="node27.html" />
	12	<link rel="prev" href="dnt-type-methods.html" />
	13	<link rel="parent" href="dnt-type-methods.html" />
	14	<link rel="next" href="node27.html" />
	15	<meta name='aesop' content='information' />
	16	<title>2.2.1 Finalization and De-allocation</title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="2.2 Type Methods"
	24	href="dnt-type-methods.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="2.2 Type Methods"
	27	href="dnt-type-methods.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="2.2.2 Object Presentation"
	30	href="node27.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><img src='../icons/blank.png'
	37	border='0' height='32' alt='' width='32' /></td>
	38	<td class='online-navigation'><img src='../icons/blank.png'
	39	border='0' height='32' alt='' width='32' /></td>
	40	</tr></table>
	41	<div class='online-navigation'>
	42	<b class="navlabel">Previous:</b>
	43	<a class="sectref" rel="prev" href="dnt-type-methods.html">2.2 Type Methods</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="dnt-type-methods.html">2.2 Type Methods</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="node27.html">2.2.2 Object Presentation</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H2><A NAME="SECTION004210000000000000000">
	54	2.2.1 Finalization and De-allocation</A>
	55	</H2>
	56
	57	<P>
	58	<a id='l2h-5' xml:id='l2h-5'></a>
	59
	60	<P>
	61	<div class="verbatim"><pre>
	62	destructor tp_dealloc;
	63	</pre></div>
	64
65	<P>
66	This function is called when the reference count of the instance of
67	your type is reduced to zero and the Python interpreter wants to
68	reclaim it. If your type has memory to free or other clean-up to
69	perform, put it here. The object itself needs to be freed here as
70	well. Here is an example of this function:
71
72	<P>
73	<div class="verbatim"><pre>
74	static void
75	newdatatype_dealloc(newdatatypeobject * obj)
76	{
77	free(obj->obj_UnderlyingDatatypePtr);
78	obj->ob_type->tp_free(obj);
79	}
80	</pre></div>
81
82	<P>
83	One important requirement of the deallocator function is that it
84	leaves any pending exceptions alone. This is important since
85	deallocators are frequently called as the interpreter unwinds the
86	Python stack; when the stack is unwound due to an exception (rather
87	than normal returns), nothing is done to protect the deallocators from
88	seeing that an exception has already been set. Any actions which a
89	deallocator performs which may cause additional Python code to be
90	executed may detect that an exception has been set. This can lead to
91	misleading errors from the interpreter. The proper way to protect
92	against this is to save a pending exception before performing the
93	unsafe action, and restoring it when done. This can be done using the
94	<tt class="cfunction">PyErr_Fetch()</tt><a id='l2h-6' xml:id='l2h-6'></a> and
95	<tt class="cfunction">PyErr_Restore()</tt><a id='l2h-7' xml:id='l2h-7'></a> functions:
96
97	<P>
98	<div class="verbatim"><pre>
99	static void
100	my_dealloc(PyObject *obj)
101	{
102	MyObject self = (MyObject ) obj;
103	PyObject *cbresult;
104
105	if (self->my_callback != NULL) {
106	PyObject err_type, err_value, *err_traceback;
107	int have_error = PyErr_Occurred() ? 1 : 0;
108
109	if (have_error)
110	PyErr_Fetch(&err_type, &err_value, &err_traceback);
111
112	cbresult = PyObject_CallObject(self->my_callback, NULL);
113	if (cbresult == NULL)
114	PyErr_WriteUnraisable(self->my_callback);
115	else
116	Py_DECREF(cbresult);
117
118	if (have_error)
119	PyErr_Restore(err_type, err_value, err_traceback);
120
121	Py_DECREF(self->my_callback);
122	}
123	obj->ob_type->tp_free((PyObject*)self);
124	}
125	</pre></div>
126
127	<P>
128
129	<DIV CLASS="navigation">
130	<div class='online-navigation'>
131	<p></p><hr />
132	<table align="center" width="100%" cellpadding="0" cellspacing="2">
133	<tr>
134	<td class='online-navigation'><a rel="prev" title="2.2 Type Methods"
135	href="dnt-type-methods.html"><img src='../icons/previous.png'
136	border='0' height='32' alt='Previous Page' width='32' /></A></td>
137	<td class='online-navigation'><a rel="parent" title="2.2 Type Methods"
138	href="dnt-type-methods.html"><img src='../icons/up.png'
139	border='0' height='32' alt='Up One Level' width='32' /></A></td>
140	<td class='online-navigation'><a rel="next" title="2.2.2 Object Presentation"
141	href="node27.html"><img src='../icons/next.png'
142	border='0' height='32' alt='Next Page' width='32' /></A></td>
143	<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
144	<td class='online-navigation'><a rel="contents" title="Table of Contents"
145	href="contents.html"><img src='../icons/contents.png'
146	border='0' height='32' alt='Contents' width='32' /></A></td>
147	<td class='online-navigation'><img src='../icons/blank.png'
148	border='0' height='32' alt='' width='32' /></td>
149	<td class='online-navigation'><img src='../icons/blank.png'
150	border='0' height='32' alt='' width='32' /></td>
151	</tr></table>
152	<div class='online-navigation'>
153	<b class="navlabel">Previous:</b>
154	<a class="sectref" rel="prev" href="dnt-type-methods.html">2.2 Type Methods</A>
155	<b class="navlabel">Up:</b>
156	<a class="sectref" rel="parent" href="dnt-type-methods.html">2.2 Type Methods</A>
157	<b class="navlabel">Next:</b>
158	<a class="sectref" rel="next" href="node27.html">2.2.2 Object Presentation</A>
159	</div>
160	</div>
161	<hr />
162	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
163	</DIV>
164	<!--End of Navigation Panel-->
165	<ADDRESS>
166	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
167	</ADDRESS>
168	</BODY>
169	</HTML>