Memory Allocation

Note

This page uses two different syntax variants:

  • Cython specificcdef syntax, which was designed to make type declarationsconcise and easily readable from a C/C++ perspective.

  • Pure Python syntax which allows static Cython type declarations inpure Python code,followingPEP-484 type hintsandPEP 526 variable annotations.

    To make use of C data types in Python syntax, you need to import the specialcython module in the Python module that you want to compile, e.g.

    importcython

    If you use the pure Python syntax we strongly recommend you use a recentCython 3 release, since significant improvements have been made herecompared to the 0.29.x releases.

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.SeeWorking with Python arrays andTyped 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 variablecdefdoublex /x:cython.double) areusuallyallocated on the stack and passed by value, but for larger and morecomplicated objects (e.g. a dynamically-sized list of doubles), the memory mustbemanually requested and released. C provides the functionsmalloc(),realloc(), andfree() for this purpose, which can be importedin cython fromclibc.stdlib. Their signatures are:

void*malloc(size_tsize)void*realloc(void*ptr,size_tsize)voidfree(void*ptr)

A very simple example of malloc usage is the following:

importrandomfromcython.cimports.libc.stdlibimportmalloc,freedefrandom_noise(number:cython.int=1):i:cython.int# allocate number * sizeof(double) bytes of memorymy_array:cython.p_double=cython.cast(cython.p_double,malloc(number*cython.sizeof(cython.double)))ifnotmy_array:raiseMemoryError()try:ran=random.normalvariateforiinrange(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[xforxinmy_array[:number]]finally:# return the previously allocated memory to the systemfree(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 thecpython.mem standarddeclarations file:

fromcython.cimports.cpython.memimportPyMem_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() orPyMem_Malloc()must be manually releasedwith a corresponding call tofree() orPyMem_Free()when they are no longer used (andmust 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.:

fromcython.cimports.cpython.memimportPyMem_Malloc,PyMem_Realloc,PyMem_Free@cython.cclassclassSomeMemory:data:cython.p_doubledef__cinit__(self,number:cython.size_t):# allocate some memory (uninitialised, may contain arbitrary data)self.data=cython.cast(cython.p_double,PyMem_Malloc(number*cython.sizeof(cython.double)))ifnotself.data:raiseMemoryError()defresize(self,new_number:cython.size_t):# Allocates new_number * sizeof(double) bytes,# preserving the current content and making a best-effort to# reuse the original data location.mem=cython.cast(cython.p_double,PyMem_Realloc(self.data,new_number*cython.sizeof(cython.double)))ifnotmem:raiseMemoryError()# Only overwrite the pointer if the memory was really reallocated.# On error (mem is NULL), the originally memory has not been freed.self.data=memdef__dealloc__(self):PyMem_Free(self.data)# no-op if self.data is NULL