[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / lib / weakref-extension.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.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="lib.html" title='Python Library Reference' />
<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="prev" href="weakref-example.html" />
<link rel="parent" href="module-weakref.html" />
<link rel="next" href="module-fpectl.html" />
<meta name='aesop' content='information' />
<title>3.3.3 Weak References in Extension Types </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="3.3.2 Example"
  href="weakref-example.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="3.3 weakref  "
  href="module-weakref.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="3.4 fpectl  "
  href="module-fpectl.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</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'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></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="weakref-example.html">3.3.2 Example</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-weakref.html">3.3 weakref  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-fpectl.html">3.4 fpectl  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION005330000000000000000"></A><A NAME="weakref-extension"></A>
<BR>
3.3.3 Weak References in Extension Types
            
</H2>

<P>
One of the goals of the implementation is to allow any type to
participate in the weak reference mechanism without incurring the
overhead on those objects which do not benefit by weak referencing
(such as numbers).

<P>
For an object to be weakly referencable, the extension must include a
<tt class="ctype">PyObject*</tt> field in the instance structure for the use of the
weak reference mechanism; it must be initialized to <tt class="constant">NULL</tt> by the
object's constructor.  It must also set the <tt class="member">tp_weaklistoffset</tt>
field of the corresponding type object to the offset of the field.
Also, it needs to add <tt class="constant">Py_TPFLAGS_HAVE_WEAKREFS</tt> to the
tp_flags slot.  For example, the instance type is defined with the
following structure:

<P>
<div class="verbatim"><pre>
typedef struct {
    PyObject_HEAD
    PyClassObject *in_class;       /* The class object */
    PyObject      *in_dict;        /* A dictionary */
    PyObject      *in_weakreflist; /* List of weak references */
} PyInstanceObject;
</pre></div>

<P>
The statically-declared type object for instances is defined this way:

<P>
<div class="verbatim"><pre>
PyTypeObject PyInstance_Type = {
    PyObject_HEAD_INIT(&amp;PyType_Type)
    0,
    "module.instance",

    /* Lots of stuff omitted for brevity... */

    Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_WEAKREFS   /* tp_flags */
    0,                                          /* tp_doc */
    0,                                          /* tp_traverse */
    0,                                          /* tp_clear */
    0,                                          /* tp_richcompare */
    offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
};
</pre></div>

<P>
The type constructor is responsible for initializing the weak reference
list to <tt class="constant">NULL</tt>:

<P>
<div class="verbatim"><pre>
static PyObject *
instance_new() {
    /* Other initialization stuff omitted for brevity */

    self-&gt;in_weakreflist = NULL;

    return (PyObject *) self;
}
</pre></div>

<P>
The only further addition is that the destructor needs to call the
weak reference manager to clear any weak references.  This should be
done before any other parts of the destruction have occurred, but is
only required if the weak reference list is non-<tt class="constant">NULL</tt>:

<P>
<div class="verbatim"><pre>
static void
instance_dealloc(PyInstanceObject *inst)
{
    /* Allocate temporaries if needed, but do not begin
       destruction just yet.
     */

    if (inst-&gt;in_weakreflist != NULL)
        PyObject_ClearWeakRefs((PyObject *) inst);

    /* Proceed with object destruction normally. */
}
</pre></div>

<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="3.3.2 Example"
  href="weakref-example.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="3.3 weakref  "
  href="module-weakref.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="3.4 fpectl  "
  href="module-fpectl.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</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'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></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="weakref-example.html">3.3.2 Example</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-weakref.html">3.3 weakref  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-fpectl.html">3.4 fpectl  </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="lib.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="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="prev" href="weakref-example.html" />
	13	<link rel="parent" href="module-weakref.html" />
	14	<link rel="next" href="module-fpectl.html" />
	15	<meta name='aesop' content='information' />
	16	<title>3.3.3 Weak References in Extension Types </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="3.3.2 Example"
	24	href="weakref-example.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="3.3 weakref "
	27	href="module-weakref.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="3.4 fpectl "
	30	href="module-fpectl.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Python Library Reference</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'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	37	border='0' height='32' alt='Module Index' width='32' /></a></td>
	38	<td class='online-navigation'><a rel="index" title="Index"
	39	href="genindex.html"><img src='../icons/index.png'
	40	border='0' height='32' alt='Index' width='32' /></A></td>
	41	</tr></table>
	42	<div class='online-navigation'>
	43	<b class="navlabel">Previous:</b>
	44	<a class="sectref" rel="prev" href="weakref-example.html">3.3.2 Example</A>
	45	<b class="navlabel">Up:</b>
	46	<a class="sectref" rel="parent" href="module-weakref.html">3.3 weakref </A>
	47	<b class="navlabel">Next:</b>
	48	<a class="sectref" rel="next" href="module-fpectl.html">3.4 fpectl </A>
	49	</div>
	50	<hr /></div>
	51	</DIV>
	52	<!--End of Navigation Panel-->
	53
	54	<H2><A NAME="SECTION005330000000000000000"></A><A NAME="weakref-extension"></A>
	55	<BR>
	56	3.3.3 Weak References in Extension Types
	57
	58	</H2>
	59
	60	<P>
	61	One of the goals of the implementation is to allow any type to
	62	participate in the weak reference mechanism without incurring the
	63	overhead on those objects which do not benefit by weak referencing
	64	(such as numbers).
65
66	<P>
67	For an object to be weakly referencable, the extension must include a
68	<tt class="ctype">PyObject*</tt> field in the instance structure for the use of the
69	weak reference mechanism; it must be initialized to <tt class="constant">NULL</tt> by the
70	object's constructor. It must also set the <tt class="member">tp_weaklistoffset</tt>
71	field of the corresponding type object to the offset of the field.
72	Also, it needs to add <tt class="constant">Py_TPFLAGS_HAVE_WEAKREFS</tt> to the
73	tp_flags slot. For example, the instance type is defined with the
74	following structure:
75
76	<P>
77	<div class="verbatim"><pre>
78	typedef struct {
79	PyObject_HEAD
80	PyClassObject in_class; / The class object */
81	PyObject in_dict; / A dictionary */
82	PyObject in_weakreflist; / List of weak references */
83	} PyInstanceObject;
84	</pre></div>
85
86	<P>
87	The statically-declared type object for instances is defined this way:
88
89	<P>
90	<div class="verbatim"><pre>
91	PyTypeObject PyInstance_Type = {
92	PyObject_HEAD_INIT(&PyType_Type)
93	0,
94	"module.instance",
95
96	/* Lots of stuff omitted for brevity... */
97
98	Py_TPFLAGS_DEFAULT \| Py_TPFLAGS_HAVE_WEAKREFS /* tp_flags */
99	0, /* tp_doc */
100	0, /* tp_traverse */
101	0, /* tp_clear */
102	0, /* tp_richcompare */
103	offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
104	};
105	</pre></div>
106
107	<P>
108	The type constructor is responsible for initializing the weak reference
109	list to <tt class="constant">NULL</tt>:
110
111	<P>
112	<div class="verbatim"><pre>
113	static PyObject *
114	instance_new() {
115	/* Other initialization stuff omitted for brevity */
116
117	self->in_weakreflist = NULL;
118
119	return (PyObject *) self;
120	}
121	</pre></div>
122
123	<P>
124	The only further addition is that the destructor needs to call the
125	weak reference manager to clear any weak references. This should be
126	done before any other parts of the destruction have occurred, but is
127	only required if the weak reference list is non-<tt class="constant">NULL</tt>:
128
129	<P>
130	<div class="verbatim"><pre>
131	static void
132	instance_dealloc(PyInstanceObject *inst)
133	{
134	/* Allocate temporaries if needed, but do not begin
135	destruction just yet.
136	*/
137
138	if (inst->in_weakreflist != NULL)
139	PyObject_ClearWeakRefs((PyObject *) inst);
140
141	/* Proceed with object destruction normally. */
142	}
143	</pre></div>
144
145	<DIV CLASS="navigation">
146	<div class='online-navigation'>
147	<p></p><hr />
148	<table align="center" width="100%" cellpadding="0" cellspacing="2">
149	<tr>
150	<td class='online-navigation'><a rel="prev" title="3.3.2 Example"
151	href="weakref-example.html"><img src='../icons/previous.png'
152	border='0' height='32' alt='Previous Page' width='32' /></A></td>
153	<td class='online-navigation'><a rel="parent" title="3.3 weakref "
154	href="module-weakref.html"><img src='../icons/up.png'
155	border='0' height='32' alt='Up One Level' width='32' /></A></td>
156	<td class='online-navigation'><a rel="next" title="3.4 fpectl "
157	href="module-fpectl.html"><img src='../icons/next.png'
158	border='0' height='32' alt='Next Page' width='32' /></A></td>
159	<td align="center" width="100%">Python Library Reference</td>
160	<td class='online-navigation'><a rel="contents" title="Table of Contents"
161	href="contents.html"><img src='../icons/contents.png'
162	border='0' height='32' alt='Contents' width='32' /></A></td>
163	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
164	border='0' height='32' alt='Module Index' width='32' /></a></td>
165	<td class='online-navigation'><a rel="index" title="Index"
166	href="genindex.html"><img src='../icons/index.png'
167	border='0' height='32' alt='Index' width='32' /></A></td>
168	</tr></table>
169	<div class='online-navigation'>
170	<b class="navlabel">Previous:</b>
171	<a class="sectref" rel="prev" href="weakref-example.html">3.3.2 Example</A>
172	<b class="navlabel">Up:</b>
173	<a class="sectref" rel="parent" href="module-weakref.html">3.3 weakref </A>
174	<b class="navlabel">Next:</b>
175	<a class="sectref" rel="next" href="module-fpectl.html">3.4 fpectl </A>
176	</div>
177	</div>
178	<hr />
179	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
180	</DIV>
181	<!--End of Navigation Panel-->
182	<ADDRESS>
183	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
184	</ADDRESS>
185	</BODY>
186	</HTML>