koliseo

A C library for a simple arena allocator.

Table of Contents

• What is this thing?
  • Basic example
  • Extra features
    • Region
    • Debug
    • Gulp
    • List template
    • Experimental
    • How to use extras
  • Documentation
  • Prerequisites
  • Configuration
  • Building
  • 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.

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.

Region

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)
  • 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

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.

List template

Any time LIST_T is defined before including templates/list.h, a basic 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 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
• Debug: KLS_DEBUG_CORE
• Gulp: KOLISEO_HAS_GULP
• Experimental: KOLISEO_HAS_EXPER

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.

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.
• Run ./configure --enable-gulp to setup the Makefile appropriately and build with -DKOLISEO_HAS_GULP flag.
• 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

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

• Break up internal extensions to the core functionality
  • Maybe move the guarded code into separate headers?
• Model KLS_Temp_Conf to still be included without Region feature
• At the moment, the arena can't grown its own underlying buffer.
  • Add backwards-compatible logic to enable growable arenas.
• Clean up the Windows part of the includes, to have minimal definitions from windows.h.