Processes, Threads, and Locks with iodine spoon

Reference the Linux x86_64 process, thread, and futex mutex helpers in iodine’s spoon library.

The iodine/spoon.ih library contains Linux x86_64 helpers for process creation, thread creation, thread synchronization, and futex-based mutexes. It uses raw Linux syscalls and manages thread stacks and thread-local storage itself.

Treat this library as experimental low-level code. It creates processes and threads, allocates stacks and TLS storage, and calls Linux syscalls directly. Test it in a disposable program before using it in an application.

Process helpers

Function	Description
fork_p()	Invoke Linux fork and return the raw result.
execve(filename, argv, envp)	Invoke Linux execve with the supplied path, argument vector, and environment vector.
wait_pid(pid, status, options)	Invoke Linux wait4/waitpid-style syscall 61 for a process ID.
getpid_p()	Return the current process ID.
gettid_p()	Return the current thread ID.
food()	Return zero in a fork child or non-main thread, and nonzero in the parent/main thread.
spoon(path)	Fork and attempt to execute path in the child. Returns the raw fork result in each process.

spoon(path) builds a one-element argument vector containing path and passes a null environment pointer. It does not provide a way to supply additional command-line arguments or a custom environment.

using spoon from <iodine/spoon>;
using food from <iodine/spoon>;
using printd from <iodine/printd>;
expose spoon;
expose food;
expose printd;

int main() {
    int pid = spoon("/usr/bin/true");
    if (food()) {
        printd("Child process id: %d", pid);
    }
    return 0;
}

The sample assumes the executable exists. The library does not report a distinct execve failure through a documented error API.

Thread helpers

Function	Description
spawn_spoon()	Call the thread-spawn overload with a count of one.
spawn_spoon(count)	Create threads using Linux clone flags and allocate stack and TLS storage for them.
spoon_sync()	Iterate tracked thread entries, attempt to wait for them, and free their stored stack, TLS, and TID allocations.

The spawned threads continue execution from the point of creation. Use food() to distinguish the main thread from threads created by spawn_spoon.

In the current implementation, a child created inside spawn_spoon(count) continues through the remaining iterations of the same loop. Counts greater than one can therefore create additional descendants rather than exactly count total threads. The tracking and synchronization code is also low-level; verify its behavior for your workload.

Mutex helpers

The mutex API uses an int as its lock word:

Function	Description
mtx_init(m)	Set the lock word to zero.
mtx_lock(m)	Acquire the lock using an atomic exchange and futex wait.
mtx_unlock(m)	Clear the lock word and wake one futex waiter.
mtx_destroy(m)	Reset the lock word to zero.

using mtx_init from <iodine/spoon>;
using mtx_lock from <iodine/spoon>;
using mtx_unlock from <iodine/spoon>;
expose mtx_init;
expose mtx_lock;
expose mtx_unlock;

int main() {
    int lock;
    mtx_init(&lock);
    mtx_lock(&lock);
    // Protect shared work here.
    mtx_unlock(&lock);
    return 0;
}

This is a minimal usage sketch, not a complete shared-state threading example. The mutex helpers do not provide a separate owner, timeout, or error-reporting API.

Low-level wrappers and internal state

The library also defines internal assembly wrappers for clone, atomic exchange, and futex wait/wake operations. Its _sp namespace stores a fixed table for up to 64 tracked threads and the associated stacks, TLS regions, and TID areas.

The source is available in plstd/spoon.plib. This .plib source is documented as iodine/spoon.ih.