109 The boundaries — running things overlapped, and when there is no OS

109.1 Stackless coroutines — overlapping without threads#

If a function can do some work, stop, and later start again from that place, much becomes easier, because the code can be written in order instead of a state machine written by hand.

#include <proven.h>
#include <stdio.h>

/* A stackless coroutine: how far it got is held in one slot of a struct, and
   the macros return to that spot with a switch. No thread, no separate stack,
   no allocation. */
typedef struct {
    proven_coro_t co;      /* the slot that remembers how far it got */
    int           sent;
    int           limit;
} producer_t;

/* returning 0 means "one value handed out, paused"; 1 means "all done" */
static int produce(producer_t *p, int *out)
{
    PROVEN_CORO_BEGIN(&p->co);
    while (p->sent < p->limit) {
        *out = p->sent * 10;
        p->sent += 1;
        PROVEN_CORO_YIELD(&p->co);   /* it leaves here and comes back to this spot on the next call */
    }
    PROVEN_CORO_END(&p->co);
}

int main(void)
{
    producer_t p = { .sent = 0, .limit = 4 };
    PROVEN_CORO_INIT(&p.co);

    int value = -1;
    while (!PROVEN_CORO_IS_DONE(&p.co)) {
        if (produce(&p, &value) == 0)
            printf("produced %d\n", value);
    }
    printf("finished after %d values; coroutine state is %zu bytes\n",
           p.sent, sizeof(proven_coro_t));
    return 0;
}

produced 0
produced 10
produced 20
produced 30
finished after 4 values; coroutine state is 4 bytes

The heart of it is the last line of the output — the state this coroutine remembers is 4 bytes. There is no separate stack, no thread and no allocation. It packages an old knack in C in which macros make re-entry points with switch and case (a cousin of Duff’s device — that syntax seen in chapter 33 is used again here).

The price is clear too. Local variables do not survive — stop and come back and they are gone, so state that must be maintained has to be kept in a struct. It is why the example kept sent as a struct member. And, being implemented with switch, PROVEN_CORO_YIELD cannot be put inside another switch.

Even so the reason this model is loved in embedded work is plain. If one task is 4 bytes, hundreds can be started at little cost, and since no stack is taken separately the memory usage can be calculated at compile time.

109.2 The job system — using several cores#

proven_job_sys_t is a small system equipped with a queue of work and worker threads. What sets it apart is that the queue’s size is fixed — if it overflows, submission fails, and that failure comes as a value. The judgement is that an infinitely growing queue is merely a device for putting the problem off until memory is exhausted.

There are five calls, and their order is itself the contract.

proven_job_sys_t *sys;
proven_err_t e = proven_job_system_init(alloc, 4, 256, &sys);  /* ① 4 workers, queue 256 */
bool ok = proven_job_submit(sys, routine, arg);                /* ② submit (false if full or closed) */
bool did = proven_job_execute_one(sys);                        /* ③ this thread handles one too */
proven_job_system_close(sys);                                  /* ④ take no more */
proven_job_system_destroy(sys);                                /* ⑤ join the workers and clean up */

That it is an opaque type stands out — the inside of proven_job_sys_t is not in the header and it is handled only by pointer (the opaque type of chapter 69 in the flesh). Platform resources such as threads and locks are inside, and their layout is not to be exposed to user code.

The contract is also why ④ and ⑤ are separate. Closing is “no more submissions are taken”, and destroying is “wait for the workers to finish and then clean up”. Between them, the header requires the producer threads to be joined.

proven_job_execute_one is a little special. It lets the submitting side handle one item of work itself — so when submission fails because the queue is full, instead of merely waiting, the submitter can handle one item and try again (a simple form of work stealing).

The false of proven_job_submit, though, means two things. It is false when the queue is full and also when the system is closed. The first calls for trying again and the second for stopping. To tell them apart, use proven_job_submit_ex — PROVEN_ERR_AGAIN comes when the queue is full, PROVEN_ERR_INVALID_STATE when the system is closed.

To wait until all the submitted work has finished, use a job group (proven_job_group_t).

proven_job_group_t group;
proven_job_group_init(&group);
proven_err_t e = proven_job_group_submit(sys, &group, routine, arg);  /* the group counts it */
proven_job_group_wait(sys, &group);                                  /* returns when all are done */

While it waits, proven_job_group_wait takes work out of the queue and runs it itself. So the wait makes progress even when every worker is busy. After it returns, what the jobs wrote may be read. The group must stay alive until every job submitted to it has finished — leaving the block that holds the group before the wait is the lifetime problem seen in chapter 45.

/* thread A */                    /* thread B */
proven_job_submit(sys, job);      proven_job_system_destroy(sys);

109.3 Threads, allocators, and provenance#

In a program running on several threads the allocator demands special care. If two threads use one arena together, chapter 104′s simple action of “cutting from the front” becomes a race at once. The prescription is usually one per thread — and then no synchronisation is needed at all.

Pointer provenance, which was only named in chapter 15, becomes practical here too. Since even at the same address it matters which allocation a pointer came from, giving a block obtained from one allocator back to another is a contract violation (as in chapter 104′s counterexample) even if the address happens to match. The library’s name came from here.

109.4 When there is no OS — freestanding#

Running with no OS is the constraint that most shaped this library. It is the demand to run in the very environment chapter 76 gave as the reason the standard library is thin — a place with no operating system, no heap and no files.

What changes in a freestanding build is this.

