allocation.rst

Memory allocation

c

#include <libcork/core.h>

The macros in this section provide nicer interfaces for certain memory allocation tasks. We provide two strategies for handling memory allocation failures. The default is to abort the program, since there's usually not going to be much actual recovery that can be done. There are also macros that will return a NULL pointer (just like the standard malloc and friends), allowing you to try to perform some recovery. (If you just want to print out a friendly error message and quit the program, use the default abort-on-failure macros; they'll do both of those things for you, and your code will be much simpler.)

Note

All of the internal memory allocation performed by libcork is done using the abort-on-failure macros. The recover-on-failure macros only affect memory allocation that you perform yourself.

Aborting on failure

The macros in this section abort the program if any memory allocation fails.

void *cork_malloc(size_t size) void *cork_calloc(size_t count, size_t size) void *cork_realloc(void *ptr, size_t new_size)

Uses the standard malloc, calloc, and realloc functions to allocate (or reallocate) some memory. These functions behave exactly like the underlying standard functions; however, if the allocation fails, they'll print out an error message and abort the program using abort().

Note

Note that the possible memory leak in the standard realloc function doesn't apply here, since we're going to abort the whole program if the reallocation fails.

type *cork_new(TYPE type)

Allocate a new instance of the given type. This is exactly equivalent to:

cork_malloc(sizeof(type))

Since we use the standard malloc and friends to allocate the memory, you should use the standard free function to free it.

Recovering from failures

The macros in this section will return a NULL pointer if any memory allocation fails, allowing you to (possibly? maybe?) recover from the error condition.

void *cork_xmalloc(size_t size) void *cork_xcalloc(size_t count, size_t size) void *cork_xrealloc(void *ptr, size_t new_size) type *cork_xnew(TYPE type)

These macros do the same thing as the non-x variants, but they don't abort the program if the allocation fails. Instead, you'll get a NULL pointer back. You should still use the standard free function to free the memory when you're done with it.

Note that cork_xrealloc is more safe than the standard A common idiom when calling the standard realloc function is:

void  *ptr = /* from somewhere */;
/* UNSAFE!  Do not do this! */
ptr = realloc(ptr, new_size);

This is unsafe, however. The realloc function returns a NULL pointer if the reallocation fails. By assigning directly into ptr, you'll get a memory leak in these situations. The cork_xrealloc function, on the other hand, will automatically free the existing pointer if the reallocation fails, eliminating the memory leak:

void  *ptr = /* from somewhere */;
/* This is safe.  Do this. */
ptr = cork_realloc(ptr, new_size);

String-related functions

const char *cork_strdup(const char *str) const char *cork_xstrdup(const char *str)

Creates a copy of the given C string. You shouldn't modify the contents of the copied string. You must use :ccork_strfree() to free the string when you're done with it. The x variant returns a NULL pointer if the allocation fails; the non-x variant aborts the program.

void cork_strfree(const char *str)

Frees str, which must have been created using :ccork_strdup() or :ccork_xstrdup().