Threading

Classes
struct	clod_process_opts

Macros
#define	CLOD_SPINLOCK_INIT   0
#define	CLOD_ONCE_INIT   0
#define	CLOD_ONCE(once)
#define	CLOD_MUTEX_INIT   0

Typedefs
typedef int	clod_process_main(int argc, char **argv)
typedef uintptr_t	clod_process
typedef char	clod_spinlock
typedef char	clod_once
typedef int	clod_mutex

Enumerations
enum	clod_process_type { CLOD_THREAD = 1 , CLOD_THREAD_BACKGROUND = 2 , CLOD_DAEMON = 3 }
enum	clod_process_result { CLOD_PROCESS_OK = 0 , CLOD_PROCESS_INVALID = 1 , CLOD_PROCESS_NO_MEMORY = 2 , CLOD_PROCESS_UNSUPPORTED = 3 }

Functions
enum clod_process_result	clod_process_start (struct clod_process_opts *opts, clod_process *process_out)
enum clod_process_result	clod_process_join (clod_process process)
void	clod_spinlock_lock (clod_spinlock *spinlock)
void	clod_spinlock_unlock (clod_spinlock *spinlock)
bool	clod_once_do (clod_once *once)
void	clod_once_done (clod_once *once)
int64_t	clod_timer (int64_t *time, int64_t duration_us)
void	clod_mutex_lock (clod_mutex *mutex)
void	clod_mutex_unlock (clod_mutex *mutex)

Detailed Description

Threading API. Implements threading from scratch, but since doing so forfeits the use of libc, also wraps libc threading APIs.

Macro Definition Documentation

CLOD_SPINLOCK_INIT

#define CLOD_SPINLOCK_INIT   0

Definition at line 121 of file thread.h.

CLOD_ONCE_INIT

#define CLOD_ONCE_INIT   0

Definition at line 136 of file thread.h.

CLOD_ONCE

#define CLOD_ONCE

(

once

)

Value:

for (bool _do_once = clod_once_do(once); _do_once; clod_once_done(once), _do_once = false)

Definition at line 138 of file thread.h.

CLOD_MUTEX_INIT

#define CLOD_MUTEX_INIT   0

Definition at line 189 of file thread.h.

Typedef Documentation

clod_process_main

typedef int clod_process_main(int argc, char **argv)

Definition at line 73 of file thread.h.

clod_process

typedef uintptr_t clod_process

Definition at line 102 of file thread.h.

clod_spinlock

typedef char clod_spinlock

Simple spinlock. Should never be copied.

Definition at line 124 of file thread.h.

clod_once

typedef char clod_once

Perform a function once and only once.

Definition at line 141 of file thread.h.

clod_mutex

typedef int clod_mutex

Simple mutex.

Definition at line 188 of file thread.h.

Enumeration Type Documentation

clod_process_type

enum clod_process_type

Enumerator
CLOD_THREAD	The most typical kind of "thread", implemented using a standard threading API if one is found, with a fallback to libclod's own threading implementation if not. It shares memory, files, signals and other OS resources and contexts. Libclod explicitly avoids re-implementing anything with this type to facilitate compatability with runtimes that make assumptions about the execution environment's context that may be broken by a custom implementation.
CLOD_THREAD_BACKGROUND	Similar to CLOD_THREAD, but receives a new PID. It shares memory, files, signals and other OS resources and contexts. When the parent process dies it dies too, but it is not interrupted by the debugger or other signals. It is intended for use as a background task runner that is tied to the calling process's lifetime but otherwise wants autonomy. Note Libclod does not attempt to replicate the exact thread-local storage data structures that any libc implementation might be using, and as such the execution environment is incompatible with libc. The thread local storage (i.e. FS register on x86_64) is explicitly pointed to invalid memory to reflect this.
CLOD_DAEMON	Doesn't fall into the common concepts of a thread or process. Shares memory and open file handles, but does not share signals or other OS resources. The new execution environment attempts to be as thread-ish as possible, but receives a new PID and does not exit when the parent does. It is intended for use as a watchdog or background task runner. Note Libclod does not attempt to replicate the exact thread-local storage data structures that any libc implementation might be using, and as such the execution environment is incompatible with libc. The thread local storage (i.e. FS register on x86_64) is explicitly pointed to invalid memory to reflect this. When the parent dies, it may leave shared memory in an inconsistent state. Extreme care must be taken to ensure correctness if dealing with shared data. One should note that many C stdlib methods deal with shared memory internally, and larger runtimes (i.e. Golang, JVM) have no chance of functioning following the parent's death. In general, one would want to set up the child to receive a signal on the parent's death, and only perform some minimal operations before exiting itself.