• platform/ is not included at all. Files, time and OS randomness disappear.
• Allocation is done with an arena over a static buffer (chapter 104). There is no malloc.
• Strings are handled with _borrow over stack and static buffers (chapter 105).
• You register the panic handler yourself — there may be no console to print to, so it becomes a matter of lighting an LED, kicking a watchdog or rebooting.
• Real-number formatting uses large-integer arithmetic, so it can be taken out whole if it is not needed.

Why the disciplines of the earlier chapters — “take the allocator as an argument”, “a view is borrowed”, “no hidden globals” — were insisted on so persistently becomes clear here. Those disciplines were not a matter of taste but the minimum condition for running in this environment.

109.4.1 The actual build procedure#

Left in words alone it stays vague, so here is the order.

1. Take platform/ out of the compilation list. Leave only src/proven/*.c. Files, time, OS randomness, streams, mmap and the job system go out with it.
2. Define PROVEN_FREESTANDING (-DPROVEN_FREESTANDING=1). proven_heap_allocator() then returns an unusable value (all zeros), and if it is used by mistake proven_alloc_is_valid says false.
3. Reserve the backing memory statically. Put one array where the linker script knows it and lay an arena over it (chapter 104).
4. Register a panic handler. There being no console, one of an LED, a watchdog or a reboot (chapter 102′s example).
5. Take out what is not needed. If real-number formatting is not used, -DPROVEN_FMT_NO_FLOAT strips the large-integer arithmetic code out whole.

/* the skeleton of a freestanding program */
static proven_byte_t g_pool[8 * 1024];      /* the memory budget is settled here */

int main(void)
{
    proven_set_panic_handler(board_panic);
    proven_arena_t arena = proven_arena_create(
        (proven_mem_mut_t){ .ptr = g_pool, .size = sizeof g_pool });
    proven_allocator_t alloc = proven_arena_as_allocator(&arena);

    for (;;) {
        proven_arena_reset(&arena);          /* reset on every pass */
        handle_one_event(alloc);
    }
}

These twenty lines contain all of this part’s discipline — the allocator is an argument, lifetime is per arena, main does not return (chapter 59), and the memory budget is written as a number in the source.

109.5 Where this library stands — what it is, and what it is not#

Before closing the part, the library’s place has to be made clear. The design seen so far — taking an allocator as a parameter, returning failure as a value, views that carry a length, refusing rather than truncating — was not invented by proven. Zig’s allocator parameter, Rust’s Result and slices, recent C++‘s span and expected, and the in-house C conventions of many companies have all moved in the same direction. There is considerable common ground about it.

proven, however, is not that common ground itself. It is one attempt to implement that direction in C23 — neither a standard nor an industry component. The distinction matters for a simple reason: the direction has been verified in many places, but this implementation has not yet. What to take from this part is the direction rather than the code, and if you do take the code, take it knowing what follows.

109.5.1 What has been verified so far#

What this book has put in print is exactly this much.

That is, what this book vouches for is that the code printed here runs in this environment — not that the whole library is verified in every environment. The book claims no more than that.

109.5.2 Stability — what may still change#

proven is not at 1.0. The version this book uses is a snapshot of v0.113.0 (the base library proven_base only — the same release’s cryptography library proven_crypto, compression library proven_codec and network layer proven_net are not included). Versions have the form MAJOR.MINOR.PATCH, and while the first number is 0 that means:

• The API may change. Names and signatures are still being tidied. There is no guarantee that this book’s examples compile unchanged against the next version.
• No ABI (application binary interface) is promised. Struct layouts may change, so mixing pre-compiled binaries is not advisable at this stage; building from source alongside your own code is safer.
• Pin the version. If you use it in earnest, vendor a specific snapshot into your repository (as this book does under vendor/proven) and move it deliberately.

109.5.3 What is not there yet#

To set it down honestly: the following are absent or thin in this version.

• Performance and size comparisons. The library’s repository holds benchmarks of float parsing and formatting against glibc. They were measured on one x86-64 machine, and there is no benchmark of the library’s other parts and none against C libraries other than glibc. This book has not re-measured those numbers, so it makes no performance claim — a performance claim without data is advertising.
• Outside users. There is little record of use in projects beyond the author’s.
• A wide platform matrix. The freestanding branch exists in the design, but the list of continuously verified targets is narrow.
• A long compatibility history. The trust an old library earns — “it has been carried across many versions already” — accumulates only with time.

109.6 When it is better not to use it#

We close honestly. There are cases where this library is not the answer.

• Short, script-like programs — for a twenty-line tool, ownership discipline and allocator parameters are mere formality. The standard library is enough.
• A codebase that already has other conventions — a large project mostly already has its own string, container and error conventions. Mix two conventions and conversion code arises at every boundary, and those boundaries become the places of new bugs.
• Places like C++ and Rust where the language already solves the problem — in an environment where the language handles ownership and error propagation, there is little reason to lay a C library on top.
• Work that one standard function finishes — exactly as this book said in chapter 76. The right attitude is neither “do not use it” nor “use it unconditionally” but knowing the contract and choosing.

With this, the promise this book made in chapter 1 has been kept — showing C’s problems first, and showing one answer to them through to the end. The next chapter closes this part — writing the same program in plain C and in proven, side by side. Beyond it lies the story outside these pages: chapter 111 looks round the terrain of practice (build tools, version control, real projects), chapter 114 follows, and the last chapter gathers up the road this book has travelled.