koliseo

A C library for a simple arena allocator.

Table of Contents

• What is this thing?
  • Basic example
  • Prerequisites
  • Configuration
  • Building
  • Extra features
    • Region
    • Debug
    • Gulp
    • Templates
    • Experimental
    • How to use extras
  • Extensions
  • Documentation
  • Supported platforms
• Credits
• Todo

What is this thing?

This is a C library for an arena allocator, whose arenas are named Koliseo. It offers a basic API to perform initialisation, push (request arena memory), reset and free of a Koliseo.

If you compile it without defining any special macros, you will get the basic functionality.

Basic example

This is a basic usage example, initialising a Koliseo and then pushing an example pointer. You can build it by running:

gcc static/basic_example.c src/koliseo.c -o basic_example

For a more complete example, including Koliseo_Temp usage, check out demo.c provided in static folder.

typedef struct Example {
    int val;
} Example;

#include "../src/koliseo.h"

int main(void)
{
    //Init the arena
    Koliseo* kls = kls_new(KLS_DEFAULT_SIZE);

    //Use the arena (see demo for Koliseo_Temp usage)
    Example* e = KLS_PUSH(kls, Example);
    e->val = 42;

    //Show contents to stdout
    print_dbg_kls(kls);

    //Free the arena
    kls_free(kls);
    return 0;
}

After including the koliseo.h header:

• To initialise a default arena:

Koliseo* kls_new(size_t)

• To request memory for a specific type:

Type* KLS_PUSH(Koliseo* kls, Type)

• For C strings, you can use:

char* KLS_PUSH_STR(Koliseo* kls, char* cstring)

• Also, a couple unsafe utility macros (not recommended to use, for now):

char* KLS_STRDUP(Koliseo* kls, char* source, char* dest)

• To free the arena:

void kls_free(Koliseo* kls)

For more documentation on the available functions, see this section.

Prerequisites

To build the demo binary, you need:

• automake and autoconf to generate the needed Makefile
• make to build the binary
• gcc or clang, for building demo

To bootstrap and use the ./anvil tool to build all amboso-supported tags for demo, you also need either:

• bash >4.x, gawk if you want to use amboso
• rustc if you want to use invil

Configuration

To prepare the files needed by autotools, run:

aclocal
autoconf
automake --add-missing
./configure # Optionally, with --enable-debug or --host
make

You will get a ./configure script, which you can use to enable debug mode or other features.

• Run ./configure --host x86-64-w64-mingw32 to setup the Makefile appropriately for a x86_64-w64-mingw32 build.
• Run ./configure --enable-debug to setup the Makefile appropriately and build with -DKLS_DEBUG_CORE flag.
  • By default, enabling debug this way also adds -DKLS_SETCONF_DEBUG to the demo build. This preproc guard lets you really debug kls initialisation, by printing logs from inside kls_set_conf().
• Run ./configure --enable-region to setup the Makefile appropriately and build with -DKOLISEO_HAS_REGION flag. 🚧 (After 0.5, this is no longer relevant) 🚧
• Run ./configure --enable-gulp to setup the Makefile appropriately and build with -DKOLISEO_HAS_GULP flag. 🚧 (After 0.5, this is no longer relevant) 🚧
• Run ./configure --enable-exper to setup the Makefile appropriately and build with -DKOLISEO_HAS_EXPER flag.

Building

To build both the libkoliseo.so lib and demo binary, run:

• ./configure, which should generate the Makefile. See Configuration section.
• make, to build all target

Extra features

By default, extended functionalities are not included in the build, with each feature needing a preprocessor macro to be defined before including the library header. You can find hints on configuration here, or the list of macros here.

🚧 Disclaimer: after version 0.5, the Region and Gulp features are no longer bundled in the main koliseo.c file, after being moved to their own files. Read below for more info. 🚧

Region

🚧 Disclaimer: after version 0.5, the Region feature is no longer present inside the main koliseo.c file. It has been reimplemented as an extension, in kls_region.c file. 🚧 🚧 See the Extension section. 🚧

A ready-to-go index for every allocation you make.

