API

group stackpool

Public function definitions and types for Yc’s stack pools.

Defines

YC_ENABLE_ALLOC_ACCOUNTING

A define that is non-zero when allocators should include accounting code.

Typedefs

typedef struct y_stackpool *y_StackPool

The public type for the stack pool.

typedef bool (*y_StackPoolOverflowHandler)(y_StackPool p)

A function to call when a stackpool cannot allocate memory for setting jump markers, entering scopes, or entering functions.

Param p:

The stackpool.

Return:

True if the error was handled, false otherwise.

Pre:

p must not be NULL.

Functions

void y_stackpool_enterScope(y_StackPool p)

Marks the start of a scope in the stack pool.

This is meant to be used when a new scope is opened. If there was any error when pushing the scope onto the stackpool, the stackpool overflow context stack is searched for a handler that will handle the error.

Parameters:

p – The stack pool.

Pre:

p must not be NULL.

void y_stackpool_exitScope(y_StackPool p)

Deallocates all allocations that have been allocated since the start of the current scope.

This is meant to be used on exit from a scope.

Parameters:

p – The stack pool.

Pre:

p must not be NULL.

void y_stackpool_exitScopes(y_StackPool p, size_t n)

Deallocates all allocations that have been allocated since the start of the current n scopes.

This is meant to be used on exit from a scope.

Parameters:
  • p – The stack pool.

  • n – The number of scopes to deallocate allocations for.

Pre:

p must not be NULL.

void y_stackpool_enterFunc(y_StackPool p, const char *func)

Marks the start of a function in the stack pool.

This is meant to be used when a new function is opened. If there was any error when pushing the function onto the stackpool, the stackpool overflow context stack is searched for a handler that will handle the error.

Parameters:
  • p – The stack pool.

  • func – The function name.

Pre:

p must not be NULL.

Pre:

func must not be NULL.

void y_stackpool_exitFunc(y_StackPool p)

Deallocates all allocations that have been allocated since the start of the current function.

This is meant to be used on exit from a function.

Parameters:

p – The stack pool.

Pre:

p must not be NULL.

y_Status y_stackpool_printStack(y_StackPool p, y_File f)

Prints a stacktrace.

Parameters:
  • p – The stackpool that has the stack trace of functions.

  • f – The file to print to.

Returns:

An error code, if any.

Pre:

p must not be NULL.

Pre:

f must not be NULL.

void y_stackpool_setjmp(y_StackPool p, sigjmp_buf *buf)

Puts a longjmp() marker into the stack pool.

If there was any error when pushing the marker onto the stackpool, the stackpool overflow context stack is searched for a handler that will handle the error.

Parameters:
  • p – The stack pool.

  • buf – A sigjmp_buf to jump to when calling y_stackpool_jmp(). If no jump is desired, this can be NULL.

Pre:

p must not be NULL.

void y_stackpool_jmp(y_StackPool p, bool jmp)

Deallocates everything in the stack pool until a longjmp() marker is found.

Parameters:
  • p – The stack pool.

  • jmp – True if this function should jump, false otherwise. If this is true, a valid sigjmp_buf must have been given to the corresponding call to y_stackpool_setjmp().

Pre:

sa must not be NULL.

Pre:

There must be a longjmp() marker in the stack pool.

void *y_stackpool_malloc(y_StackPool p, size_t size, y_Destructor dtor)

Allocates at least size bytes in the stack pool and attaches the destructor at the dtor index to the allocation.

Parameters:
  • p – The stack pool.

  • size – The size to allocate.

  • dtor – The destructor to attach to the allocation. Can be NULL for no destructor.

Returns:

A pointer to the allocation.

Pre:

p must not be NULL.

Pre:

size must be greater than 0.

void *y_stackpool_calloc(y_StackPool p, size_t size, y_Destructor dtor)

Allocates and zeroes at least size bytes in the stack pool and attaches the destructor at the dtor index to the allocation.

Parameters:
  • p – The stack pool.

  • size – The size to allocate.

  • dtor – The destructor to attach to the allocation. Can be NULL for no destructor.

Returns:

A pointer to the allocation.

Pre:

p must not be NULL.

Pre:

size must be greater than 0.

void y_stackpool_free(y_StackPool p)

Deallocates the item on the top of the stack in the stack pool.

Parameters:

p – The stack pool.

Pre:

p must not be NULL.

group mappool

Public function definitions and types for Yc’s memory pool.

This is a byte vector hooked with a map that allows users to allocate memory and use any type as the key to get the pointer.

Typedefs

typedef struct y_mappool *y_MapPool

The public definition of a y_MapPool.

This is hidden behind a pointer.

Functions

y_MapPool y_mappool_create(float load, size_t ksize, y_Hasher hash, y_Equal eq, y_Destructor kdtor)

Creates a y_MapPool.

Params hash and cmp can be NULL, but if they are, keys are required to be the size of uint64_t’s because they will be used as the hash directly, as well as compared directly.

Parameters:
  • load – The load of the pool.

  • ksize – The key size.

  • hash – The hash function for the pool’s keys.

  • eq – The equality function for the pool’s keys.

  • kdtor – The key destructor, or NULL if unnecessary.

