Mercurial > cpython-lru_cache-weakref

annotate Doc/api/memory.tex @ 24042:63fbbed10714 legacy-trunk

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