At some point I decided to make as many packages as possible freestanding — independent of any libc implementation or specific OS runtime. That went pretty well. Solod now has 37 standard library packages, and 31 of them work in freestanding mode.

This post describes the techniques I used to get there. There's nothing genuinely novel, and if you're experienced with C, you probably already know all of them. Still, I think it's useful to document the approach — both for me and for anyone interested.

Freestanding mode • Headers • Builtins • Memory • Atomics • Pure C • Allocation • Values • Hooks • Hosted-only • Testing • Final thoughts

Freestanding mode

C has two types of environments. In a hosted environment, you get the full standard library — either the one required by the C standard or, even better, POSIX. In a freestanding environment, you get almost nothing.

The compiler tells you which one you're in:

#if __STDC_HOSTED__
// libc is available
#else
// you're on your own
#endif

Pass -ffreestanding and link with -nostdlib, and that's it: you no longer have printf, or malloc, or even memcpy. There is no entropy source, no file system operations, and no clock. If libc itself is "hard mode", this is "impossible".

Despite its limitations, freestanding mode can be really useful for microcontrollers, WebAssembly sandboxes, kernels, and anything else without an operating system to rely on.

Freestanding headers

Freestanding does not mean "just the C language". The C standard guarantees some headers even without libc, because they define types and macros instead of functions:

float.h   stdalign.h  stdbool.h  stdint.h
limits.h  stdarg.h    stddef.h   ...

Everything that requires actual function implementations is gone:

assert.h  math.h   stdlib.h  time.h
errno.h   stdio.h  string.h  ...

To reflect the hosted/freestanding split, let's introduce builtin.h, a common header included in every standard library package:

#if __STDC_HOSTED__

#include <assert.h>
#include <inttypes.h>
#include <stdalign.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define so_build_hosted

#else

#include <stdbool.h>
#include <stdint.h>
#include <stdalign.h>
#include <stddef.h>

#endif  // __STDC_HOSTED__

Individual packages follow the same approach: branch on so_build_hosted to distinguish between the hosted and freestanding implementations.

Compiler builtins

GCC and Clang implement some C standard functions without relying on libc. These are known as compiler builtins.

__builtin_trap causes the program to terminate abnormally. You can use it to implement poor man's assertion and panic:

#ifdef so_build_hosted

#define so_panic(msg)                                     \
    do {                                                  \
        fprintf(stderr, "panic: %s\n  %s:%d (func %s)\n", \
                msg, __FILE__, __LINE__, __func__);       \
        exit(1);                                          \
    } while (0)

#else

#define assert(cond)                   \
    do {                               \
        if (!(cond)) __builtin_trap(); \
    } while (0)

#define so_panic(msg)     \
    do {                  \
        (void)msg;        \
        __builtin_trap(); \
    } while (0)

#endif // so_build_hosted

From now on, I'll mainly show the freestanding versions and omit the hosted versions to keep things simple.

The __builtin_alloca function allocates memory on the stack. Its bounded wrapper limits the size of each allocation:

#define alloca __builtin_alloca

// The maximum size that can be allocated
// with alloca (64 KB by default).
#ifndef SO_MAX_ALLOCA_SIZE
#define SO_MAX_ALLOCA_SIZE (64 << 10)  // in bytes
#endif

#define so_alloca(size) ({                                \
    size_t _size = (size_t)(size);                        \
    if (_size > SO_MAX_ALLOCA_SIZE)                       \
        so_panic("alloca: size exceeds maximum allowed"); \
    _size ? alloca(_size) : NULL;                         \
})

Memory operations

The memxxx functions from string.h have matching builtins too, so you might expect a freestanding build to provide them for you:

// int memcmp(const void* lhs, const void* rhs, size_t n);
#define memcmp __builtin_memcmp

// void* memcpy(void* dst, const void* src, size_t n);
#define memcpy __builtin_memcpy

// void* memmove(void* dst, const void* src, size_t n);
#define memmove __builtin_memmove

// void* memset(void* dst, int ch, size_t n);
#define memset __builtin_memset

Unfortunately, there's no free lunch here.

__builtin_memcpy is not a separate memcpy implementation. If n is small and known at compile time, the compiler expands it into a few load and store instructions. But if n is large or only known at runtime, it calls the actual memcpy from libc instead.

Even worse, you don't need to mention memcpy explicitly to use it. Suppose you copy a large struct like this:

typedef struct { char buf[4096]; } Big;

void copy(Big* a, const Big* b) {
    *a = *b;
}

When you compile the code for aarch64-freestanding, the object file contains an undefined reference to memcpy. Zero-initializing a local array produces the same issue with memset. Neither name appears in the source; both are introduced by the compiler.

So the freestanding environment must still provide memcpy, memmove, memset, and memcmp for memory operations to work in the general case.

WebAssembly covers three of the four: memcpy, memmove, and memset map to the memory.copy and memory.fill instructions. There is no instruction for comparison, so memcmp stays a real function call even there. On other targets, the toolchain often provides all four, as zig cc does (even with -nostdlib). If it doesn't, provide a plain C implementation:

#undef memcpy
void* memcpy(void* dst, const void* src, size_t n) {
    unsigned char* d = dst;
    const unsigned char* s = src;
    while (n--) *d++ = *s++;
    return dst;
}

#undef memset
void* memset(void* dst, int ch, size_t n) {
    unsigned char* d = dst;
    while (n--) *d++ = (unsigned char)ch;
    return dst;
}

#undef memmove
void* memmove(void* dst, const void* src, size_t n) {
    // omitted for brevity
}

#undef memcmp
int memcmp(const void* lhs, const void* rhs, size_t n) {
    const unsigned char* l = lhs;
    const unsigned char* r = rhs;
    for (; n--; l++, r++) {
        if (*l != *r) return *l - *r;
    }
    return 0;
}

