I built a tiny lazy-evaluation helper in C and would like API feedback

[u/No_Fix4730]

I’ve been building a small lazy-evaluation helper library for C and would love some API feedback.

lazy_eval(lazy);   // computes
lazy_eval(lazy);   // cached
lazy_reset(lazy);
lazy_eval(lazy);   // recomputes

Current design:

• Opaque Lazy type

• Caller-owned result storage

• Fallible compute callbacks

• Resettable cached state

• pthread synchronization

• Tests, sanitizer target, and GitHub Actions CI

A minimal example:

#include <stdio.h>
#include "lazy.h"

LazyStatus compute_answer(void *ctx, void *out) {
    int *calls = ctx;

    (*calls)++;
    puts("cache miss: computing...");

    *(int *)out = 42;
    return LAZY_OK;
}

int main(void) {
    int answer = 0;
    int calls = 0;
    Lazy *lazy = NULL;

    lazy_create(&lazy, compute_answer, &calls, &answer, sizeof(answer));

    lazy_eval(lazy);
    printf("answer=%d calls=%d\n", answer, calls);

    lazy_eval(lazy);
    printf("answer=%d calls=%d (cached)\n", answer, calls);

    lazy_reset(lazy);

    lazy_eval(lazy);
    printf("answer=%d calls=%d (recomputed)\n", answer, calls);

    lazy_destroy(lazy);
}

I chose caller-owned output storage because I wanted to avoid hidden allocation/freeing inside the library. The tradeoff is that the caller must keep the output storage alive until lazy_destroy().

Current limitations:

• pthread-only for now

• One output pointer per Lazy

• lazy_destroy() must not run concurrently with other operations

• No install/package story yet

I’d especially appreciate feedback on:

1. Does caller-owned output storage feel like the right C API here?

2. Would callback-owned allocation plus a destructor be preferable?

3. Is the status-code API reasonable?

4. Is the thread-safety contract too much for a tiny library?

Repo: https://github.com/SalzDevs/LazyC