Returns:

A newly-created y_MapPool, or NULL on error.

Pre:

ksize must be greater than zero.

Pre:

If cmp is NULL, ksize must be sizeof(uint64_t).

Pre:

If hash is NULL, ksize must be sizeof(uint64_t).

Pre:

load must be between (0, 1].

y_MapPool y_mappool_createStringKeyMap(float load)

Creates a y_MapPool using strings as keys.

Parameters:

load – The load of the pool.

Returns:

A newly-created y_MapPool, or NULL on error.

Pre:

load must be between (0, 1].

size_t y_mappool_allocations(const y_MapPool p)

Returns the number of allocations in p.

Parameters:

p – The pool to query.

Returns:

The number of allocations in p.

Pre:

p must not be NULL.

bool y_mappool_exists(const y_MapPool p, const void *key)

Returns true if the key has already been used to allocate space, false otherwise.

Parameters:
  • p – The pool to query.

  • key – The key to query for.

Returns:

true if the key was used, false otherwise.

Pre:

p must not be NULL.

Pre:

key must not be NULL.

Pre:

The map must not have been created with y_mappool_createStringKey().

bool y_mappool_existsStringKey(const y_MapPool p, const char *key)

Returns true if the key has already been used to allocate space, false otherwise.

Parameters:
  • p – The pool to query.

  • key – The key to query for.

Returns:

true if the key was used, false otherwise.

Pre:

p must not be NULL.

Pre:

key must not be NULL.

Pre:

The map must have been created with y_mappool_createStringKey().

size_t y_mappool_size(const y_MapPool p, const void *key)

Returns the allocation size for the given key, or 0, if there is no allocation.

Parameters:
  • p – The pool to query.

  • key – The key to query for.

Returns:

The allocation size for key, or 0 if none.

Pre:

p must not be NULL.

Pre:

key must not be NULL.

Pre:

The map must not have been created with y_mappool_createStringKey().

size_t y_mappool_sizeStringKey(const y_MapPool p, const char *key)

Returns the allocation size for the given key, or 0, if there is no allocation.

Parameters:
  • p – The pool to query.

  • key – The key to query for.

Returns:

The allocation size for key, or 0 if none.

Pre:

p must not be NULL.

Pre:

key must not be NULL.

Pre:

The map must have been created with y_mappool_createStringKey().

void *y_mappool_get(const y_MapPool p, const void *key)

Returns the pointer for the given key, or NULL if it doesn’t exist.

Parameters:
  • p – The pool to query.

  • key – The key to query for.

Returns:

The pointer to the memory for the given key, or NULL if none.

Pre:

p must not be NULL.

Pre:

key must not be NULL.

Pre:

The map must not have been created with y_mappool_createStringKey().

void *y_mappool_getStringKey(const y_MapPool p, const char *key)

Returns the pointer for the given key, or NULL if it doesn’t exist.

Parameters:
  • p – The pool to query.

  • key – The key to query for.

Returns:

The pointer to the memory for the given key, or NULL if none.

Pre:

p must not be NULL.

Pre:

key must not be NULL.

Pre:

The map must have been created with y_mappool_createStringKey().

void *y_mappool_malloc(y_MapPool p, const void *key, size_t size, y_Destructor dtor)

Allocates space in the pool for the key and returns a pointer to the space, or NULL on error.

If the key has already been used, then the pointer to the space for the key is returned. In that case, if the size of the allocation does not match size, or the destructor does not match dtor, an assert is triggered.

Parameters:
  • p – The pool to allocate in.

  • key – The key to allocate at.

  • size – The amount of space to allocate.

  • dtor – The destructor for the allocation.

Returns:

The pointer to the space, whether newly-allocated or not.

Pre:

p must not be NULL.

Pre:

key must not be NULL.

Pre:

size must be greater than 0.

Pre:

If key was already used, size must match the size of the existing allocation, and dtor must match the destructor.

Pre:

The map must not have been created with y_mappool_createStringKey().

void *y_mappool_mallocStringKey(y_MapPool p, const char *key, size_t size, y_Destructor dtor)

Allocates space in the pool for the key and returns a pointer to the space, or NULL on error.

If the key has already been used, then the pointer to the space for the key is returned. In that case, if the size of the allocation does not match size, or the destructor does not match dtor, an assert is triggered.

Parameters:
  • p – The pool to allocate in.

  • key – The key to allocate at.

  • size – The amount of space to allocate.

  • dtor – The destructor for the allocation.

Returns:

The pointer to the space, whether newly-allocated or not.

Pre:

p must not be NULL.

Pre:

key must not be NULL.

Pre:

size must be greater than 0.

Pre:

If key was already used, size must match the size of the existing allocation, and dtor must match the destructor.

Pre:

The map must have been created with y_mappool_createStringKey().

void *y_mappool_calloc(y_MapPool p, const void *key, size_t size, y_Destructor dtor)

Allocates space in p for key and returns a pointer to the space, or NULL on error.