The defines (#define memcpy __builtin_memcpy and others above) are still worth keeping, even if you implement the functions yourself. This way, the compiler can still use its own implementation when applicable.

Fun fact: at -O2 and above, GCC can fold your custom memcpy implementation back into a call to memcpy, which is infinite recursion. -ffreestanding prevents this because it implies -fno-builtin, but the guarantee is weak. You can use -fno-tree-loop-distribute-patterns to disable this behavior for good.

The rest of string.h is not covered. No compiler provides memchr or strlen, so those you always have to write yourself — more on that below.

Atomic operations

Another useful group of compiler builtins is __atomic_xxx, which provide atomic, thread-safe memory access. They operate on regular objects instead of _Atomic objects:

// so_atomic_load atomically loads the value at p.
#define so_atomic_load(p) \
    (__atomic_load_n((p), __ATOMIC_SEQ_CST))

// so_atomic_store atomically stores v at p.
#define so_atomic_store(p, v) \
    (__atomic_store_n((p), (v), __ATOMIC_SEQ_CST))

This makes porting Go's sync/atomic types straightforward. All types — atomic integers, unsigned integers, booleans, and pointers — use the same two load/store macros:

// Bool is an atomic boolean value. The zero value is false.
typedef struct atomic_Bool {
    bool v;
} atomic_Bool;

// Load atomically loads and returns the value stored in x.
bool atomic_Bool_Load(atomic_Bool* x) {
    return so_atomic_load(&x->v);
}

// Store atomically stores val into x.
void atomic_Bool_Store(atomic_Bool* x, bool val) {
    so_atomic_store(&x->v, val);
}

A separate atomic_Bool type isn't strictly required — atomic_Bool_Load and atomic_Bool_Store would work with a plain bool*. Still, it can be useful. With a plain pointer, *x = true creates a silent data race that looks like ordinary code, while the wrapper makes you explicitly write x->v = true.

No stdatomic.h include is needed. However, the CPU must natively support the integer width you use. For example, a 64-bit atomic on a 32-bit target becomes a call to libatomic instead of a single instruction. But that's a different story.

Pure C implementations

If the compiler doesn't provide an implementation, you have to write one yourself. Preferably, use the libc name so all call sites remain unchanged.

A good example is memchr, which is required by bytes.IndexByte. There is a __builtin_memchr, but it is not an implementation, so you need to provide your own:

#ifndef so_build_hosted
// memchr implementation for freestanding environments.
static inline void* memchr(const void* s, int c, size_t n) {
    const unsigned char* p = s;
    unsigned char target = (unsigned char)c;
    while (n--) {
        if (*p == target) return (void*)p;
        p++;
    }
    return NULL;
}
#endif

Some of these DIY implementations aren't trivial, of course. Fortunately, Go's standard library includes many standalone algorithms, such as the string-to-number conversion functions in strconv or integer math in math/bits. Porting them to C is almost mechanical:

// Go version.
const m3 = 0x00ff00ff00ff00ff

// ReverseBytes32 returns the value of x
// with its bytes in reversed order.
func ReverseBytes32(x uint32) uint32 {
    const m = 1<<32 - 1
    x = x>>8&(m3&m) | x&(m3&m)<<8
    return x>>16 | x<<16
}

// C version.
static const int64_t m3 = 0x00ff00ff00ff00ff;

uint32_t bits_ReverseBytes32(uint32_t x) {
    const int64_t m = ((int64_t)1 << 32) - 1;
    x = ((x >> 8) & (m3 & m)) | ((x & (m3 & m)) << 8);
    return (x >> 16) | (x << 16);
}

Memory allocation

Memory allocation calls for a different technique. A naive approach would be to implement a freestanding malloc that uses a static buffer:

extern char so_heap[SO_HEAP_SIZE];
extern size_t so_heap_offset;

static inline void* malloc(size_t size) {
    // Simplified version without alignment.
    if (size > SO_HEAP_SIZE - so_heap_offset) {
        return NULL;
    }
    void* ptr = &so_heap[so_heap_offset];
    so_heap_offset += size;
    return ptr;
}

It might be sufficient for testing, but I'd avoid using it in production.

Instead of reimplementing malloc, let's remove the need for it, and make the caller provide the memory. Start with an allocator interface, so callers don't depend on a specific implementation:

// Allocator defines the interface for memory allocators.
// Simplified version without Realloc and alignment.
typedef struct {
    void* self;
    so_R_ptr_err (*Alloc)(void* self, so_int size);
    void (*Free)(void* self, void* ptr, so_int size);
} mem_Allocator;

#if SIZE_MAX == 0xFFFFFFFFu
typedef int32_t so_int;
#else
typedef int64_t so_int;
#endif

typedef struct {
    const char* ptr;
    so_int len;
} so_String;

typedef struct {
    void* self;
    so_String (*Error)(void* self);
} so_Error;

typedef struct {
    void* val;
    so_Error err;
} so_R_ptr_err;

Then provide an arena allocator, which is freestanding by design:

// Arena is a memory allocator that bump-allocates
// linearly within a fixed buffer.
typedef struct {
    so_Slice buf;
    so_int offset;
} mem_Arena;

mem_Arena mem_NewArena(so_Slice buf) {
    return (mem_Arena){.buf = buf};
}

so_R_ptr_err mem_Arena_Alloc(void* self, so_int size) {
    // Simplified version without alignment.
    mem_Arena* a = self;
    assert(size > 0 && "mem: invalid allocation size");
    if (size > so_len(a->buf) - a->offset) {
        return (so_R_ptr_err){.val = NULL, .err = mem_ErrOutOfMemory};
    }
    void* ptr = &so_at(so_byte, a->buf, a->offset);
    a->offset += size;
    return (so_R_ptr_err){.val = ptr, .err = (so_Error){}};
}

void mem_Arena_Free(void* self, void* ptr, so_int size) {
    // Free in arena is a no-op.
    (void)self; (void)ptr; (void)size;
}

void mem_Arena_Reset(void* self) {
    mem_Arena* a = self;
    a->offset = 0;
}

Usage example:

typedef struct Point {
    so_int x;
    so_int y;
} Point;

// Prepare the arena.
so_byte data[1024];
so_Slice buf = {.ptr = data, .len = sizeof(data)};
mem_Arena arena = mem_NewArena(buf);
mem_Allocator alloc = {
    .self = &arena,
    .Alloc = mem_Arena_Alloc,
    .Free = mem_Arena_Free};

// Allocate a Point. mem_Alloc is a macro that calls
// the Alloc "method" and panics on failure.
Point* p = mem_Alloc(Point, alloc);
p->x = 11;
p->y = 22;

On a freestanding target, an arena is a better choice than a buffer-backed malloc, because the caller decides how much memory is available and when it's released.

Values, not pointers

Constructor functions in Go typically return a pointer:

// A string reader.
type Reader struct {
    s        string
    i        int64 // current reading index
    prevRune int   // index of previous rune; or < 0
}

// NewReader returns a new Reader reading from s.
func NewReader(s string) *Reader {
    return &Reader{s, 0, -1}
}

This roughly translates to the following code, using the memory allocator from the previous section:

// A string reader.
typedef struct {
    so_String s;
    int64_t i;
    so_int prevRune;
} strings_Reader;

// NewReader returns a new Reader reading from s.
// The returned reader is allocated; the caller owns it.
strings_Reader* strings_NewReader(mem_Allocator alloc, so_String s) {
    strings_Reader* r = mem_Alloc(strings_Reader, alloc);
    r->s = s;
    r->i = 0;
    r->prevRune = -1;
    return r;
}

Instead of blindly following Go idioms, it's better to get rid of allocations altogether and return a value:

// NewReader returns a new Reader reading from s.
strings_Reader strings_NewReader(so_String s) {
    return (strings_Reader){.s = s, .prevRune = -1};
}

This isn't a technique specific to writing freestanding code — it's helpful for almost any C library.

Target hooks

Some things you can't write in a target-agnostic way at all. Only the target knows how to print a byte, read the clock, or generate a random number; these all depend on the hardware.

What you can do is declare functions (hooks) and let the user's code define them:

Then the user can call specific APIs available on their hardware:

so_int so_write_out(const uint8_t* buf, so_int size) {
    return board_uart_write(buf, size);
}

int64_t so_time_mono(void) {
    return (int64_t)board_uptime_ms() * 1000000;
}

What happens if the user doesn't provide an implementation? You still want the standard library to compile and work unless someone calls the missing functions. To achieve that, use weak definitions:

// so_write_out drops the bytes and reports a full write,
// so panic and fmt print nothing and report no error.
__attribute__((weak)) so_int so_write_out(const uint8_t* buf, so_int size) {
    (void)buf;
    return size;
}

// so_crand_read reads no bytes. The interpretation is left to the caller.
__attribute__((weak)) so_int so_crand_read(uint8_t* buf, so_int size) {
    (void)buf;
    (void)size;
    return 0;
}

// so_time_wall panics, because no default date is correct.
__attribute__((weak)) so_R_i64_i32 so_time_wall(void) {
    so_panic("time: define so_time_wall for this target");
}

Now every hook gets a default, and a definition in the user code silently wins over the default one.

Note that the defaults above behave differently on purpose. Dropping output is fine because a board with no UART (serial interface) has nowhere to print. Inventing a date is not fine, because no date would be correct.

For the same reason, crypto/rand panics instead of falling back to a software generator. A "random" source that silently returns predictable bytes would be a terrible idea:

// crand_read fills buf with size cryptographically secure random bytes.
// Panics if the target does not define so_crand_read.
static inline void crand_read(uint8_t* buf, so_int size) {
    if (size <= 0) return;
    if (so_crand_read(buf, size) != size) {
        so_panic("crypto/rand: no entropy source");
    }
}

You can still use a fallback when cryptographic security isn't needed, such as for hashing map keys or math/rand:

// runtime_Seed returns a random 64-bit seed.
static inline uint64_t runtime_Seed(void) {
    uint64_t seed = 0;
    // Use cryptographically secure random if available.
    if (so_crand_read((uint8_t*)&seed, 8) == 8 && seed != 0) {
        return seed;
    }
    // Fallback to deterministic xorshift64 sequence.
    // ...
}

Hosted-only

Some things aren't worth solving with hooks, such as the os and net packages, which require a lot of target-specific code. In these cases, it's better to use a header-level guard that fails in freestanding mode:

// so/os/os.h
#include "so/builtin/builtin.h"

#ifndef so_build_hosted
#error "os: hosted environment required"
#endif

If user code imports os in a freestanding environment, the compiler reports an error at compile time instead of at link time or runtime.

Testing

The only way to know if the freestanding implementation actually works is to test it.

My approach in Solod is to run the freestanding packages' test suites with a WASI runtime and a small harness. The harness defines all five hooks from the Target hooks section as WASI imports:

// ciovec is the buffer descriptor that fd_write reads.
// The WASI ABI is 32-bit, so both fields are 32-bit.
typedef struct {
    const uint8_t* buf;
    uint32_t len;
} ciovec;

// wasi_fd_write writes the buffers to the file descriptor
// and stores the number of bytes written in nwritten.
__attribute__((import_module("wasi_snapshot_preview1"), import_name("fd_write")))
extern uint32_t wasi_fd_write(uint32_t fd, const ciovec* iovs,
                              uint32_t iovs_len, uint32_t* nwritten);

// so_write_out writes size bytes to the standard output of the WASI host.
so_int so_write_out(const uint8_t* buf, so_int size) {
    ciovec iov = {.buf = buf, .len = (uint32_t)size};
    uint32_t written = 0;
    if (wasi_fd_write(1, &iov, 1, &written) != 0) {
        return 0;
    }
    return (so_int)written;
}

The freestanding make task builds tests from stdlib packages into a single wasm32-freestanding binary and runs it with wasmtime. This uses the same tests for the freestanding logic as in hosted mode, so I don't need to write separate freestanding tests.

Final thoughts

Here's a summary of the approach I used write a freestanding stdlib in C:

• Choose between hosted and freestanding at compile time.
• Use the compiler builtins when possible.
• Implement the missing parts and port the standalone code.
• Use explicit allocators; prefer values to pointers.
• Declare hooks for the hardware, with weak defaults.
• Fail fast for packages that can't work in freestanding.
• Test in a freestanding build, not just hosted.

I hope you find it useful too.

If you're interested in trying this in practice, take a look at Solod's README — it has everything you need to get started. Or try it online without installing anything.

Solod, a systems language for C and Go developers, might look like one of those languages, but it takes a different approach.

Go's tooling

Solod is not "Go-like" in the usual sense, nor is it an attempt to "fix Go's mistakes". At the language level, Solod is literally a subset of Go. Solod reuses much of Go's existing tooling, including syntax highlighting, LSP, linters, and the package management system.

Take this quick-start guide, for example:

go install solod.dev/cmd/so@latest

go mod init example
go get solod.dev@latest

package main

import "solod.dev/so/math"

func main() {
    ans := math.Sqrt(1764)
    println("Hello, world! The answer is", int(ans))
}

so run .

There's nothing new here. It's mostly standard Go workflow, except for so run, which is a Go program that mimics go run.

Go's standard library

Solod also reuses a lot of Go's standard library code and tests. Some of it is taken verbatim from Go's source code, like these two string functions:

// CutPrefix returns s without the provided leading prefix string
// and reports whether it found the prefix.
func CutPrefix(s, prefix string) (string, bool) {
    if !HasPrefix(s, prefix) {
        return s, false
    }
    return s[len(prefix):], true
}

// HasPrefix reports whether the string s begins with prefix.
func HasPrefix(s, prefix string) bool {
    return len(s) >= len(prefix) && s[:len(prefix)] == prefix
}

Of course, Solod retains the Go authors' copyright.

Some code requires changes to support the manual memory management with explicit allocators used by Solod:

// Go version.
func Clone(s string) string {
    if len(s) == 0 {
        return ""
    }
    b := make([]byte, len(s))
    copy(b, s)
    return unsafe.String(&b[0], len(b))
}

// Solod version.
func Clone(a mem.Allocator, s string) string {
    if len(s) == 0 {
        return ""
    }
    b := mem.AllocSlice[byte](a, len(s), len(s))
    copy(b, s)
    return string(b)
}

You can probably see the resemblance.

A grain of salt

Go tools don't know that Solod is a subset of the full Go language, so they won't flag features Solod doesn't support, like function literals or iterators. These diagnostics come from the custom so tooling:

package main

func main() {
    f := func(n int) {
        println(n)
    }
    f(42)
}

main.go:4:7: function literals are not supported
    f := func(n int) {
         ^here

Also, although a substantial part of Go's standard library is ported verbatim or with minimal changes from the original source, that doesn't mean the code is automatically correct. Solod still needs its own tests, including ones that run under sanitizers and static analyzers.

It's all C in the end

All Solod code is translated to regular C11 and then compiled with GCC or Clang. Solod therefore relies on C tooling and decades of optimization work just as much as on Go's.

Solod code:

package main

import "solod.dev/so/math"

func main() {
    // What might it be?
    ans := math.Sqrt(1764)
    println("Hello, world! The answer is", int(ans))
}

Translated C code:

// -- main.h --
#pragma once
#include "so/builtin/builtin.h"
#include "so/math/math.h"

// -- main.c --
#include "main.h"

int main(void) {
    // What might it be?
    double ans = math_Sqrt(1764.0);
    so_println("%s %" PRIdINT, "Hello, world! The answer is", (so_int)(ans));
    return 0;
}

The C version is noisier, of course, especially for more complex programs than this one. But it remains readable.

And since there's no runtime, interoperability between Solod and C costs nothing.

Final thoughts

A new language doesn't necessarily need a new ecosystem.

Solod relies heavily on Go, and I see that as a strength, not a weakness. Reusing Go's proven tools and standard library makes Solod more reliable and easier to work with.

If you're interested, take a look at Solod's readme — it has everything you need to get started. Or try it online without installing anything.

// Backward returns an iterator over index-value pairs in the slice,
// traversing it backward with descending indices.
func Backward[Slice ~[]E, E any](s Slice) iter.Seq2[int, E]

If you're not deeply familiar with generics and iterators, the natural reaction to this signature (and to the others in the slices package) is: "couldn't this have been made simpler somehow?"

To answer that, let's run a thought experiment. Let's picture ourselves as a distant ancestor, living in the pre-iterator era, who decided to implement Backward from scratch.

Our imaginary ancestor doesn't work at Google, so don't project their decisions onto the Go development team. They had their own reasons — and no Jira.

1. A slice in reverse

A pleasant, sunny summer day, birds singing. You're at the keyboard as usual, and suddenly you decide to write a function for walking a slice in reverse order. Anything beats working on yet another Jira ticket.

// Backward returns the slice in reverse order.
func Backward[T any](s []T) []T {
    n := len(s)
    res := make([]T, n)
    for i := n - 1; i >= 0; i-- {
        res[n-1-i] = s[i]
    }
    return res
}

Usage example:

s := []int{11, 22, 33, 44, 55}
b := Backward(s)
fmt.Println(b)
// [55 44 33 22 11]

The implementation is simple and works reliably. There's one drawback, though: Backward creates a copy of the slice, which can be wasteful for large slices.

Besides, the sun has hidden behind a cloud, and it looks like rain is coming. You decide to work a bit more.

2. Gimme, gimme, gimme

To avoid copying the slice, you decide to return a closure that knows the current position in the original slice and returns the next element on each call:

// Backward returns a function that, on each call, returns the next
// element of the slice (in reverse order) and a flag indicating
// whether to continue iterating (false means done).
func Backward[T any](s []T) func() (T, bool) {
    i := len(s)
    return func() (T, bool) {
        if i == 0 {
            var zero T
            return zero, false
        }
        i--
        return s[i], true
    }
}

Usage example:

s := []int{11, 22, 33, 44, 55}
next := Backward(s)
for {
    v, ok := next()
    if !ok {
        break
    }
    fmt.Print(v, " ")
}
fmt.Println()
// 55 44 33 22 11

Now it allocates O(1) memory instead of O(n). That's better.

Before moving on, you glance out of the window. Yep, sure enough, the rain has started, and the sky is even cloudier than before. Excellent working weather!

3. A callback-based iterator

Something about the calling code keeps bothering you. It came out quite imperative. You'd like to hand the loop mechanics over to Backward and leave the caller with nothing but the application logic (whatever it is you do with the slice elements).

You decide to complicate Backward's signature a little. Now it will return an iterator function that takes a callback as an argument and applies it to each element of the slice:

// Backward returns a function that takes a yield callback.
// The callback is invoked for each element of the slice (in reverse order).
func Backward[T any](s []T) func(yield func(T) bool) {
    return func(yield func(T) bool) {
        for i := len(s) - 1; i >= 0; i-- {
            if !yield(s[i]) {
                return
            }
        }
    }
}

The yield function returns a bool — that's so the callback can signal when it wants to stop the traversal early.

Now you can turn the for loop body in the calling code into a callback, and you don't need the loop anymore:

work := func(x int) bool {
    if x < 30 {
        return false // early exit
    }
    fmt.Print(x, " ")
    return true
}

s := []int{11, 22, 33, 44, 55}
it := Backward(s)
it(work)
fmt.Println()
// 55 44 33

Mmm, very functional.

One small nuance: Backward's signature looks a bit heavy. You add a separate type for the return value:

// Seq is an iterator over sequences of individual values.
// When called as seq(yield), seq calls yield(v) for each value
// v in the sequence, stopping early if yield returns false.
type Seq[T any] func(yield func(T) bool)

The function looks much better now:

func Backward[T any](s []T) Seq[T] {
    // body unchanged
}

Praising yourself for inventing the iterator, you walk over to the window. It looks like the weather's gotten worse. The rain is coming down in buckets, and the sky is so overcast that it's grown as dark as evening.

4. Iterator 2: Return of the Iterator

It's all great, but then it hits you: an ordinary range over a slice returns both the index and the element's value. Your iterator returns only the value. You decide to fix this vexing oversight:

func Backward[T any](s []T) func(yield func(int, T) bool) {
    return func(yield func(int, T) bool) {
        for i := len(s) - 1; i >= 0; i-- {
            if !yield(i, s[i]) {
                return
            }
        }
    }
}

Usage example:

work := func(i int, x int) bool {
    fmt.Print(i, ":", x, " ")
    return true
}

s := []int{11, 22, 33, 44, 55}
it := Backward(s)
it(work)
fmt.Println()
// 4:55 3:44 2:33 1:22 0:11

Since the result's signature has changed, it no longer fits the Seq type. What can you do — you'll have to add a new type. After ten minutes of deliberation, you decide to call it Seq2:

// Seq2 is an iterator over sequences of key-value pairs.
// When called as seq(yield), seq calls yield(k, v) for each pair
// (k, v) in the sequence, stopping early if yield returns false.
type Seq2[K any, V any] func(yield func(K, V) bool)

func Backward[T any](s []T) Seq2[int, T] {
    // body unchanged
}

You get up to stretch your legs, and go to the window. The downpour is so heavy you can't make anything out. Lightning is flashing. Hail the size of your fist is falling — you've never seen anything like it in your life. Well, these things happen!

5. Not quite a slice

Have you thought of everything? Seems so. But you're not going back to Jira tickets just yet. Refreshing your memory of the Go spec, you realize that besides ordinary slices there are "user-defined" ones — types whose underlying type is a slice:

// IDs is a slice of identifiers.
type IDs []int

Backward works perfectly well with IDs — the compiler accepts a value of type IDs since its underlying type is []int:

ids := IDs{11, 22, 33, 44, 55}
it := Backward(ids)
it(work)
fmt.Println()
// 4:55 3:44 2:33 1:22 0:11

But what about this?

// backwardIDs builds an iterator over a slice of identifiers
// in reverse order.
var backwardIDs func(IDs) Seq2[int, int] = Backward[int]
// ERROR: cannot use Backward[int]
// (value of type func(s []int) Seq2[int, int])
// as func(IDs) Seq2[int, int] value in variable declaration

Here's where the difference between IDs and []int shows up.

When you assign the function itself, it's the signatures that get compared: func(IDs) Seq2[int, int] versus func([]int) Seq2[int, int]. Signatures match only if the parameter types are identical. But IDs and []int are different, even though one is based on the other. The signatures differ → you get an error.

Scratching your head, you turn to the spec once again and find a special generic syntax: ~T. It represents the set of all types whose underlying type is T. Just what you need!

Now you'll have to parameterize not only the element type (E) but the slice type (Slice) as well. E is needed for the returned values, while Slice lets the function accept not just []E, but any types based on it:

func Backward[Slice ~[]E, E any](s Slice) Seq2[int, E] {
    return func(yield func(int, E) bool) {
        for i := len(s) - 1; i >= 0; i-- {
            if !yield(i, s[i]) {
                return
            }
        }
    }
}

Now the example:

var backwardIDs func(IDs) Seq2[int, int] = Backward[IDs, int]

ids := IDs{11, 22, 33, 44, 55}
work := func(i int, x int) bool {
    fmt.Print(i, ":", x, " ")
    return true
}
it := backwardIDs(ids)
it(work)
fmt.Println()
// 4:55 3:44 2:33 1:22 0:11

It works! You've ended up with something similar to Backward from the slices package.

You exhale wearily and walk over to the window. The downpour and hail have given way to a hurricane. Trees and billboards go flying past. Toads, for some reason, are falling from the sky.

6. Iterator 3: Judgment Day

To take your mind off the strange events outside the window, you keep pondering.

An ordinary Backward is already great. But it would be even better if the traversal logic itself were configurable. On the other hand, if you end up with a lot of parameters, a strategy would suit better. And, by the way, it wouldn't hurt to add a factory that produces iterator factories according to given criteria...

Before you can finish the thought, the ground outside the window tears open with a deafening roar. An enormous black hand, streaming molten lava and flickering flames, bursts out of the fissure, seizes you, and drags you straight down to hell.

P.S. Despite the article's tongue-in-cheek tone, the "complicated" version in the standard library is justified (Backward just follows suite with other package functions). But if you're doing something similar in a project that solves a specific problem — it might make sense to stop at the simpler option.

• Go developers who want low-level control without having to learn another language.
• C developers who like Go's style.

At the end of the v0.2 post, I said the obvious goal for the next release was concurrency, along with the stdlib packages that support it. That's what v0.3 is about. So now has threads, channels, worker pools, mutexes, and atomics — enough tools for parallel data processing or handling network connections.

This release also adds a streaming JSON package, a bunch of safety checks (escape analysis, leak checking, nil-pointer panics, stack traces), and proper so test and so bench commands.

Threads • Channels • Worker pools • Sharing state • JSON • Safety net • Tooling • Wrapping up

Threads

The new conc package is the foundation. It provides real OS threads, backed by pthreads. If you're familiar with Go's goroutines, the code will look similar — but there are some important differences.

// greet prints a label three times.
func greet(arg any) any {
    from := arg.(string)
    for i := range 3 {
        println(from, "->", i)
    }
    return nil
}

func main() {
    // Run greet on a separate OS thread, concurrently with main.
    name := "thread"
    th := conc.Go(greet, name)

    // Wait blocks until the thread finishes.
    th.Wait()
    println("done")
}

thread -> 0
thread -> 1
thread -> 2
done

Solod doesn't support closures, so conc.Go takes a function and an any argument, instead of just a func() like you'd expect in Go.

Other important differences: starting an OS thread isn't free, and you always have to Wait on it (or Detach it), or it will leak. That makes conc.Go a good fit for a small, fixed number of long-lived threads — but not for thousands of short-lived tasks. For those cases, it's better to use a pool (shown below).

Channels

Threads in Solod communicate with each other through channels, like goroutines in Go. A channel carries values of a specific type. By default, sending or receiving on a channel blocks until both sides are ready, so a channel also works as a synchronization point.

// ping sends a single message on the given channel.
func ping(arg any) any {
    messages := arg.(*conc.Chan[string])
    messages.Send("ping")
    return nil
}

func main() {
    // An unbuffered channel (buffer size 0): each send blocks
    // until a receiver is ready to take the value.
    messages := conc.NewChan[string](mem.System, 0)
    defer messages.Free()

    // Launch a thread that sends "ping" into the channel.
    th := conc.Go(ping, &messages)
    defer th.Wait()

    // Receive the message and print it.
    var msg string
    messages.Recv(&msg)
    println(msg)
}

ping

A couple of So-specific moments here. When you create a channel, you give it an allocator (mem.System in this case), and you call Free when you're done with it. Also, Recv writes to a pointer you pass in, instead of returning the value directly. It returns a bool, which is false when the channel is closed and empty. So, a typical for msg := range ch loop in Go becomes for ch.Recv(&msg) { ... } in Solod.

Allocators are a key concept in Solod. The language doesn't allow hidden heap allocations, so any function that needs to allocate memory must take an allocator (the mem.Allocator interface) as its first argument.

Buffered channels can hold a limited number of values without having a receiver ready — just pass a non-zero size with NewChan. If you don't want to block forever, use RecvTimeout or SendTimeout with a duration. They return conc.Ok or conc.Timeout instead of getting stuck.

Worker pools

Threads are expensive, so spawning one per task doesn't scale. For handling many short-lived tasks, use conc.Pool: it uses a fixed number of worker threads that take tasks from a queue.

// job holds input and the result.
type job struct {
    id     int
    result int
}

// process handles one job.
func process(arg any) {
    j := arg.(*job)
    time.Sleep(100*time.Millisecond)
    j.result = j.id * 2
}

func main() {
    // A pool of 4 worker threads. Each submitted job is handled
    // by the next available worker.
    pool := conc.NewPool(mem.System, conc.PoolOptions{NumThreads: 4})
    defer pool.Free()

    // Submit 8 jobs. Each writes into its own struct, so keep
    // the structs alive in a slice until the jobs finish.
    start := time.Now()
    jobs := make([]job, 8)
    for i := range jobs {
        jobs[i].id = i + 1
        pool.Go(process, &jobs[i])
    }

    // Wait until all submitted jobs have finished.
    pool.Wait()

    for i := range jobs {
        println("job", jobs[i].id, "->", jobs[i].result)
    }
    elapsed := time.Since(start) / 1_000_000
    println("took", elapsed, "ms")
}

job 1 -> 2
job 2 -> 4
job 3 -> 6
job 4 -> 8
job 5 -> 10
job 6 -> 12
job 7 -> 14
job 8 -> 16
took 200 ms

pool.Wait() works similar to Go's WaitGroup.Wait — it blocks until all submitted jobs are finished. This program takes about 200 ms to run (even though there's 800 ms of total work), because 4 workers run concurrently.

You might think OS threads are much slower than Go's goroutines, but for pools, that's not the case. On realistic workloads, conc.Pool is usually only about 10% slower than Go, whether the tasks are CPU-bound or waiting on I/O. Channels are a different story: handing off work between threads requires a kernel wakeup, while Go does this in user space, so it can be several times slower. Check out Go-flavored concurrency in C for more details.

Sharing state

One way to share state in Solod is by using channels to communicate it. However, sometimes you just need a shared counter or a lock. For that, the new release introduces the sync and sync/atomic packages.

Here's an example of an atomic counter being updated by 50 tasks running on 4 threads:

// increment atomically increases the shared counter 1000 times.
func increment(arg any) {
    ops := arg.(*atomic.Uint64)
    for range 1000 {
        ops.Add(1)
    }
}

func main() {
    // An atomic value is safe for concurrent reads and writes.
    var ops atomic.Uint64

    pool := conc.NewPool(mem.System, conc.PoolOptions{NumThreads: 4})
    defer pool.Free()

    // 50 tasks, each incrementing the counter 1000 times.
    for range 50 {
        pool.Go(increment, &ops)
    }
    pool.Wait()

    println("ops:", ops.Load())
}

ops: 50000

A regular int incremented with ops++ would cause a data race and give a different result each time. Here, the result is exactly 50,000 on every run, thanks to the atomic Uint64 counter. The atomic package provides Int64, Uint64, Bool, and Pointer[T] types, all of which are lock-free and safe for concurrent use.

For anything more complex than a counter, use sync, which provides Mutex, Cond (a condition variable), and Once (runs a function exactly once). One thing to watch out for: unlike Go, a So mutex's zero value isn't ready to use — you need to Init it before locking and Free it when done.

var mu sync.Mutex
mu.Init()
defer mu.Free()

mu.Lock()
defer mu.Unlock()
// ... critical section ...

JSON

Go's encoding/json relies on reflection to marshal arbitrary structs. Solod has no reflection, and uses a different approach: a token-level API. You read and write one JSON token at a time, and the Encoder and Decoder types take care of the syntax — adding commas and colons, checking UTF-8, and rejecting bad input.

Encoding is done through a series of calls that match the structure of your document:

out := make([]byte, 256)
sb := strings.FixedBuilder(out)
enc := json.NewEncoder(&sb)

enc.BeginObject()
enc.Str("name")
enc.Str("Alice")
enc.Str("age")
enc.Int(25)
enc.EndObject()
enc.Flush()

println(sb.String())

{"name":"Alice","age":25}

Decoding pulls one validated token at a time with Next. You can check each token with Kind and read its value using typed getters like Str, Int, or Bool:

src := `{"name":"Alice","age":25}`
dec := json.NewDecoder(mem.System, []byte(src))
defer dec.Free()

var name string
var age int64

dec.Next() // the opening {
for dec.Next() && dec.Kind() == json.KindString {
    switch dec.Str() {
    case "name":
        dec.Next()
        name = dec.Str()
    case "age":
        dec.Next()
        age = dec.Int()
    default:
        dec.Next()
        dec.Skip()
    }
}

println(name, age)

Alice 25

This is a simplified example that works only because the decoder doesn't allocate any memory. In a real-world situation, you'd need to use an allocator.

The decoder works the same way whether you're using an in-memory document (NewDecoder) or reading from a stream with an io.Reader (NewReader). This means you can decode data directly from a source without having to buffer the entire message first. Both the encoder and decoder use minimal memory and will reject invalid JSON or non-UTF-8 strings.

As you can see, API is low-level and not nearly as ergonomic as it is in Go, especially when it comes to decoding. But on the bright side, it's 10 times faster and almost doesn't allocate, unlike in Go.

Safety net

Solod compiles to plain C, which is fast but not very forgiving: if you use an out-of-bounds index, dereference nil, or divide by zero, you get undefined behavior that could crash the program or silently give wrong results. The new release addresses some of these issues.

Escape analysis. Returning a pointer to a stack-allocated value is a classic C footgun. So now catches the common cases at compile time:

type Point struct{ x, y int }

func newPoint(x, y int) *Point {
    return &Point{x: x, y: y}
    //     ^ compile-time error: stack-allocated
    //       value escapes function frame
}

func main() {
    p := newPoint(3, 4)
    println(p.x, p.y)
}

so run: /tmp/sandbox/main.go:26:12: stack-allocated value escapes function frame
    return &Point{x: x, y: y}
           ^here (exit status 1)

While the escape analyzer doesn't catch every case, it's still quite useful in practice. I actually found a couple of dangling pointers in the standard library code with it, even though I was sure there weren't any.

Leak detection. Solod has no garbage collector, so a forgotten Free is a real memory leak. mem.Tracker helps catch these leaks: it wraps an allocator and keeps track of every allocation and free that goes through it. This way, you can monitor the program's memory usage in real time instead of guessing.

Wrap mem.System once, allocate memory through the tracker, and have a background thread log the stats at regular intervals:

// monitor periodically logs live allocation stats.
func monitor(arg any) any {
    t := arg.(*mem.Tracker)
    for {
        time.Sleep(100 * time.Millisecond)
        s := t.Stats()
        println("live:", s.Mallocs-s.Frees, "allocations,", s.Alloc, "bytes")
    }
    return nil
}

func main() {
    // Wrap the system allocator to count every allocation and free.
    heap := &mem.Tracker{Allocator: mem.System}

    // Watch memory from a background thread.
    conc.Go(monitor, heap).Detach()

    // Allocate through heap so the monitor sees it.
    for i := range 10 {
        v := mem.Alloc[int](heap) // intentionally not freeing it
        *v = i
        time.Sleep(50*time.Millisecond)
    }
    // ...
}

live: 2 allocations, 16 bytes
live: 4 allocations, 32 bytes
live: 6 allocations, 48 bytes
live: 8 allocations, 64 bytes
live: 10 allocations, 80 bytes

The tracker is lock-free and only uses a few atomic operations for each allocation, so it's cheap enough to keep enabled in production.

Nil-pointer panics. If you try to dereference a nil pointer, it will cause a panic at runtime instead of a raw segmentation fault:

type Rect struct{ width, height int }

func (r *Rect) area() int {
    return r.width * r.height
    //     ^ runtime error: nil pointer dereference
}

func main() {
    var r *Rect
    println(r.area())
}

panic: nil pointer dereference

Stack traces. When a program panics, the -panic flag controls what happens next:

so run -panic=trace .  # print a stack trace, then exit(1) - the default
so run -panic=exit  .  # just exit(1) after the message
so run -panic=abort .  # raise SIGABRT for a debugger or core dump

Stack trace frames represent each function in the call chain:

func main() {
    Work()
}

func Work() {
    res := Calc(42)
    println(res)
}

func Calc(x int) int {
    if x == 42 {
        panic("can't handle 42")
    }
    return x * 2
}

panic: can't handle 42
/tmp/solod_build764532392/main.c:27 (func main_Calc)
/tmp/solod_run1106942066(main_Calc+0x51)
/tmp/solod_run1106942066(main_Work+0x12)
/tmp/solod_run1106942066(main+0x9)

The same system handles assertions like slice bounds, index-out-of-range, c.Assert, and similar checks. Instead of calling C's assert, they panic in a way that respects the -panic flag.

There's also a new -sanitize flag that enables C sanitizers (address and undefined by default) to help you catch more issues during development:

so run -sanitize -panic=abort example/play

Tooling

'so test' and 'so bench'. Solod now has built-in test and benchmark runners. so test finds TestXxx(t *testing.T) functions in a package's test subdirectory, creates a runner, transpiles it, and runs it. so bench does the same for BenchmarkXxx(b *testing.B).

A typical package layout with tests and benchmarks looks like this:

so/uuid
├── bench
│   ├── main.go
│   └── uuid.go
├── test
│   ├── main.go
│   └── uuid.go
└── uuid.go

There's also a quick check for memory leaks: t.Allocator() gives you a tracking allocator (described in the 'Safety net' section above), and the test will fail if anything allocated with it isn't freed by the end of the test.

=== RUN   TestAlloc
    memory leak: 1 unfreed allocation(s), 16 byte(s)
--- FAIL: TestAlloc

Fuzzing. Since Solod is a strict subset of Go, any So package is also a valid Go package. This means you get Go's built-in fuzzer for free, making fuzz testing pretty easy. So's encoding/json package takes advantage of this by using Go's own encoding/json as an oracle, making sure that every JSON document accepted by So is also accepted by Go.

Automatic linking. The new so:link directive lets a package specify which C library it needs, and so build gathers these libraries and passes them to the C compiler. The standard packages already use the new directive, so importing so/math links with -lm, and so/sync or so/conc links with -lpthread — you no longer have to set LDFLAGS manually.

Wrapping up

With v0.3, Solod reaches an important milestone: a program can now do multiple things at once. The JSON package gives programs a standard way to communicate, and the safety checks help prevent silent failures — both during development and in production.

There's still a lot to do, of course. In the next release, the standard library will keep growing, and the language and tooling will get better to make programming in So more convenient and safe.

If you're interested, take a look at So's readme — it has everything you need to get started. Or try So online without installing anything.

I know some of you have read them, and I've received a lot of kind words from you (even some core Go team members reached out) — thank you so much for that!

Tour history: Go 1.22 • 1.23 • 1.24 • 1.25 • 1.26 + Go features by version

Unfortunately, at some point, writing these tours stopped being fun and started to feel like a part-time job. I'm not really excited about that, so I've decided to stop.

I still like Go (well, most of it). I read a lot of Go code, I write some Go code, and I write Solod code, which is also Go 🙂 (Solod is a systems language with Go syntax and a Go-like stdlib).

I'm still pretty close to the language and will probably continue to write about it.

But the interactive tours story is over.

None of that machinery exists in C. Which made me wonder: how close can you get to Go's concurrency model using only POSIX threads? Obviously, native OS threads can't match the efficiency of lightweight goroutines, but what is the actual cost, when does it become a problem, and is there any way to at least partially avoid it?

I ran into these questions while adding concurrency to Solod (So), a strict subset of Go that translates to plain C, with no runtime and no garbage collector. In the end, I came to the conclusion that you can do quite a lot with pthreads — as long as you're honest about the tradeoffs.

This post is about the POSIX threads-based concurrency model I chose, the benefits it offers, and its limitations.

Mutex/Cond • Atomics • Pool • Channel • Performance • Design • Wrapping up

Mutex/Cond

Everything in So's concurrency stack is built on two basic POSIX primitives: the mutex and the condition variable. sync.Mutex is a thin wrapper around pthread_mutex_t:

// Extracted from So's stdlib source code.
type Mutex struct {
    mu pthread_mutex_t
}

func (m *Mutex) Lock() {
    rc := pthread_mutex_lock(&m.mu)
    if rc != 0 {
        panic("sync: Mutex.Lock failed")
    }
}

Since So translates to C, this is basically a struct that holds a pthread_mutex_t and a function that calls pthread_mutex_lock. Here's the transpiler output:

// The translated C code.
typedef struct sync_Mutex {
    pthread_mutex_t mu;
} sync_Mutex;

void sync_Mutex_Lock(sync_Mutex* m) {
    int rc = pthread_mutex_lock(&m->mu);
    if (rc != 0) {
        so_panic("sync: Mutex.Lock failed");
    }
}

That is the whole translation — the generated C is a near-mechanical mirror of the So code, only noisier. From here on, I'll mainly show the So version, but I'll also provide the C code for those who are interested.

There's nothing exciting here: sync.Mutex is a pthread mutex wrapper that panics if something goes wrong (which is rare).

The companion primitive is sync.Cond, a wrapper around pthread_cond_t. It's the standard "wait until a condition holds" tool, associated with a mutex:

type Cond struct           // wraps pthread_cond_t + pthread_mutex_t
func (c *Cond) Wait()      // wraps pthread_cond_wait
func (c *Cond) Signal()    // wraps pthread_cond_signal
func (c *Cond) Broadcast() // wraps pthread_cond_broadcast

typedef struct sync_Cond {
    pthread_cond_t cond;
    sync_Mutex*    mu;
} sync_Cond;

void sync_Cond_Wait(sync_Cond* c);      // wraps pthread_cond_wait
void sync_Cond_Signal(sync_Cond* c);    // wraps pthread_cond_signal
void sync_Cond_Broadcast(sync_Cond* c); // wraps pthread_cond_broadcast

These two types — Mutex and Cond — are the foundation. Other concurrency tools — Once, the thread pool, channels — are built using a mutex and one or more condition variables. This has several effects on performance, as we'll see later.

Atomics

Not everything needs a lock. So's sync/atomic mirrors Go's: Bool, Int32, Int64, Uint32, Uint64, and a generic Pointer[T], all with Load, Store, Swap, and CompareAndSwap methods.

The nice thing is that these don't need pthreads at all. They map directly to the C compiler's __atomic builtins — the same hardware instructions that Go's compiler emits. So there's no reason for them to be any slower, and they're not:

Each number is the cost of one operation on a single thread.

sync.Once is a good example of using atomics effectively. Its fast path only needs a single atomic load — after the given function runs, every future call to Do checks a flag and returns:

type Once struct {
    mu   Mutex
    done atomic.Bool
}

// Do calls f if and only if Do is being called
// for the first time for this o.
func (o *Once) Do(f func()) {
    if o.done.Load() { // lock-free fast path
        return
    }
    // slow path...
}

typedef struct sync_Once {
    sync_Mutex mu;
    atomic_Bool done;
} sync_Once;

// Do calls f if and only if Do is being called
// for the first time for this o.
void sync_Once_Do(sync_Once* o, void (*f)()) {
    if (atomic_Bool_Load(&o->done)) { // lock-free fast path
        return;
    }
    // slow path...
}

Worker pool

To actually run code concurrently, you need threads. The conc.Thread type wraps pthread_t and its related functions:

type Thread struct          // wraps pthread_t
func (th Thread) Wait() any // wraps pthread_join
func (th Thread) Detach()   // wraps pthread_detach

typedef struct conc_Thread {
    pthread_t t;
} conc_Thread;

void* conc_Thread_Wait(conc_Thread th);   // wraps pthread_join
void  conc_Thread_Detach(conc_Thread th); // wraps pthread_detach

Consider this conc.Go function:

// Go launches an OS thread that runs fn(arg) and returns a handle to it.
func Go(entry func(any) any, arg any) Thread {
    var th Thread
    rc := pthread_create(&th.t, nil, entry, arg)
    // ...
}

// Go launches an OS thread that runs fn(arg) and returns a handle to it.
// `any` in So translates to `void*` in C.
conc_Thread conc_Go(void* (*entry)(void*), void* arg) {
    conc_Thread th = {0};
    int rc = pthread_create(&th.t, NULL, entry, arg);
    // ...
}

Usage example:

func work(arg any) any {
    acc := arg.(*Account)
    // ...
}

func main() {
    var acc Account
    th := conc.Go(work, &acc)
    // ... do other work concurrently ...
    th.Wait() // work is complete once Wait returns
}

void* work(void* arg) {
    main_Account* acc = (main_Account*)arg;
    // ...
}

int main(void) {
    main_Account acc = {0};
    conc_Thread th = conc_Go(work, &acc);
    // ... do other work concurrently ...
    conc_Thread_Wait(th); // work is complete once Wait returns
}

It might look like go work(&acc), but that's just on the surface. conc.Go starts an actual OS thread, not a goroutine. You have to eventually call Wait to join or Detach it, or else its resources will leak. Also, OS threads are expensive to create — they're nothing like Go's goroutines, which only need a few kilobytes of stack and start up in nanoseconds.

That's exactly why you usually don't want to call Go inside a loop. For tasks that are short-lived or happen often, it's better to use a pool of long-lived worker threads and send tasks to them.

conc.Pool to the rescue:

     Worker thread pool in So
┌────────┐ ┌────────┐   ┌────────┐
│ Task 1 │ │ Task 2 │...│ Task M │  M tasks
└────────┘ └────────┘   └────────┘
┌────────────────────────────────┐
│           conc.Pool            │  coordinator
└────────────────────────────────┘
┌────────┐ ┌────────┐   ┌────────┐
│ Thrd 1 │ │ Thrd 2 │...│ Thrd N │  N threads, N << M
└────────┘ └────────┘   └────────┘
┌────────────────────────────────┐
│          OS scheduler          │
└────────────────────────────────┘

Usage example:

type Task struct {
    in  int
    out int
}

func square(arg any) {
    task := arg.(*Task)
    task.out = task.in * task.in
}

func main() {
    tasks := make([]Task, 10)

    opts := conc.PoolOpts{NumThreads: 2}
    pool := conc.NewPool(mem.System, opts)
    defer pool.Free()

    for i := range tasks {
        tasks[i].in = i
        pool.Go(square, &tasks[i])
    }
    pool.Wait()
}

typedef struct main_Task {
    so_int in;
    so_int out;
} main_Task;

void square(void* arg) {
    main_Task* task = (main_Task*)arg;
    task->out = task->in * task->in;
}

int main(void) {
    so_Slice tasks = so_make_slice(main_Task, 10, 10);

    conc_PoolOpts opts = (conc_PoolOpts){.NumThreads = 2};
    conc_Pool* pool = conc_NewPool(mem_System, opts);

    for (so_int i = 0; i < so_len(tasks); i++) {
        // so_at is a generic macro to get the i-th element of a
        // specific type (main_Task here) from a type-erased slice.
        // Here we're getting the i-th task from the tasks slice.
        so_at(main_Task, tasks, i).in = i;
        conc_Pool_Go(pool, square, &so_at(main_Task, tasks, i));
    }
    conc_Pool_Wait(pool);
    conc_Pool_Free(pool);
}

The first argument to NewPool, mem.System, is a memory allocator. Solod avoids hidden allocations, so anything that needs memory takes an allocator explicitly — here it backs the pool's task queue.

Under the hood, a Pool is a fixed group of worker threads that pull tasks from a shared queue (a ring buffer). It uses one mutex and a few condition variables:

// Pool is a bounded pool of worker threads with a wait queue
// which execute tasks of the form func(any).
type Pool struct {
    alloc mem.Allocator

    mu       sync.Mutex
    notEmpty sync.Cond // signaled when a task is enqueued
    notFull  sync.Cond // signaled when a slot frees
    allDone  sync.Cond // broadcast when no task is in flight

    workers []Thread
    queue   []task // ring buffer of submitted tasks
    active  int    // tasks submitted but not yet finished
    stopped bool   // set by Free to drain and exit
}

// NewPool creates a pool with a given number
// of worker threads and starts them.
func NewPool(alloc mem.Allocator, opts PoolOpts) *Pool

// Go submits a task for execution, blocking while the queue is full.
func (p *Pool) Go(fn func(any), arg any)

// Wait blocks until all submitted tasks finish.
func (p *Pool) Wait()

// Pool is a bounded pool of worker threads with a wait queue
// which execute tasks of the form func(any).
typedef struct conc_Pool {
    mem_Allocator alloc;

    sync_Mutex mu;
    sync_Cond  notEmpty; // signaled when a task is enqueued
    sync_Cond  notFull;  // signaled when a slot frees
    sync_Cond  allDone;  // broadcast when no task is in flight

    so_Slice workers;
    so_Slice queue;      // ring buffer of submitted tasks
    so_int   active;     // tasks submitted but not yet finished
    bool     stopped;    // set by Free to drain and exit
} conc_Pool;

conc_Pool* conc_NewPool(mem_Allocator alloc, conc_PoolOpts opts);
void       conc_Pool_Go(conc_Pool* p, void (*fn)(void*), void* arg);
void       conc_Pool_Wait(conc_Pool* p);

notEmpty wakes up a worker when there are tasks to do, notFull applies back-pressure when the queue is full, and allDone lets Wait know when everything is finished. It's a classic producer-consumer setup, about 200 lines of code, and there's nothing fancy about it.

The heart of the pool is the worker loop. Each thread blocks until a task appears, runs it outside the lock so workers execute in parallel, then records that it finished:

// workerMain runs on every pool thread: pull a task, run it, repeat.
func workerMain(arg any) any {
    p := arg.(*Pool)
    for {
        p.mu.Lock()
        for p.qempty() && !p.stopped {
            p.notEmpty.Wait() // sleep until a task is enqueued
        }
        if p.qempty() && p.stopped {
            p.mu.Unlock()
            break // queue drained and pool shutting down
        }
        t := p.qpop()
        p.notFull.Signal() // a slot freed for a waiting submitter
        p.mu.Unlock()

        t.fn(t.arg) // run the task with the lock released

        p.mu.Lock()
        p.active--
        if p.active == 0 {
            p.allDone.Broadcast() // wake anyone parked in Wait
        }
        p.mu.Unlock()
    }
    return nil
}

// workerMain runs on every pool thread: pull a task, run it, repeat.
static void* workerMain(void* arg) {
    conc_Pool* p = (conc_Pool*)arg;
    for (;;) {
        sync_Mutex_Lock(&p->mu);
        for (; conc_Pool_qempty(p) && !p->stopped;) {
            sync_Cond_Wait(&p->notEmpty); // sleep until a task is enqueued
        }
        if (conc_Pool_qempty(p) && p->stopped) {
            sync_Mutex_Unlock(&p->mu);
            break; // queue drained and pool shutting down
        }
        task t = conc_Pool_qpop(p);
        sync_Cond_Signal(&p->notFull); // a slot freed for a waiting submitter
        sync_Mutex_Unlock(&p->mu);

        t.fn(t.arg); // run the task with the lock released

        sync_Mutex_Lock(&p->mu);
        p->active--;
        if (p->active == 0) {
            sync_Cond_Broadcast(&p->allDone); // wake anyone parked in Wait
        }
        sync_Mutex_Unlock(&p->mu);
    }
    return NULL;
}

This is what separates a pool from a plain queue. Pool.Go bumps active as it enqueues; each worker decrements it after running a task, and the last one out broadcasts allDone.

Pool.Wait sleeps until the count hits zero:

// Wait blocks until every submitted task has finished.
func (p *Pool) Wait() {
    p.mu.Lock()
    for p.active != 0 {
        p.allDone.Wait()
    }
    p.mu.Unlock()
}

// Wait blocks until every submitted task has finished.
void conc_Pool_Wait(conc_Pool* p) {
    sync_Mutex_Lock(&p->mu);
    for (; p->active != 0;) {
        sync_Cond_Wait(&p->allDone);
    }
    sync_Mutex_Unlock(&p->mu);
}

The tradeoff is that the number of worker threads is fixed. In Go, a program can handle thousands of concurrent I/O waits because blocked goroutines use very little memory. A So pool can't do this — if all N workers are parked on a blocking syscall, the pool is stalled until one returns. You have to set the pool size based on the workload, instead of letting the runtime manage it for you.

Channel

Channels are an important part of Go's concurrency model, and So's conc.Chan[T] gives you something quite similar. Just like in Go, it passes values by copy and comes in buffered and unbuffered flavors:

ch := conc.NewChan[int](mem.System, 2) // buffered, capacity 2
defer ch.Free()

// Producer on its own thread.
prod := producer{ch: &ch, n: 5}
thr := conc.Go(produce, &prod)
defer thr.Wait()

// Consume until the channel is closed and drained.
var v int
for ch.Recv(&v) {
    fmt.Printf("received %d\n", v)
}

// conc_NewChan, conc_Chan_Recv, and friends are generic macros:
// the element type (so_int here) is passed as the first argument.
conc_Chan ch = conc_NewChan(so_int, mem_System, 2); // buffered, capacity 2

// Producer on its own thread.
producer prod = (producer){.ch = &ch, .n = 5};
conc_Thread thr = conc_Go(produce, &prod);

// Consume until the channel is closed and drained.
so_int v = 0;
for (; conc_Chan_Recv(so_int, &ch, &v);) {
    fmt_Printf("received %d\n", v);
}

conc_Thread_Wait(thr);
conc_Chan_Free(so_int, &ch);