sam-t2/devtools/v9/html/python/api/memoryOverview.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="memoryInterface.html" />
<link rel="prev" href="memory.html" />
<link rel="parent" href="memory.html" />
<link rel="next" href="memoryInterface.html" />
<meta name='aesop' content='information' />
<title>9.1 Overview </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="9. Memory Management"
  href="memory.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="9. Memory Management"
  href="memory.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="9.2 Memory Interface"
  href="memoryInterface.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="memory.html">9. Memory Management</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="memory.html">9. Memory Management</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="memoryInterface.html">9.2 Memory Interface</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0011100000000000000000"></A><A NAME="memoryOverview"></A>
<BR>
9.1 Overview
</H1>

<P>
Memory management in Python involves a private heap containing all
Python objects and data structures. The management of this private
heap is ensured internally by the <em>Python memory manager</em>.  The
Python memory manager has different components which deal with various
dynamic storage management aspects, like sharing, segmentation,
preallocation or caching.

<P>
At the lowest level, a raw memory allocator ensures that there is
enough room in the private heap for storing all Python-related data
by interacting with the memory manager of the operating system. On top
of the raw memory allocator, several object-specific allocators
operate on the same heap and implement distinct memory management
policies adapted to the peculiarities of every object type. For
example, integer objects are managed differently within the heap than
strings, tuples or dictionaries because integers imply different
storage requirements and speed/space tradeoffs. The Python memory
manager thus delegates some of the work to the object-specific
allocators, but ensures that the latter operate within the bounds of
the private heap.

<P>
It is important to understand that the management of the Python heap
is performed by the interpreter itself and that the user has no
control over it, even if she regularly manipulates object pointers to
memory blocks inside that heap.  The allocation of heap space for
Python objects and other internal buffers is performed on demand by
the Python memory manager through the Python/C API functions listed in
this document.

<P>
To avoid memory corruption, extension writers should never try to
operate on Python objects with the functions exported by the C
library: <tt class="cfunction">malloc()</tt><a id='l2h-895' xml:id='l2h-895'></a>,
<tt class="cfunction">calloc()</tt><a id='l2h-896' xml:id='l2h-896'></a>,
<tt class="cfunction">realloc()</tt><a id='l2h-897' xml:id='l2h-897'></a> and
<tt class="cfunction">free()</tt><a id='l2h-898' xml:id='l2h-898'></a>.  This will result in
mixed calls between the C allocator and the Python memory manager
with fatal consequences, because they implement different algorithms
and operate on different heaps.  However, one may safely allocate and
release memory blocks with the C library allocator for individual
purposes, as shown in the following example:

<P>
<div class="verbatim"><pre>
    PyObject *res;
    char *buf = (char *) malloc(BUFSIZ); /* for I/O */

    if (buf == NULL)
        return PyErr_NoMemory();
    ...Do some I/O operation involving buf...
    res = PyString_FromString(buf);
    free(buf); /* malloc'ed */
    return res;
</pre></div>

<P>
In this example, the memory request for the I/O buffer is handled by
the C library allocator. The Python memory manager is involved only
in the allocation of the string object returned as a result.

<P>
In most situations, however, it is recommended to allocate memory from
the Python heap specifically because the latter is under control of
the Python memory manager. For example, this is required when the
interpreter is extended with new object types written in C. Another
reason for using the Python heap is the desire to <em>inform</em> the
Python memory manager about the memory needs of the extension module.
Even when the requested memory is used exclusively for internal,
highly-specific purposes, delegating all memory requests to the Python
memory manager causes the interpreter to have a more accurate image of
its memory footprint as a whole. Consequently, under certain
circumstances, the Python memory manager may or may not trigger
appropriate actions, like garbage collection, memory compaction or
other preventive procedures. Note that by using the C library
allocator as shown in the previous example, the allocated memory for
the I/O buffer escapes completely the Python memory manager.

<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="9. Memory Management"
  href="memory.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="9. Memory Management"
  href="memory.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="9.2 Memory Interface"
  href="memoryInterface.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="memory.html">9. Memory Management</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="memory.html">9. Memory Management</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="memoryInterface.html">9.2 Memory Interface</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>