Doc/api/memory.tex

   1 \chapter{Memory Management \label{memory}}
   2 \sectionauthor{Vladimir Marangozov}{Vladimir.Marangozov@inrialpes.fr}
   3
   4
   5 \section{Overview \label{memoryOverview}}
   6
   7 Memory management in Python involves a private heap containing all
   8 Python objects and data structures. The management of this private
   9 heap is ensured internally by the \emph{Python memory manager}.  The
  10 Python memory manager has different components which deal with various
  11 dynamic storage management aspects, like sharing, segmentation,
  12 preallocation or caching.
  13
  14 At the lowest level, a raw memory allocator ensures that there is
  15 enough room in the private heap for storing all Python-related data
  16 by interacting with the memory manager of the operating system. On top
  17 of the raw memory allocator, several object-specific allocators
  18 operate on the same heap and implement distinct memory management
  19 policies adapted to the peculiarities of every object type. For
  20 example, integer objects are managed differently within the heap than
  21 strings, tuples or dictionaries because integers imply different
  22 storage requirements and speed/space tradeoffs. The Python memory
  23 manager thus delegates some of the work to the object-specific
  24 allocators, but ensures that the latter operate within the bounds of
  25 the private heap.
  26
  27 It is important to understand that the management of the Python heap
  28 is performed by the interpreter itself and that the user has no
  29 control over it, even if she regularly manipulates object pointers to
  30 memory blocks inside that heap.  The allocation of heap space for
  31 Python objects and other internal buffers is performed on demand by
  32 the Python memory manager through the Python/C API functions listed in
  33 this document.
  34
  35 To avoid memory corruption, extension writers should never try to
  36 operate on Python objects with the functions exported by the C
  37 library: \cfunction{malloc()}\ttindex{malloc()},
  38 \cfunction{calloc()}\ttindex{calloc()},
  39 \cfunction{realloc()}\ttindex{realloc()} and
  40 \cfunction{free()}\ttindex{free()}.  This will result in
  41 mixed calls between the C allocator and the Python memory manager
  42 with fatal consequences, because they implement different algorithms
  43 and operate on different heaps.  However, one may safely allocate and
  44 release memory blocks with the C library allocator for individual
  45 purposes, as shown in the following example:
  46
  47 \begin{verbatim}
  48     PyObject *res;
  49     char *buf = (char *) malloc(BUFSIZ); /* for I/O */
  50
  51     if (buf == NULL)
  52         return PyErr_NoMemory();
  53     ...Do some I/O operation involving buf...
  54     res = PyString_FromString(buf);
  55     free(buf); /* malloc'ed */
  56     return res;
  57 \end{verbatim}
  58
  59 In this example, the memory request for the I/O buffer is handled by
  60 the C library allocator. The Python memory manager is involved only
  61 in the allocation of the string object returned as a result.
  62
  63 In most situations, however, it is recommended to allocate memory from
  64 the Python heap specifically because the latter is under control of
  65 the Python memory manager. For example, this is required when the
  66 interpreter is extended with new object types written in C. Another
  67 reason for using the Python heap is the desire to \emph{inform} the
  68 Python memory manager about the memory needs of the extension module.
  69 Even when the requested memory is used exclusively for internal,
  70 highly-specific purposes, delegating all memory requests to the Python
  71 memory manager causes the interpreter to have a more accurate image of
  72 its memory footprint as a whole. Consequently, under certain
  73 circumstances, the Python memory manager may or may not trigger
  74 appropriate actions, like garbage collection, memory compaction or
  75 other preventive procedures. Note that by using the C library
  76 allocator as shown in the previous example, the allocated memory for
  77 the I/O buffer escapes completely the Python memory manager.
  78
  79
  80 \section{Memory Interface \label{memoryInterface}}
  81
  82 The following function sets, modeled after the ANSI C standard,
  83 but specifying  behavior when requesting zero bytes,
  84 are available for allocating and releasing memory from the Python heap:
  85
  86
  87 \begin{cfuncdesc}{void*}{PyMem_Malloc}{size_t n}
  88   Allocates \var{n} bytes and returns a pointer of type \ctype{void*}
  89   to the allocated memory, or \NULL{} if the request fails.
  90   Requesting zero bytes returns a distinct non-\NULL{} pointer if
  91   possible, as if \cfunction{PyMem_Malloc(1)} had been called instead.
  92   The memory will not have been initialized in any way.
  93 \end{cfuncdesc}
  94
  95 \begin{cfuncdesc}{void*}{PyMem_Realloc}{void *p, size_t n}
  96   Resizes the memory block pointed to by \var{p} to \var{n} bytes.
  97   The contents will be unchanged to the minimum of the old and the new
  98   sizes. If \var{p} is \NULL, the call is equivalent to
  99   \cfunction{PyMem_Malloc(\var{n})}; else if \var{n} is equal to zero, the
 100   memory block is resized but is not freed, and the returned pointer
 101   is non-\NULL.  Unless \var{p} is \NULL, it must have been
 102   returned by a previous call to \cfunction{PyMem_Malloc()} or
 103   \cfunction{PyMem_Realloc()}.
 104 \end{cfuncdesc}
 105
 106 \begin{cfuncdesc}{void}{PyMem_Free}{void *p}
 107   Frees the memory block pointed to by \var{p}, which must have been
 108   returned by a previous call to \cfunction{PyMem_Malloc()} or
 109   \cfunction{PyMem_Realloc()}.  Otherwise, or if
 110   \cfunction{PyMem_Free(p)} has been called before, undefined
 111   behavior occurs. If \var{p} is \NULL, no operation is performed.
 112 \end{cfuncdesc}
 113
 114 The following type-oriented macros are provided for convenience.  Note
 115 that \var{TYPE} refers to any C type.
 116
 117 \begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n}
 118   Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} *
 119   sizeof(\var{TYPE}))} bytes of memory.  Returns a pointer cast to
 120   \ctype{\var{TYPE}*}.  The memory will not have been initialized in
 121   any way.
 122 \end{cfuncdesc}
 123
 124 \begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n}
 125   Same as \cfunction{PyMem_Realloc()}, but the memory block is resized
 126   to \code{(\var{n} * sizeof(\var{TYPE}))} bytes.  Returns a pointer
 127   cast to \ctype{\var{TYPE}*}.
 128 \end{cfuncdesc}
 129
 130 \begin{cfuncdesc}{void}{PyMem_Del}{void *p}
 131   Same as \cfunction{PyMem_Free()}.
 132 \end{cfuncdesc}
 133
 134 In addition, the following macro sets are provided for calling the
 135 Python memory allocator directly, without involving the C API functions
 136 listed above. However, note that their use does not preserve binary
 137 compatibility accross Python versions and is therefore deprecated in
 138 extension modules.
 139
 140 \cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}.
 141
 142 \cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}.
 143
 144
 145 \section{Examples \label{memoryExamples}}
 146
 147 Here is the example from section \ref{memoryOverview}, rewritten so
 148 that the I/O buffer is allocated from the Python heap by using the
 149 first function set:
 150
 151 \begin{verbatim}
 152     PyObject *res;
 153     char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
 154
 155     if (buf == NULL)
 156         return PyErr_NoMemory();
 157     /* ...Do some I/O operation involving buf... */
 158     res = PyString_FromString(buf);
 159     PyMem_Free(buf); /* allocated with PyMem_Malloc */
 160     return res;
 161 \end{verbatim}
 162
 163 The same code using the type-oriented function set:
 164
 165 \begin{verbatim}
 166     PyObject *res;
 167     char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
 168
 169     if (buf == NULL)
 170         return PyErr_NoMemory();
 171     /* ...Do some I/O operation involving buf... */
 172     res = PyString_FromString(buf);
 173     PyMem_Del(buf); /* allocated with PyMem_New */
 174     return res;
 175 \end{verbatim}
 176
 177 Note that in the two examples above, the buffer is always
 178 manipulated via functions belonging to the same set. Indeed, it
 179 is required to use the same memory API family for a given
 180 memory block, so that the risk of mixing different allocators is
 181 reduced to a minimum. The following code sequence contains two errors,
 182 one of which is labeled as \emph{fatal} because it mixes two different
 183 allocators operating on different heaps.
 184
 185 \begin{verbatim}
 186 char *buf1 = PyMem_New(char, BUFSIZ);
 187 char *buf2 = (char *) malloc(BUFSIZ);
 188 char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
 189 ...
 190 PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
 191 free(buf2);       /* Right -- allocated via malloc() */
 192 free(buf1);       /* Fatal -- should be PyMem_Del()  */
 193 \end{verbatim}
 194
 195 In addition to the functions aimed at handling raw memory blocks from
 196 the Python heap, objects in Python are allocated and released with
 197 \cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and
 198 \cfunction{PyObject_Del()}, or with their corresponding macros
 199 \cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and
 200 \cfunction{PyObject_DEL()}.
 201
 202 These will be explained in the next chapter on defining and
 203 implementing new object types in C.