Jacket
#import "Thread";
Threads and what they need to cooperate: Thread to run a procedure on its own thread, Mutex, Condition_Variable
and Semaphore to coordinate, and Thread_Group for a pool of workers.
Not available on wasm: it has no operating-system threads.
Shared :: struct { mutex: Mutex; total: int; }
add_many :: (thread: *Thread) -> s64 {
shared := cast(*Shared) thread.data;
for 1..1000 {
lock(*shared.mutex);
shared.total += 1;
unlock(*shared.mutex);
}
return 0;
}
shared: Shared;
init(*shared.mutex);
threads: [4] Thread;
for *thread: threads {
assert(thread_init(thread, add_many));
thread.data = *shared;
thread_start(thread);
}
for *thread: threads {
assert(thread_is_done(thread, -1));
thread_deinit(thread);
}
assert(shared.total == 4000);
destroy(*shared.mutex);Thread_Group.false.Prepares thread to run proc. Start it with thread_start. Returns false when proc is null, the storage size is
negative or an allocation fails.
hello :: (thread: *Thread) -> s64 { return 0; }
thread: Thread;
assert(thread_init(*thread, hello, name = "hello"));
thread_start(*thread);
assert(thread_is_done(*thread, -1));
thread_deinit(*thread);Sets up a mutex. It is recursive: the thread that holds it can lock it again, and has to unlock it as many times.
Releases the resources of a mutex. It must be unlocked.
Takes the mutex, waiting until no other thread holds it. Pair every lock with an unlock.
Gives the mutex back. Call it from the thread that locked it.
Locks the raw operating-system critical section behind a Mutex. Prefer lock.
Unlocks a critical section locked with csection_lock.
Waits on a raw operating-system condition variable, giving up after wait_time_ms (never, when negative). Prefer
wait.
Wakes one waiter on a raw operating-system condition variable. Prefer wake.
Wakes every waiter on a raw operating-system condition variable. Prefer wake_all.
Waits on c until another thread calls wake or wake_all. It can return without either, so check the condition again afterwards.
Wakes one thread waiting on c, if any. Change the shared state under the mutex first; see wait for an example.
Wakes every thread waiting on c.
Adds one count to the semaphore, waking a thread blocked in wait_for.
Takes one count from the semaphore, waiting for signal if there is none. The result says whether it got one: .SUCCESS,
.TIMEOUT or .ERROR.
Lets a thread set up with thread_init begin running its procedure.
Whether thread has finished.
count := 0;
worker :: (thread: *Thread) -> s64 {
(cast(*int) thread.data).* = 7;
return 0;
}
thread: Thread;
assert(thread_init(*thread, worker));
thread.data = *count;
thread_start(*thread);
assert(thread_is_done(*thread, -1)); // wait for it
thread_deinit(*thread);
assert(count == 7);Cleans up after a thread that has finished. Wait for it first with thread_is_done(*thread, -1); after this the Thread
can be reused or dropped.
Starts the workers of group. Work added before this waits in the queues. Calling it again does nothing.
Queues work for one of the group's workers; group_proc receives the same pointer. The work must stay valid until it
comes back from get_completed_work. Send work to a group that has been set up and not shut down.
The pointers of the work finished since the last call, in temporary storage. Empty when none has.
Stops the workers after they finish what is queued and frees the group. Returns false if they did not all stop within
timeout_milliseconds (-1 waits as long as it takes).
Waits until every piece of work added to group has been run by a worker, or until timeout_milliseconds pass (-1 waits as
long as it takes). Returns false on a timeout. The group has to be started, and has to have a live worker to run the work:
if every worker stopped with work still queued, only a timeout ends the wait.
Counter :: struct { mutex: Mutex; total: s64; }
count :: (group: *Thread_Group, thread: *Thread, work: *void) -> Thread_Continue_Status {
counter := cast(*Counter) group.data;
lock(*counter.mutex);
counter.total += 1;
unlock(*counter.mutex);
return .CONTINUE;
}
counter: Counter;
init(*counter.mutex);
group: Thread_Group;
group.logging = false;
init(*group, 4, count);
group.data = *counter;
start(*group);
for 1..100 add_work(*group, null);
assert(wait_for_all(*group));
assert(counter.total == 100);
assert(shutdown(*group));
destroy(*counter.mutex);What wait_for returns: .SUCCESS when it took a count, .TIMEOUT when the time ran out and .ERROR when the wait failed.
A lock that lets one thread at a time into a piece of code. Set it up with init, take it with lock, give it back with
unlock. It can be locked again by the thread that already holds it.
Lets a thread sleep until another thread says the shared state changed. Use it with a Mutex: wait releases the mutex
while sleeping, and wake or wake_all end the sleep.
A counter threads can wait on. signal adds one; wait_for takes one, waiting if there are none. Handy for handing work
between threads.
An operating-system thread. Set it up with thread_init, fill in data if the procedure needs it, run it with
thread_start, wait with thread_is_done and clean up with thread_deinit. The Thread must stay where it is until
thread_deinit. The procedure gets a pointer to it, with data, the thread's index and its own temporary storage.
What a Thread_Group procedure returns after one piece of work: .CONTINUE for more, .STOP to end that worker.
A pool of worker threads that run one procedure over pieces of work. Set it up with init, queue work with add_work,
start the workers and collect results with get_completed_work. shutdown stops the workers.
start to run something on each worker thread, once, before its first piece of work. worker_index is the
worker's place in the group, 0 up to the number of threads minus one. A good place to build state the worker keeps.wait_for_all sleeps on.Work :: struct { input: int; result: int; }
square :: (group: *Thread_Group, thread: *Thread, work: *void) -> Thread_Continue_Status {
item := cast(*Work) work;
item.result = item.input * item.input;
return .CONTINUE;
}
group: Thread_Group;
group.logging = false;
init(*group, 2, square);
items: [4] Work;
for *item, i: items {
item.input = i + 1;
add_work(*group, item);
}
start(*group);
assert(wait_for_all(*group));
assert(get_completed_work(*group).count == items.count);
assert(shutdown(*group));
assert(items[3].result == 16);A rank for a mutex, kept in debug builds.
The number of a thread, as in context.thread_index.
What thread_deinit says when the thread is still running or was never started.