If key has already been used, then the pointer to the space for the key is returned. In that case, if the size of the allocation does not match size, or the destructor does not match dtor, an assert is triggered.

If the space is newly-allocated, it will be zeroed.

Parameters:
  • p – The pool to allocate in.

  • key – The key to allocate at.

  • size – The amount of space to allocate.

  • dtor – The destructor for the allocation.

Returns:

The pointer to the space, whether newly-allocated or not.

Pre:

p must not be NULL.

Pre:

key must not be NULL.

Pre:

size must be greater than 0.

Pre:

If key was already used, size must match the size of the existing allocation, and dtor must match the destructor.

Pre:

The map must not have been created with y_mappool_createStringKey().

void *y_mappool_callocStringKey(y_MapPool p, const char *key, size_t size, y_Destructor dtor)

Allocates space in p for key and returns a pointer to the space, or NULL on error.

If key has already been used, then the pointer to the space for the key is returned. In that case, if the size of the allocation does not match size, or the destructor does not match dtor, an assert is triggered.

If the space is newly-allocated, it will be zeroed.

Parameters:
  • p – The pool to allocate in.

  • key – The key to allocate at.

  • size – The amount of space to allocate.

  • dtor – The destructor for the allocation.

Returns:

The pointer to the space, whether newly-allocated or not.

Pre:

p must not be NULL.

Pre:

key must not be NULL.

Pre:

size must be greater than 0.

Pre:

If key was already used, size must match the size of the existing allocation, and dtor must match the destructor.

Pre:

The map must have been created with y_mappool_createStringKey().

void y_mappool_free(y_MapPool p)

Frees the pool and all of its stuff.

Parameters:

p – The pool to free.

Pre:

p must not be NULL.

group setpool

Public function definitions and types for Yc’s set pools.

Typedefs

typedef struct y_setpool *y_SetPool

The public type of the private setpool struct.

Functions

void *y_setpool_alloc(y_SetPool p, const void *data, size_t size, y_Destructor dtor)

Allocates space in the setpool for the data and copies it over.

The setpool becomes the owner of the data.

Parameters:
  • p – The setpool to allocate in.

  • data – A pointer to the data to copy in.

  • size – The size of the allocation.

  • dtor – The destructor to attach to the allocation.

Returns:

A pointer to the allocation, even if it already exists, or NULL on error.

Pre:

p must not be NULL.

Pre:

size must be greater than 0.

Pre:

data must not be NULL.

Pre:

dtor must be a valid destructor index.

size_t y_setpool_nbytes(const y_SetPool p)

Returns the number of given to callers from the setpool.

Parameters:

p – The setpool to query.

Returns:

The number of bytes given to callers from the setpool.

Pre:

p must not be NULL.

size_t y_setpool_cap(const y_SetPool p)

Returns the maximum number of elements the provided setpool can hold (the capacity).

If the load of the setpool is less than 1, the setpool will never reach this capacity before expanding.

Parameters:

p – The setpool whose capacity will be returned.

Returns:

p’s capacity.

Pre:

p must not be NULL.

size_t y_setpool_max(const y_SetPool p)

Returns the maximum number of element p can hold without allocating more memory.

Parameters:

p – The setpool whose max size will be returned.

Returns:

p’s max size without allocating more memory.

Pre:

p must not be NULL.

float y_setpool_load(const y_SetPool p)

Returns the load factor that was set for the setpool.

Parameters:

p – The setpool whose load factor will be returned.

Returns:

p’s load factor.

Pre:

p must not be NULL.

bool y_setpool_exists(const y_SetPool p, const void *data, size_t size)

Returns true if an allocation with exactly the same size and contents of the given data exists in the setpool.

It is highly recommended that any padding in the data be memset to 0 bytes.

Parameters:
  • p – The setpool.

  • data – The data to find.

  • size – The size of the data, in bytes.

Returns:

True if there is an allocation with exactly the same data and size, false otherwise.

Pre:

p must not be NULL.

Pre:

data must not be NULL.

bool y_setpool_exists_k(const y_SetPool p, const void *data, size_t size, void *data_ptr)

Returns true if an allocation with exactly the same size and contents of the given data exists in the setpool.

It is highly recommended that any padding in the data be memset to 0 bytes. Also returns a pointer to the data.

Parameters:
  • p – The setpool.

  • data – The data to find.

  • size – The size of the data, in bytes.

  • data_ptr – A pointer to a pointer to return the pointer to the data.

Returns:

True if there is an allocation with exactly the same data and size, false otherwise.

Pre:

p must not be NULL.

Pre:

data must not be NULL.

Pre:

data_ptr must not be NULL.

void *y_setpool_at(const y_SetPool p, const void *data, size_t size)

Returns a pointer to the data in the setpool that exactly matches the given data and size.

If there is no such data in the setpool, this panics. It is highly recommended that any padding in the data be memset to 0 bytes.

Parameters:
  • p – The setpool.

  • data – The data to find.

  • size – The size of the data, in bytes.

Returns:

A pointer to the data in the setpool.

Pre:

p must not be NULL.

Pre:

data must not be NULL.