1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
<html xmlns="http://www.w3.org/1999/xhtml">
7
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
9
<title>Reference Counting — Python 3.5.1 documentation</title>
11
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
12
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
14
<script type="text/javascript">
15
var DOCUMENTATION_OPTIONS = {
18
COLLAPSE_INDEX: false,
23
<script type="text/javascript" src="../_static/jquery.js"></script>
24
<script type="text/javascript" src="../_static/underscore.js"></script>
25
<script type="text/javascript" src="../_static/doctools.js"></script>
26
<script type="text/javascript" src="../_static/sidebar.js"></script>
27
<link rel="search" type="application/opensearchdescription+xml"
28
title="Search within Python 3.5.1 documentation"
29
href="../_static/opensearch.xml"/>
30
<link rel="author" title="About these documents" href="../about.html" />
31
<link rel="copyright" title="Copyright" href="../copyright.html" />
32
<link rel="top" title="Python 3.5.1 documentation" href="../contents.html" />
33
<link rel="up" title="Python/C API Reference Manual" href="index.html" />
34
<link rel="next" title="Exception Handling" href="exceptions.html" />
35
<link rel="prev" title="The Very High Level Layer" href="veryhigh.html" />
36
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
37
<script type="text/javascript" src="../_static/copybutton.js"></script>
38
<script type="text/javascript" src="../_static/version_switch.js"></script>
43
<body role="document">
44
<div class="related" role="navigation" aria-label="related navigation">
47
<li class="right" style="margin-right: 10px">
48
<a href="../genindex.html" title="General Index"
49
accesskey="I">index</a></li>
51
<a href="../py-modindex.html" title="Python Module Index"
54
<a href="exceptions.html" title="Exception Handling"
55
accesskey="N">next</a> |</li>
57
<a href="veryhigh.html" title="The Very High Level Layer"
58
accesskey="P">previous</a> |</li>
59
<li><img src="../_static/py.png" alt=""
60
style="vertical-align: middle; margin-top: -1px"/></li>
61
<li><a href="https://www.python.org/">Python</a> »</li>
63
<span class="version_switcher_placeholder">3.5.1</span>
64
<a href="../index.html">Documentation </a> »
67
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
71
<div class="document">
72
<div class="documentwrapper">
73
<div class="bodywrapper">
74
<div class="body" role="main">
76
<div class="section" id="reference-counting">
77
<span id="countingrefs"></span><h1>Reference Counting<a class="headerlink" href="#reference-counting" title="Permalink to this headline">¶</a></h1>
78
<p>The macros in this section are used for managing reference counts of Python
82
void <code class="descname">Py_INCREF</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_INCREF" title="Permalink to this definition">¶</a></dt>
83
<dd><p>Increment the reference count for object <em>o</em>. The object must not be <em>NULL</em>; if
84
you aren’t sure that it isn’t <em>NULL</em>, use <a class="reference internal" href="#c.Py_XINCREF" title="Py_XINCREF"><code class="xref c c-func docutils literal"><span class="pre">Py_XINCREF()</span></code></a>.</p>
88
<dt id="c.Py_XINCREF">
89
void <code class="descname">Py_XINCREF</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_XINCREF" title="Permalink to this definition">¶</a></dt>
90
<dd><p>Increment the reference count for object <em>o</em>. The object may be <em>NULL</em>, in
91
which case the macro has no effect.</p>
96
void <code class="descname">Py_DECREF</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_DECREF" title="Permalink to this definition">¶</a></dt>
97
<dd><p>Decrement the reference count for object <em>o</em>. The object must not be <em>NULL</em>; if
98
you aren’t sure that it isn’t <em>NULL</em>, use <a class="reference internal" href="#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal"><span class="pre">Py_XDECREF()</span></code></a>. If the reference
99
count reaches zero, the object’s type’s deallocation function (which must not be
100
<em>NULL</em>) is invoked.</p>
101
<div class="admonition warning">
102
<p class="first admonition-title">Warning</p>
103
<p class="last">The deallocation function can cause arbitrary Python code to be invoked (e.g.
104
when a class instance with a <a class="reference internal" href="../reference/datamodel.html#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal"><span class="pre">__del__()</span></code></a> method is deallocated). While
105
exceptions in such code are not propagated, the executed code has free access to
106
all Python global variables. This means that any object that is reachable from
107
a global variable should be in a consistent state before <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal"><span class="pre">Py_DECREF()</span></code></a> is
108
invoked. For example, code to delete an object from a list should copy a
109
reference to the deleted object in a temporary variable, update the list data
110
structure, and then call <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal"><span class="pre">Py_DECREF()</span></code></a> for the temporary variable.</p>
114
<dl class="function">
115
<dt id="c.Py_XDECREF">
116
void <code class="descname">Py_XDECREF</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_XDECREF" title="Permalink to this definition">¶</a></dt>
117
<dd><p>Decrement the reference count for object <em>o</em>. The object may be <em>NULL</em>, in
118
which case the macro has no effect; otherwise the effect is the same as for
119
<a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal"><span class="pre">Py_DECREF()</span></code></a>, and the same warning applies.</p>
122
<dl class="function">
124
void <code class="descname">Py_CLEAR</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_CLEAR" title="Permalink to this definition">¶</a></dt>
125
<dd><p>Decrement the reference count for object <em>o</em>. The object may be <em>NULL</em>, in
126
which case the macro has no effect; otherwise the effect is the same as for
127
<a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal"><span class="pre">Py_DECREF()</span></code></a>, except that the argument is also set to <em>NULL</em>. The warning
128
for <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal"><span class="pre">Py_DECREF()</span></code></a> does not apply with respect to the object passed because
129
the macro carefully uses a temporary variable and sets the argument to <em>NULL</em>
130
before decrementing its reference count.</p>
131
<p>It is a good idea to use this macro whenever decrementing the value of a
132
variable that might be traversed during garbage collection.</p>
135
<p>The following functions are for runtime dynamic embedding of Python:
136
<code class="docutils literal"><span class="pre">Py_IncRef(PyObject</span> <span class="pre">*o)</span></code>, <code class="docutils literal"><span class="pre">Py_DecRef(PyObject</span> <span class="pre">*o)</span></code>. They are
137
simply exported function versions of <a class="reference internal" href="#c.Py_XINCREF" title="Py_XINCREF"><code class="xref c c-func docutils literal"><span class="pre">Py_XINCREF()</span></code></a> and
138
<a class="reference internal" href="#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal"><span class="pre">Py_XDECREF()</span></code></a>, respectively.</p>
139
<p>The following functions or macros are only for use within the interpreter core:
140
<code class="xref c c-func docutils literal"><span class="pre">_Py_Dealloc()</span></code>, <code class="xref c c-func docutils literal"><span class="pre">_Py_ForgetReference()</span></code>, <code class="xref c c-func docutils literal"><span class="pre">_Py_NewReference()</span></code>,
141
as well as the global variable <code class="xref c c-data docutils literal"><span class="pre">_Py_RefTotal</span></code>.</p>
148
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
149
<div class="sphinxsidebarwrapper">
150
<h4>Previous topic</h4>
151
<p class="topless"><a href="veryhigh.html"
152
title="previous chapter">The Very High Level Layer</a></p>
154
<p class="topless"><a href="exceptions.html"
155
title="next chapter">Exception Handling</a></p>
157
<ul class="this-page-menu">
158
<li><a href="../bugs.html">Report a Bug</a></li>
159
<li><a href="../_sources/c-api/refcounting.txt"
160
rel="nofollow">Show Source</a></li>
163
<div id="searchbox" style="display: none" role="search">
164
<h3>Quick search</h3>
165
<form class="search" action="../search.html" method="get">
166
<input type="text" name="q" />
167
<input type="submit" value="Go" />
168
<input type="hidden" name="check_keywords" value="yes" />
169
<input type="hidden" name="area" value="default" />
171
<p class="searchtip" style="font-size: 90%">
172
Enter search terms or a module, class or function name.
175
<script type="text/javascript">$('#searchbox').show(0);</script>
178
<div class="clearer"></div>
180
<div class="related" role="navigation" aria-label="related navigation">
183
<li class="right" style="margin-right: 10px">
184
<a href="../genindex.html" title="General Index"
187
<a href="../py-modindex.html" title="Python Module Index"
190
<a href="exceptions.html" title="Exception Handling"
193
<a href="veryhigh.html" title="The Very High Level Layer"
195
<li><img src="../_static/py.png" alt=""
196
style="vertical-align: middle; margin-top: -1px"/></li>
197
<li><a href="https://www.python.org/">Python</a> »</li>
199
<span class="version_switcher_placeholder">3.5.1</span>
200
<a href="../index.html">Documentation </a> »
203
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
207
© <a href="../copyright.html">Copyright</a> 1990-2016, Python Software Foundation.
209
The Python Software Foundation is a non-profit corporation.
210
<a href="https://www.python.org/psf/donations/">Please donate.</a>
212
Last updated on Jan 22, 2016.
213
<a href="../bugs.html">Found a bug</a>?
215
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.
b'\\ No newline at end of file'
added
removed
python-3.5.1-docs-html/c-api/refcounting.html