• It uses a linked list and has some the memory overhead, due to hosting a couple static string buffers for the tags, so it may not be suited for all usecases.
• Offers extended API with tagging arguments, to type/name your references
• For now, two allocations backends can be chosen for the list, it can be stored:
  • In an inner Koliseo (this puts an extra limit to the total number of single allocations)
  • 🚧 Since 0.5.2, a new backend is available which leverages growable Koliseo to avoid the extra limit on total number of single allocations. 🚧
  • Using the global allocator (from malloc)
• Extra utility functions
  • Help you estimate relative memory usage by some particular type of object. May prove useful in some scenarios.

Core debug

Extra debug for core calls, may be too verbose for some applications.

Gulp

🚧 Disclaimer: after version 0.5, the Gulp feature is no longer present inside the main koliseo.c file. It has been reimplemented as an extension, in kls_gulp.h file. 🚧

Utility to memory-map a file (always the best idea, right?) to a C string, by providing the filepath.

• Also includes a minimal string-view API, in case you want to work on the file contents differently.

Templates

The templates/ directory hosts some template headers for different data structures. You can find examples on how to use them in the static/ directory.

For example:

Any time LIST_T is defined before including templates/list.h or templates/dllist.h, respectively a basic linked-list or a doubly-linked list implementation supporting Koliseo allocation will be declared for the passed type.

• It can be done also after building a static object for the library.

The LIST_T macro and the templates/list.h or templates/dllist.h should be repeatable without issues, allowing definition of more than one list interface.

This is implemented using some code-generating macros, which could rended build time slower if overused.

Defining the LIST_NAME, LIST_PREFIX and LIST_LINKAGE can allow customisation for each list implementation:

• LIST_NAME: The name of the data type to be generated.
  • If not given, will expand to something like list_int for an int.
• LIST_PREFIX: Prefix for generated functions.
  • If not given, will expand to something LIST_NAME + _. (eg. list_int_)
• LIST_LINKAGE: Customize the linkage of the function.
  • If not given, will expand to static inline.

This is inspired by the dynamic array example by David Priver.

Experimental

Include some experimental (NOT WELL TESTED. USE WITH CAUTION) functions.

In particular, enables the dreaded pop operation and its functions.

How to enable extra features

To aid in building with extra features, see this section.

The preprocessor macros to enable them manually are:

• Region: KOLISEO_HAS_REGION 🚧 (After 0.5, this macro is no longer used) 🚧
• Debug: KLS_DEBUG_CORE
• Gulp: KOLISEO_HAS_GULP 🚧 (After 0.5, this macro is no longer used) 🚧
• Experimental: KOLISEO_HAS_EXPER

Extensions

You can define your own extensions to the allocator, which gives several hook points in its usage:

typedef struct KLS_Hooks {
    KLS_hook_on_new* on_new_handler; /**< Used to pass custom new handler for kls_new_alloc calls.*/
    KLS_hook_on_free* on_free_handler; /**< Used to pass custom free handler for kls_free calls.*/
    KLS_hook_on_push* on_push_handler; /**< Used to pass custom push handler for kls_push calls.*/
    KLS_hook_on_temp_start* on_temp_start_handler; /**< Used to pass custom start handler for kls_temp_start calls.*/
    KLS_hook_on_temp_free* on_temp_free_handler; /**< Used to pass custom free handler for kls_temp_end calls.*/
    KLS_hook_on_temp_push* on_temp_push_handler; /**< Used to pass custom push handler for kls_temp_push calls.*/
} KLS_Hooks;

You can have multiple extensions. For example, src/kls_region.h shows how to implement support for keeping track of all allocated memory regions. See the Region section.

Documentation

HTML docs are available at this Github Pages link.

You can also get the ready pdf version of the docs from the latest release.

If you have doxygen you can generate the HTML yourself, or even the pdf if you have doxygen-latex or equivalents.

Supported platforms

ATM the code should build for:

• x86_64-Linux
• darwin-arm64
• x86_64-w64-mingw32 to target Windows.
  • This build, while mostly identical to Linux/macOS, is less tested.

Credits

Thanks to skeeto for showing me the original base implementation.

Thanks to Mako for the repo banner.

Thanks to Tsoding for its creative string view library (repo), which indeed does things so simply you mostly can't do anything different.

Thanks to David Priver for its dynamic array template example.

Todo

• Model KLS_Temp_Conf to still be included without Region feature
• Clean up the Windows part of the includes, to have minimal definitions from windows.h.