third_party/cython/src/Cython/Includes/cpython/mem.pxd

   1 cdef 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().