Memory allocation

#include <libcork/core.h>

One of the biggest hassles in writing C code is memory management. libcork’s memory allocation API tries to simplify this task as much as possible. This is still C, so you still have to manage allocated memory manually — for instance, by keeping careful track of which section of code “owns” any memory that you’ve allocated from heap, and is therefore responsible for freeing it. But we can make it easier to handle memory allocation failures, and provide helper macros for certain common allocation tasks.

There is another important use case that we also want to support: giving application writers complete control over how the libraries they use allocate and deallocate memory. libcork provides this capability, giving you control over how, for instance, a hash table allocates its internal buckets. If you’re writing a library that links with libcork as a shared library, you’ll get this behavior for free; if the application writer customizes how libcork allocates memory, your library will pick up that customization as well. If you’re embedding libcork, so that your library’s clients can’t tell (or care) that you’re using libcork, then you’ll want to expose your own similar customization interface.

Allocating memory

The simplest part of the API is the part responsible for actually allocating and deallocating memory. When using this part of the API, you don’t have to worry about customization at all; the functions described here will automatically “do the right thing” based on how your library or application is configured. The biggest thing to worry about is how to handle memory allocation failures. We provide two strategies, “guaranteed” and “recoverable”.

The most common use case is that running out of memory is a Really Bad Thing, and there’s nothing we can do to recover. In this case, it doesn’t make sense to check for memory allocation failures throughout your code, since you can’t really do anything if it does happen. The “guaranteed” family of functions handles that error checking for you, and guarantees that if the allocation function returns, it will return a valid piece of memory. If the allocation fails, the function will never return. That allows you to right simple and safe code like the following:

struct my_type  *instance = cork_new(struct my_type);
/* Just start using instance; don't worry about verifying that it's
 * not NULL! */

On the other hand, you might be writing some code that can gracefully handle a memory allocation failure. You might try to allocate a super-huge cache, for instance; if you can’t allocate the cache, your code will still work, it will just be a bit slower. In this case, you want to be able to detect memory allocation failures, and handle them in whatever way is appropriate. The “recoverable” family of functions will return a NULL pointer if allocation fails.

Note

libcork itself uses the guaranteed functions for all internal memory allocation.

Guaranteed allocation

The functions in this section are guaranteed to return a valid newly allocated pointer. If memory allocation fails, the functions will not return.

void *cork_malloc(size_t size)

void *cork_calloc(size_t count, size_t size)

void *cork_realloc(void *ptr, size_t old_size, size_t new_size)

type *cork_new(TYPE type)

The first three functions mimic the standard malloc, calloc, and realloc functions to allocate (or reallocate) some memory, with the added guarantee that they will always return a valid newly allocated pointer. cork_new is a convenience function for allocating an instance of a particular type; it is exactly equivalent to:

cork_malloc(sizeof(type))

Note that with cork_realloc, unlike the standard realloc function, you must provide the old size of the memory region, in addition to the requested new size.

Each allocation function has a corresponding deallocation function that you must use to free the memory when you are done with it: use cork_free() to free memory allocated using cork_malloc or cork_realloc; use cork_cfree() to free memory allocated using cork_calloc; and use cork_delete() to free memory allocated using cork_new.

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.

Recoverable allocation

The functions in this section will return a NULL pointer if any memory allocation fails, allowing you to recover from the error condition, if possible.

void *cork_xmalloc(size_t size)

void *cork_xcalloc(size_t count, size_t size)

void *cork_xrealloc(void *ptr, size_t old_size, size_t new_size)

void *cork_xreallocf(void *ptr, size_t old_size, size_t new_size)

type *cork_xnew(TYPE type)

The first three functions mimic the standard malloc, calloc, realloc functions. cork_xreallocf mimics the common reallocf function from BSD. These functions return NULL if the memory allocation fails. (Note that unlike the standard functions, they do not set errno to ENOMEM; the only indication you have of an error condition is a NULL return value.)

Note that with cork_xrealloc and cork_xreallocf, unlike the standard realloc function, you must provide the old size of the memory region, in addition to the requested new size.

cork_xreallocf is more safe than the standard realloc function. A common idiom when calling realloc is:

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

This is unsafe! 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_xreallocf 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_xreallocf(ptr, new_size);
/* Check whether ptr is NULL before using it! */

Each allocation function has a corresponding deallocation function that you must use to free the memory when you are done with it: use cork_free() to free memory allocated using cork_xmalloc, cork_xrealloc, or cork_xreallocf; use cork_cfree() to free memory allocated using cork_xcalloc; and use cork_delete() to free memory allocated using cork_xnew.

Deallocation

Since this is C, you must free any memory region once you’re done with it. You must use one of the functions from this section to free any memory that you created using any of the allocation functions described previously.

void *cork_free(void *ptr, size_t size)

void *cork_cfree(void *ptr, size_t count, size_t size)

type *cork_delete(void *ptr, TYPE type)

Frees a region of memory allocated by one of libcork’s allocation functions.

Note that unlike the standard free function, you must provide the size of the allocated region when it’s freed, as well as when it’s created. Most of the time this isn’t an issue, since you’re either freeing a region whose size is known at compile time, or you’re already keeping track of the size of a dynamically sized memory region for some other reason.

You should use cork_free to free memory allocated using cork_malloc(), cork_realloc(), cork_xmalloc(), cork_xrealloc(), or cork_xreallocf(). You should use cork_cfree to free memory allocated using cork_calloc() or cork_xcalloc(). You should use cork_delete to free memory allocated using cork_new() or cork_xnew().

