bpo-20064: Document PyObject_Malloc() (#4204) · python/cpython@52ba7b4 (original) (raw)
`@@ -155,6 +155,88 @@ versions and is therefore deprecated in extension modules.
`
155
155
`` :c:func:PyMem_NEW, :c:func:PyMem_RESIZE, :c:func:PyMem_DEL.
``
156
156
``
157
157
``
``
158
`+
Object allocators
`
``
159
`+
=================
`
``
160
+
``
161
`+
The following function sets, modeled after the ANSI C standard, but specifying
`
``
162
`+
behavior when requesting zero bytes, are available for allocating and releasing
`
``
163
`+
memory from the Python heap.
`
``
164
+
``
165
`` +
By default, these functions use :ref:pymalloc memory allocator <pymalloc>.
``
``
166
+
``
167
`+
.. warning::
`
``
168
+
``
169
`` +
The :term:GIL <global interpreter lock> must be held when using these
``
``
170
`+
functions.
`
``
171
+
``
172
`+
.. c:function:: void* PyObject_Malloc(size_t n)
`
``
173
+
``
174
`` +
Allocates n bytes and returns a pointer of type :c:type:void\* to the
``
``
175
`+
allocated memory, or NULL if the request fails.
`
``
176
+
``
177
`+
Requesting zero bytes returns a distinct non-NULL pointer if possible, as
`
``
178
if ``PyObject_Malloc(1)`` had been called instead. The memory will not have
``
179
`+
been initialized in any way.
`
``
180
+
``
181
+
``
182
`+
.. c:function:: void* PyObject_Realloc(void *p, size_t n)
`
``
183
+
``
184
`+
Resizes the memory block pointed to by p to n bytes. The contents will be
`
``
185
`+
unchanged to the minimum of the old and the new sizes.
`
``
186
+
``
187
If *p* is *NULL*, the call is equivalent to ``PyObject_Malloc(n)``; else if *n*
``
188
`+
is equal to zero, the memory block is resized but is not freed, and the
`
``
189
`+
returned pointer is non-NULL.
`
``
190
+
``
191
`+
Unless p is NULL, it must have been returned by a previous call to
`
``
192
`` +
:c:func:PyObject_Malloc, :c:func:PyObject_Realloc or :c:func:PyObject_Calloc.
``
``
193
+
``
194
`` +
If the request fails, :c:func:PyObject_Realloc returns NULL and p remains
``
``
195
`+
a valid pointer to the previous memory area.
`
``
196
+
``
197
+
``
198
`+
.. c:function:: void PyObject_Free(void *p)
`
``
199
+
``
200
`+
Frees the memory block pointed to by p, which must have been returned by a
`
``
201
`` +
previous call to :c:func:PyObject_Malloc, :c:func:PyObject_Realloc or
``
``
202
:c:func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been called
``
203
`+
before, undefined behavior occurs.
`
``
204
+
``
205
`+
If p is NULL, no operation is performed.
`
``
206
+
``
207
+
``
208
`+
In addition, the following macro sets are provided:
`
``
209
+
``
210
`` +
- :c:func:
PyObject_MALLOC: alias to :c:func:PyObject_Malloc
``
``
211
`` +
- :c:func:
PyObject_REALLOC: alias to :c:func:PyObject_Realloc
``
``
212
`` +
- :c:func:
PyObject_FREE: alias to :c:func:PyObject_Free
``
``
213
`` +
- :c:func:
PyObject_Del: alias to :c:func:PyObject_Free
``
``
214
`` +
- :c:func:
PyObject_DEL: alias to :c:func:PyObject_FREE(so finally an alias
``
``
215
`` +
to :c:func:PyObject_Free)
``
``
216
+
``
217
+
``
218
`+
.. _pymalloc:
`
``
219
+
``
220
`+
The pymalloc allocator
`
``
221
`+
======================
`
``
222
+
``
223
`+
Python has a pymalloc allocator optimized for small objects (smaller or equal
`
``
224
`+
to 512 bytes) with a short lifetime. It uses memory mappings called "arenas"
`
``
225
`` +
with a fixed size of 256 KiB. It falls back to :c:func:malloc and
``
``
226
`` +
:c:func:realloc for allocations larger than 512 bytes.
``
``
227
+
``
228
`` +
pymalloc is the default allocator of :c:func:PyObject_Malloc.
``
``
229
+
``
230
`+
The arena allocator uses the following functions:
`
``
231
+
``
232
`` +
- :c:func:
mmapand :c:func:munmapif available,
``
``
233
`` +
- :c:func:
mallocand :c:func:freeotherwise.
``
``
234
+
``
235
`+
.. versionchanged:: 2.7.7
`
``
236
`+
The threshold changed from 256 to 512 bytes. The arena allocator now
`
``
237
`` +
uses :c:func:mmap if available.
``
``
238
+
``
239
+
158
240
`.. _memoryexamples:
`
159
241
``
160
242
`Examples
`