Contexts

type UNIT_Context

Container type for all of UNIT’s state. This structure has no public fields, but it’s size is available publicly (allowing for allocation on the stack).

UNIT_Status UNIT_Context_Init(UNIT_Context *context)

Initialize a context. On success, UNIT_Context_Clear() must be called later to free memory allocated by this function.

Parameters:

  • context – A pointer to a context. Memory at this location will be overwritten.

Returns:

Indicator whether the call was successful. See UNIT_FAILED.

Example
1UNIT_Context context;
2if (UNIT_FAILED(UNIT_Context_Init(&context))) {
3   return -1;
4}
5
6// Must call UNIT_Context_Clear() later.

Quirk

If this function fails, there will not be any error indicator set, because there’s no context to store it on.

UNIT_Context *UNIT_Context_New(void)

Create a new context. On success, UNIT_Context_Free() must be called later to free memory allocated by this function.

Returns:

A heap-allocated pointer to the context, or NULL if an allocation failed. If non-NULL, must be deallocated using UNIT_Context_Free().

Example
1UNIT_Context *context = UNIT_Context_New();
2if (context == NULL) {
3   return -1;
4}
5
6// Must call UNIT_Context_Free() later.

Quirk

If this function fails, there will not be any error indicator set, because there’s no context to store it on.

void UNIT_Context_Clear(UNIT_Context *context)

Free memory allocated by UNIT_Context_Init().

Parameters:

  • context – The context to clear.

Example
1UNIT_Context context;
2if (UNIT_FAILED(UNIT_Context_Init(&context))) {
3   /* ... */
4}
5
6/* ... */
7
8UNIT_Context_Clear(&context);
void UNIT_Context_Free(UNIT_Context *context)

Free memory allocated by UNIT_Context_New(). This will also call UNIT_Context_Clear().

Parameters:

  • context – The context to free.

Example
1UNIT_Context *context = UNIT_Context_New();
2if (context == NULL) {
3   /* ... */
4}
5
6/* ... */
7
8UNIT_Context_Clear(&context);