Memory Allocation

Dynamic memory allocation is mostly a non-issue in Python. Everything is anobject, and the reference counting system and garbage collector automaticallyreturn memory to the system when it is no longer being used.

When it comes to more low-level data buffers, Cython has special support for(multi-dimensional) arrays of simple types via NumPy, memory views or Python’sstdlib array type. They are full featured, garbage collected and much easierto work with than bare pointers in C, while still retaining the speed and statictyping benefits.See Working with Python arrays and Typed Memoryviews.

In some situations, however, these objects can still incur an unacceptableamount of overhead, which can then makes a case for doing manual memorymanagement in C.

Simple C values and structs (such as a local variable cdef double x) areusually allocated on the stack and passed by value, but for larger and morecomplicated objects (e.g. a dynamically-sized list of doubles), the memory mustbe manually requested and released. C provides the functions malloc(),realloc(), and free() for this purpose, which can be importedin cython from clibc.stdlib. Their signatures are:

  1. void* malloc(size_t size)
  2. void* realloc(void* ptr, size_t size)
  3. void free(void* ptr)

A very simple example of malloc usage is the following:




  1.  1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23





  1. import random
    from libc.stdlib cimport malloc, free

    def random_noise(int number=1):
        cdef int i
        # allocate number  sizeof(double) bytes of memory
        cdef double     my_array = <double > malloc(number  sizeof(double))
        if not my_array:
            raise MemoryError()

        try:
            ran = random.normalvariate
            for i in range(number):
                my_array[i] = ran(0, 1)

            # … let's just assume we do some more heavy C calculations here to make up
            # for the work that it takes to pack the C double values into Python float
            # objects below, right after throwing away the existing objects above.

            return [x for x in my_array[:number]]
        finally:
            # return the previously allocated memory to the system
            free(my_array)


Note that the C-API functions for allocating memory on the Python heapare generally preferred over the low-level C functions above as thememory they provide is actually accounted for in Python’s internalmemory management system. They also have special optimisations forsmaller memory blocks, which speeds up their allocation by avoidingcostly operating system calls.

The C-API functions can be found in the cpython.mem standarddeclarations file:

  1. from cpython.mem cimport PyMem_Malloc, PyMem_Realloc, PyMem_Free

Their interface and usage is identical to that of the correspondinglow-level C functions.

One important thing to remember is that blocks of memory obtained withmalloc() or PyMem_Malloc() must be manually releasedwith a corresponding call to free() or PyMem_Free()when they are no longer used (and must always use the matchingtype of free function). Otherwise, they won’t be reclaimed until thepython process exits. This is called a memory leak.

If a chunk of memory needs a larger lifetime than can be managed by atry..finally block, another helpful idiom is to tie its lifetimeto a Python object to leverage the Python runtime’s memory management,e.g.:

  1. from cpython.mem cimport PyMem_Malloc, PyMem_Realloc, PyMem_Free
  2.  
  3. cdef class SomeMemory:
  4.  
  5.     cdef double* data
  6.  
  7.     def __cinit__(self, size_t number):
  8.         # allocate some memory (uninitialised, may contain arbitrary data)
  9.         self.data = <double*> PyMem_Malloc(number * sizeof(double))
  10.         if not self.data:
  11.             raise MemoryError()
  12.  
  13.     def resize(self, size_t new_number):
  14.         # Allocates new_number * sizeof(double) bytes,
  15.         # preserving the current content and making a best-effort to
  16.         # re-use the original data location.
  17.         mem = <double*> PyMem_Realloc(self.data, new_number * sizeof(double))
  18.         if not mem:
  19.             raise MemoryError()
  20.         # Only overwrite the pointer if the memory was really reallocated.
  21.         # On error (mem is NULL), the originally memory has not been freed.
  22.         self.data = mem
  23.  
  24.     def __dealloc__(self):
  25.         PyMem_Free(self.data)  # no-op if self.data is NULL