## gskmempool

gskmempool — pooling memory allocators.

## Synopsis

    #define             GSK_MEM_POOL_FIXED_STATIC_INIT      (size)
    #define             GSK_MEM_POOL_STATIC_INIT
                        GskMemPool;
                        GskMemPoolFixed;
    void                gsk_mem_pool_construct              (GskMemPool *pool);
    void                gsk_mem_pool_construct_with_scratch_buf
                                                            (GskMemPool *pool,
                                                             gpointer buffer,
                                                             gsize buffer_size);
    gpointer            gsk_mem_pool_alloc                  (GskMemPool *pool,
                                                             gsize size);
    gpointer            gsk_mem_pool_alloc0                 (GskMemPool *pool,
                                                             gsize size);
    char *              gsk_mem_pool_strdup                 (GskMemPool *pool,
                                                             const char *str);
    void                gsk_mem_pool_destruct               (GskMemPool *pool);
    void                gsk_mem_pool_fixed_construct        (GskMemPoolFixed *pool,
                                                             gsize size);
    gpointer            gsk_mem_pool_fixed_alloc            (GskMemPoolFixed *pool);
    gpointer            gsk_mem_pool_fixed_alloc0           (GskMemPoolFixed *pool);
    void                gsk_mem_pool_fixed_free             (GskMemPoolFixed *pool,
                                                             gpointer from_pool);
    void                gsk_mem_pool_fixed_destruct         (GskMemPoolFixed *pool);

## Description

GSK provides two pooling memory allocators. The first allocator is allocate-only, and can allocate blocks of variable size. The second allocator is alloc-and-free, but must allocate blocks of a fixed-size, which must be chosen when you construct the pool.

Both of these classes use the global allocator (g_new and g_free) as their underlying store.

These may only be accessed by one thread at a time: you should make sure to have a mutex to lock if multiple threads have access to the same mempool. I suspect the majority of use cases already must be mutex-protected for other reasons, but stronger evidence is welcome.

## Details

### GSK_MEM_POOL_FIXED_STATIC_INIT()

    #define             GSK_MEM_POOL_FIXED_STATIC_INIT(size)

Initialize a fixed-length static mem-pool member-wise given its elements' size.

Example:

    static GskMemPoolFixed request_pool = GSK_MEM_POOL_FIXED_STATIC_INIT(sizeof (Request));
    ...
    Request *request = gsk_mem_pool_fixed_alloc (&request_pool);
    ...
    gsk_mem_pool_fixed_free (request);

`size` : | the size of the mem-pool's elements.

### GSK_MEM_POOL_STATIC_INIT

    #define             GSK_MEM_POOL_STATIC_INIT

Initialize a fixed-length static mem-pool member-wise.

Example:

    void foo ()
    {
      GskMemPool mem_pool = GSK_MEM_POOL_STATIC_INIT;
      void *garbage = gsk_mem_pool_alloc (&mem_pool, 20);
      ...
      gsk_mem_pool_destruct (&mem_pool);
    }

### GskMemPool

    typedef struct {
    } GskMemPool;

A memory pool. It should be created on the stack or inside another object.

### GskMemPoolFixed

    typedef struct {
    } GskMemPoolFixed;

A fixed-size memory pool. It should be created on the stack or inside another object.

### gsk_mem_pool_construct ()

    void                gsk_mem_pool_construct              (GskMemPool *pool);

Initialize the members of a mem-pool. (The memory for the mem-pool structure itself must be provided: either as a part of another structure or on the stack.)

`pool` : | the mem-pool to initialize.

### gsk_mem_pool_construct_with_scratch_buf ()

    void                gsk_mem_pool_construct_with_scratch_buf
                                                            (GskMemPool *pool,
                                                             gpointer buffer,
                                                             gsize buffer_size);

Initialize the members of a mem-pool, using a scratch-buffer that the user provides. (The caller is responsible for ensuring that the buffer exists long enough)

`pool` : | the mem-pool to initialize.
`buffer` : | the buffer to use.
`buffer_size` : | the number of bytes in buffer to use as storage.

### gsk_mem_pool_alloc ()

    gpointer            gsk_mem_pool_alloc                  (GskMemPool *pool,
                                                             gsize size);

Allocate memory from a pool, This function terminates the program if there is an out-of-memory condition.

`pool` : | area to allocate memory from.
`size` : | number of bytes to allocate.
Returns : | the slab of memory allocated from the pool.

### gsk_mem_pool_alloc0 ()

    gpointer            gsk_mem_pool_alloc0                 (GskMemPool *pool,
                                                             gsize size);

Allocate memory from a pool, and initializes it to 0. This function terminates the program if there is an out-of-memory condition.

`pool` : | area to allocate memory from.
`size` : | number of bytes to allocate.
Returns : | the slab of memory allocated from the pool.

### gsk_mem_pool_strdup ()

    char *              gsk_mem_pool_strdup                 (GskMemPool *pool,
                                                             const char *str);

Allocated space from the mem-pool to store the given string (including its terminal NUL character) and copy the string onto that buffer.

If `str` is NULL, then NULL is returned.

`pool` : | area to allocate memory from.
`str` : | a string to duplicate, or NULL.
Returns : | a copy of `str`, allocated from `pool`.

### gsk_mem_pool_destruct ()

    void                gsk_mem_pool_destruct               (GskMemPool *pool);

Destroy all chunk associated with the given mem-pool.

`pool` : | the pool to destroy.

### gsk_mem_pool_fixed_construct ()

    void                gsk_mem_pool_fixed_construct        (GskMemPoolFixed *pool,
                                                             gsize size);

Set up a fixed-size memory allocator for use.

`pool` : | the fixed-size memory pool to construct.
`size` : | size of the allocation to take from the mem-pool.

### gsk_mem_pool_fixed_alloc ()

    gpointer            gsk_mem_pool_fixed_alloc            (GskMemPoolFixed *pool);

Allocate a block of the Fixed-Pool's size.

`pool` : | the pool to allocate a block from.
Returns : | the allocated memory.

### gsk_mem_pool_fixed_alloc0 ()

    gpointer            gsk_mem_pool_fixed_alloc0           (GskMemPoolFixed *pool);

Allocate a block of the Fixed-Pool's size. Set its contents to 0.

`pool` : | the pool to allocate a block from.
Returns : | the allocated, zeroed memory.

### gsk_mem_pool_fixed_free ()

    void                gsk_mem_pool_fixed_free             (GskMemPoolFixed *pool,
                                                             gpointer from_pool);

Recycle some of the pool's memory back to it.

`pool` : | the pool to return memory to.
`from_pool` : | the memory to return to this pool. It must have been allocated from this pool.

### gsk_mem_pool_fixed_destruct ()

    void                gsk_mem_pool_fixed_destruct         (GskMemPoolFixed *pool);

Free all memory associated with this pool.

`pool` : | the pool to destroy.