StackThreads/MP: version 0.77 User's Guide

4.2.1: Region Basics

        #include <ralloc.h>
@        st_region_t st_make_region(void);
@        void * st_region_malloc(sz, rg);
@        void st_reset_region(rg);
@        void st_abandon_region(rg);
@                st_region_t rg;
@                unsigned sz;

ralloc.h is located at a place stgcc automatically searches. st_make_region() creates a new region. st_region_malloc(sz, rg) allocates sz bytes of memory from region rg. st_reset_region(rg) resets region rg. That is, it makes all blocks allocated in region rg reusable for subsequent requests with st_region_malloc(..., rg). st_abandon_region(rg) is similar to st_reset_region(rg), but it abandons all blocks associated with rg; it gives them back to the underlying memory allocator.

A region abstracts objects' death point. The basic observation is that objects allocated during a course of computation often die together. Such objects can be allocated from a single region and then freed all at once. This saves time for memory management and avoids fragmentation without a general and sophisticated mechanism.

A region internally keeps as many free lists as the number of workers. Each worker has its own private free list. Each free list is a list of fixed-sized chunks. A single chunk is, by default, 7KB. Associated with a free list are the current chunk pointer (C), which points to the chunk from which allocations are served, the current chunk limit pointer (L), which points to the end of the current chunk, and the allocation pointer (A), which points to a point in the current chunk from which the next allocation will be served. An allocation simply checks if A + the requested size exceeds L, and if it does not, it returns A and advances it by the requested size. Otherwise, the allocation goes on to the next chunk, changing C, L, and A appropriately. When a worker runs out of its private free list, it calls the underlying memory allocator to obtain a new chunk. No attempts are made to obtain one from another worker's free list.

st_reset_region(rg) simply resets its current chunk pointer to the first chunk of the free list and sets other pointers accordingly. It does not give chunks to the underlying allocator. It is st_abandon_region(rg) that does this.