Duplicating strings

const char *cork_strdup(const char *str)

const char *cork_strndup(const char *str, size_t size)

const char *cork_xstrdup(const char *str)

const char *cork_xstrndup(const char *str, size_t size)

These functions mimic the standard strdup function. They create a copy of an existing C string, allocating exactly as much memory is needed to hold the copy.

The strdup variants calculate the size of str using strlen. For the strndup variants, str does not need to be NUL-terminated, and you must pass in its size. (Note that is different than the standard strndup, where str must be NUL-terminated, and which copies at most size bytes. Our version always copies exactly size bytes.) The result is guaranteed to be NUL-terminated, even if the source str is not.

You shouldn’t modify the contents of the copied string. You must use cork_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 is guaranteed to return a valid pointer to a copied string.

void cork_strfree(const char *str)

Frees str, which must have been created using cork_strdup() or cork_xstrdup().

Customizing how libcork allocates

The cork_alloc type encapsulates a particular memory allocation scheme. To customize how libcork allocates memory, you create a new instance of this type, and then use cork_set_allocator() to register it with libcork.

void cork_set_allocator(const struct cork_alloc *alloc)

Override which allocator instance libcork will use to create and free memory. We will take control of alloc; you must not free it yourself after passing it to this function.

You can only call this function at most once. This function is not thread-safe; it’s only safe to call before you’ve called any other libcork function (or any function from any other library that uses libcork. (The only exceptions are libcork functions that take in a cork_alloc parameter or return a cork_alloc result; these functions are safe to call before calling cork_set_allocator.)

const struct cork_alloc *cork_allocator

The current allocator instance that libcork will use to create and free memory.

Writing a custom allocator

struct cork_alloc

The cork_alloc type contains several methods for performing different allocation and deallocation operations.

You are only required to provide implementations of xmalloc and free; we can provide default implementations of all of the other methods in terms of those two. You can provide optimized versions of the other methods, if appropriate.

struct cork_alloc *cork_alloc_new_alloc(const struct cork_alloc *parent)

cork_alloc_new creates a new allocator instance. The new instance will itself be allocated using parent. You must provide implementations of at least the xmalloc and free methods. You can also override our default implementations of any of the other methods.

This function is not thread-safe; it’s only safe to call before you’ve called any other libcork function (or any function from any other library that uses libcork. (The only exceptions are libcork functions that take in a cork_alloc parameter or return a cork_alloc result; these functions are safe to call before calling cork_set_allocator.)

The new allocator instance will automatically be freed when the process exits. If you registered a user_data pointer for your allocation methods (via cork_alloc_set_user_data()), it will be freed using the free_user_data method you provided. If you create more than one cork_alloc instance in the process, they will be freed in the reverse order that they were created.

Note

In your allocator implementation, you cannot assume that the rest of the libcork allocation framework has been set up yet. So if your allocator needs to allocate, you must not use the usual cork_malloc() family of functions; instead you should use the cork_alloc_malloc variants to explicitly allocate memory using your new allocator’s parent.

void cork_alloc_set_user_data(struct cork_alloc *alloc, void *user_data, cork_free_f free_user_data)

Provide a user_data pointer, which will be passed unmodified to each allocation method that you register. You can also provide an optional free_user_data method, which we will use to free the user_data instance when the allocator itself is freed.

void cork_alloc_set_calloc(struct cork_alloc *alloc, cork_alloc_calloc_f calloc)

void cork_alloc_set_xcalloc(struct cork_alloc *alloc, cork_alloc_calloc_f calloc)

void *(*cork_alloc_calloc_f)(const struct cork_alloc *alloc, size_t count, size_t size)

These methods are used to implement the cork_calloc() and cork_xcalloc() functions. Your must allocate and return count * size bytes of memory. You must ensure that every byte in this region is initialized to 0. The calloc variant must always return a valid pointer; if memory allocation fails, it must not return. The xcalloc variant should return NULL if allocation fails.

void cork_alloc_set_malloc(struct cork_alloc *alloc, cork_alloc_malloc_f malloc)

void cork_alloc_set_xmalloc(struct cork_alloc *alloc, cork_alloc_malloc_f malloc)

void *(*cork_alloc_malloc_f)(const struct cork_alloc *alloc, size_t size)

These methods are used to implement the cork_malloc() and cork_xmalloc() functions. You must allocate and return size bytes of memory. The malloc variant must always return a valid pointer; if memory allocation fails, it must not return. The xmalloc variant should return NULL if allocation fails.

void cork_alloc_set_realloc(struct cork_alloc *alloc, cork_alloc_realloc_f realloc)

void cork_alloc_set_xrealloc(struct cork_alloc *alloc, cork_alloc_realloc_f realloc)

void *(*cork_alloc_realloc_f)(const struct cork_alloc *alloc, void *ptr, size_t old_size, size_t new_size)

These methods are used to implement the cork_realloc(), cork_xrealloc(), and cork_xreallocf() functions. You must reallocate ptr to contain new_size bytes of memory and return the reallocated pointer. old_size will be the previously allocated size of ptr. The realloc variant must always return a valid pointer; if memory reallocation fails, it must not return. The xrealloc variant should return NULL if reallocation fails.

void cork_alloc_set_free(struct cork_alloc *alloc, cork_alloc_free_f free)

void *(*cork_alloc_free_f)(const struct cork_alloc *alloc, void *ptr, size_t size)

These methods are used to implement the cork_free(), cork_cfree(), and cork_delete() functions. You must deallocate ptr. size will be the allocated size of ptr.