Previous design¶

Historically there have been two image allocators in Pillow:ImagingAllocateBlock andImagingAllocateArray. The first worksfor images smaller than 16MB of data and allocates one large chunk ofmemory ofim->linesize*im->ysize bytes. The second works forlarge images and makes one allocation for each scan line of sizeim->linesize bytes. This makes for a very sharp transitionbetween one allocation and potentially thousands of small allocations,leading to unpredictable performance penalties around the transition.

New design¶

ImagingAllocateArray now allocates space for images as a chain ofblocks with a maximum size of 16MB. If there is a memory allocationerror, it falls back to allocating a 4KB block, or at least one scanline. This is now the default for all internal allocations.

ImagingAllocateBlock is now only used for those cases when we arespecifically requesting a single segment of memory for sharing withother code.

Memory pools¶

There is now a memory pool to contain a supply of recently freedblocks, which can then be reused without going back to the OS for afresh allocation. This caching of free blocks is currently disabled bydefault, but can be enabled and tweaked using three environmentvariables:

• PILLOW_ALIGNMENT, in bytes. Specifies the alignment of memoryallocations. Valid values are powers of 2 between 1 and128, inclusive. Defaults to 1.

• PILLOW_BLOCK_SIZE, in bytes, K, or M. Specifies the maximumblock size forImagingAllocateArray. Valid values areintegers, with an optionalk orm suffix. Defaults to 16M.

• PILLOW_BLOCKS_MAX Specifies the number of freed blocks toretain to fill future memory requests. Any freed blocks over thisthreshold will be returned to the OS immediately. Defaults to 0.