Definition at line 25 of file thread.h.

clod_process_result

enum clod_process_result

Definition at line 66 of file thread.h.

Function Documentation

clod_process_start()

enum clod_process_result clod_process_start	(	struct clod_process_opts *	opts,
		clod_process *	process_out )

Create a new execution environment.

Parameters

[in]	opts	Configuration options.
[out]	process_out	(nullable) Handle to the new execution environment.

Returns

Result of the operation.

Definition at line 10 of file thread.c.

clod_process_join()

enum clod_process_result clod_process_join

(

clod_process

process

)

Wait for an execution environment to stop.

Parameters

[in]

process

Execution environment to wait for.

Returns

Result of the operation.

Definition at line 39 of file thread.c.

clod_spinlock_lock()

void clod_spinlock_lock

(

clod_spinlock *

spinlock

)

Lock a spinlock.

Parameters

spinlock

The spinlock to lock.

Definition at line 5 of file spinlock.c.

clod_spinlock_unlock()

void clod_spinlock_unlock

(

clod_spinlock *

spinlock

)

Unlock a spinlock.

Parameters

spinlock

The spinlock to lock.

Definition at line 26 of file spinlock.c.

clod_once_do()

bool clod_once_do

(

clod_once *

once

)

Returns true only once. All other calls block until clod_once_done is called following the return of true.

Parameters

[in]

once

Meeting point for threads.

Returns

True for the first call, false for all subsequent calls.

Definition at line 10 of file once.c.

clod_once_done()

void clod_once_done

(

clod_once *

once

)

Mark the value as done.

Parameters

[in]

once

Meeting point for threads.

Definition at line 38 of file once.c.

clod_timer()

int64_t clod_timer	(	int64_t *	time,
		int64_t	duration_us )

Multi-use time function. Can be used to get the current time, wait for a specific time in the future, wait some duration from the current time or easily implement a repeating task that avoids time drift.

for (int64_t time = clod_timer(nullptr, 0); true; clod_timer(&time, PERIOD_US)) {
    do_work();
}

Note

Simply reusing the same time value will result in a timer implementation that will not drift in theory, but in practice a task might be slow and the timer might fall behind. In such a case, the no-drift semantics mean that the timer will attempt to catch up, returning immediately many times until it has caught up with the current time. If this is not intended, the one can do

if (return_val > time) time = return_val; 

to implement a timer that will drift and maintain the same cadence instead of trying to catch back up.

Parameters

[in,out]	time	(nullable) Time in microseconds from an undefined epoch. If time is null, the method simply waits for duration_us. The duration is added to the value in time, unless the method is interrupted by a signal or an error occurs, in which case time is not updated. If time is null it does not return when interrupted by a signal.
[in]	duration_us	Duration after time to wait for. If duration_us is <= 0, it simply returns the current time.

Returns

The time at which the method was entered.

Definition at line 214 of file timer.c.

clod_mutex_lock()

void clod_mutex_lock

(

clod_mutex *

mutex

)

Lock a mutex. It does not support recursive locking.

Parameters

[in]

mutex

Mutex to lock.

Returns

True on success, false on failure. Failure is likely due to lack of resources.

Definition at line 12 of file mutex.c.

clod_mutex_unlock()

void clod_mutex_unlock

(

clod_mutex *

mutex

)

Unlock a mutex.

Parameters

[in]

mutex

Mutex to unlock.

Definition at line 32 of file mutex.c.