> ## Documentation Index
> Fetch the complete documentation index at: https://hypotenuse.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/MaimingyouRnlwkey/Hypotenuse-in-C-Triangle/blob/main/plstd/spoon.plib) 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.

<Warning>
  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.
</Warning>

## 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.

```c theme={null}
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`.

<Warning>
  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.
</Warning>

## 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. |

```c theme={null}
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`](https://github.com/MaimingyouRnlwkey/Hypotenuse-in-C-Triangle/blob/main/plstd/spoon.plib). This `.plib` source is documented as `iodine/spoon.ih`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.