Mercurial > cpython-lru_cache-weakref

annotate Doc/api/memory.tex @ 25838:8540887bcec6 2.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Backport of 2.183: Fix memory leak in add_subclass() found by NealN with valgrind.
author Guido van Rossum <guido@python.org>
date Fri, 18 Oct 2002 13:42:21 +0000
parents 946bebd00132
children f9236cad69e6
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
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 control on it, even if she regularly manipulates object pointers to
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
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 The following function sets, modeled after the ANSI C standard, are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83 available for allocating and releasing memory from 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
84
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 \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
87 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
88 to the allocated memory, or \NULL{} if the request fails.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 Requesting zero bytes returns a non-\NULL{} pointer.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90 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
91 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
92
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93 \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
94 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
95 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
96 sizes. If \var{p} is \NULL, the call is equivalent to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
97 \cfunction{PyMem_Malloc(\var{n})}; if \var{n} is equal to zero, the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98 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
99 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
100 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
101 \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
102 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104 \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
105 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
106 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
107 \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
108 \cfunction{PyMem_Free(p)} has been called before, undefined
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 behaviour occurs. If \var{p} is \NULL, no operation is performed.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112 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
113 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
114
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 \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
116 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
117 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
118 \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
119 any way.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 \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
123 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
124 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
125 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
126 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128 \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
129 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
130 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
132 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
133 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
134 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
135 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
136 extension modules.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
137
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
138 \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
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_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
141
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
142
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
143 \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
144
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
145 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
146 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
147 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
148
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
149 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
150 PyObject *res;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
151 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
152
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153 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
154 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
155 /* ...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
156 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
157 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
158 return res;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
159 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
160
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
161 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
162
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
163 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164 PyObject *res;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165 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
166
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167 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
168 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
169 /* ...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
170 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
171 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
172 return res;
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 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
176 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
177 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
178 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
179 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
180 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
181 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
182
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
183 \begin{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
184 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
185 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
186 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
187 ...
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 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
189 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
190 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
191 \end{verbatim}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
192
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
193 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
194 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
195 \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
196 \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
197 \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
198 \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
199
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual
Fred Drake <fdrake@acm.org>
parents:
diff changeset
200 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
201 implementing new object types in C.