1cdef extern from "Python.h":
2
3    #####################################################################
4    # 9.2 Memory Interface
5    #####################################################################
6    # You are definitely *supposed* to use these: "In most situations,
7    # however, it is recommended to allocate memory from the Python
8    # heap specifically because the latter is under control of the
9    # Python memory manager. For example, this is required when the
10    # interpreter is extended with new object types written in
11    # C. Another reason for using the Python heap is the desire to
12    # inform the Python memory manager about the memory needs of the
13    # extension module. Even when the requested memory is used
14    # exclusively for internal, highly-specific purposes, delegating
15    # all memory requests to the Python memory manager causes the
16    # interpreter to have a more accurate image of its memory
17    # footprint as a whole. Consequently, under certain circumstances,
18    # the Python memory manager may or may not trigger appropriate
19    # actions, like garbage collection, memory compaction or other
20    # preventive procedures. Note that by using the C library
21    # allocator as shown in the previous example, the allocated memory
22    # for the I/O buffer escapes completely the Python memory
23    # manager."
24
25    # The following function sets, modeled after the ANSI C standard,
26    # but specifying behavior when requesting zero bytes, are
27    # available for allocating and releasing memory from the Python
28    # heap:
29
30    void* PyMem_Malloc(size_t n)
31    # Allocates n bytes and returns a pointer of type void* to the
32    # allocated memory, or NULL if the request fails. Requesting zero
33    # bytes returns a distinct non-NULL pointer if possible, as if
34    # PyMem_Malloc(1) had been called instead. The memory will not
35    # have been initialized in any way.
36
37    void* PyMem_Realloc(void *p, size_t n)
38    # Resizes the memory block pointed to by p to n bytes. The
39    # contents will be unchanged to the minimum of the old and the new
40    # sizes. If p is NULL, the call is equivalent to PyMem_Malloc(n);
41    # else if n is equal to zero, the memory block is resized but is
42    # not freed, and the returned pointer is non-NULL. Unless p is
43    # NULL, it must have been returned by a previous call to
44    # PyMem_Malloc() or PyMem_Realloc().
45
46    void PyMem_Free(void *p)
47    # Frees the memory block pointed to by p, which must have been
48    # returned by a previous call to PyMem_Malloc() or
49    # PyMem_Realloc(). Otherwise, or if PyMem_Free(p) has been called
50    # before, undefined behavior occurs. If p is NULL, no operation is
51    # performed.
52
53    # The following type-oriented macros are provided for
54    # convenience. Note that TYPE refers to any C type.
55
56    # TYPE* PyMem_New(TYPE, size_t n)
57    # Same as PyMem_Malloc(), but allocates (n * sizeof(TYPE)) bytes
58    # of memory. Returns a pointer cast to TYPE*. The memory will not
59    # have been initialized in any way.
60
61    # TYPE* PyMem_Resize(void *p, TYPE, size_t n)
62    # Same as PyMem_Realloc(), but the memory block is resized to (n *
63    # sizeof(TYPE)) bytes. Returns a pointer cast to TYPE*.
64
65    void PyMem_Del(void *p)
66    # Same as PyMem_Free().
67
68    # In addition, the following macro sets are provided for calling
69    # the Python memory allocator directly, without involving the C
70    # API functions listed above. However, note that their use does
71    # not preserve binary compatibility across Python versions and is
72    # therefore deprecated in extension modules.
73
74    # PyMem_MALLOC(), PyMem_REALLOC(), PyMem_FREE().
75    # PyMem_NEW(), PyMem_RESIZE(), PyMem_DEL().
76