thread.h File Reference

srn_thread_t, srn_mutex_t, and srn_cond_t model the thread-level operations the runtime needs, with semantics defined here rather than borrowed from one OS API. More...

#include <pthread.h>

Include dependency graph for thread.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	srn_thread_t
struct	srn_mutex_t
struct	srn_cond_t

Typedefs
typedef struct srn_thread_t	srn_thread_t
typedef struct srn_mutex_t	srn_mutex_t
typedef struct srn_cond_t	srn_cond_t
typedef enum srn_thread_status_t	srn_thread_status_t
	Result of a thread operation.

Enumerations
enum	srn_thread_status_t {   SRN_THREAD_OK = 0 , SRN_THREAD_AGAIN , SRN_THREAD_NOMEM , SRN_THREAD_PERM ,   SRN_THREAD_ERROR }
	Result of a thread operation. More...

Functions
srn_thread_status_t	srn_thread_spawn (srn_thread_t *t, void(*fn)(void *), void *arg)
	Run fn(arg) on a new OS thread.
srn_thread_status_t	srn_thread_join (srn_thread_t *t)
	Block until the thread started for t returns.
srn_thread_status_t	srn_mutex_init (srn_mutex_t *m)
srn_thread_status_t	srn_mutex_lock (srn_mutex_t *m)
srn_thread_status_t	srn_mutex_unlock (srn_mutex_t *m)
srn_thread_status_t	srn_mutex_destroy (srn_mutex_t *m)
	Release a mutex's resources.
srn_thread_status_t	srn_cond_init (srn_cond_t *c)
srn_thread_status_t	srn_cond_wait (srn_cond_t *c, srn_mutex_t *m)
	Release m, sleep until notified, then re-acquire m before returning.
srn_thread_status_t	srn_cond_notify_one (srn_cond_t *c)
	Wake one waiter.
srn_thread_status_t	srn_cond_notify_all (srn_cond_t *c)
	Wake every waiter.
srn_thread_status_t	srn_cond_destroy (srn_cond_t *c)
	Release a condition's resources.

Detailed Description

srn_thread_t, srn_mutex_t, and srn_cond_t model the thread-level operations the runtime needs, with semantics defined here rather than borrowed from one OS API.

The status enum and the operation signatures below are platform-neutral. Only the type realizations differ per platform, so each backend defines the three types over its own primitives inside the matching branch. pthreads back them on POSIX. A Windows backend realises the same operations on the Win32 API directly, so neither platform emulates the other. The types are thin wrappers so they embed inline in another struct rather than needing a separate allocation.

Bear in mind that, we only expose what we need. THIS IS NOT A GENERICE THREAD INTERFACE.

Definition in file thread.h.

Typedef Documentation

srn_cond_t

typedef struct srn_cond_t srn_cond_t

srn_mutex_t

typedef struct srn_mutex_t srn_mutex_t

srn_thread_status_t

typedef enum srn_thread_status_t srn_thread_status_t

Result of a thread operation.

Each backend maps its own error space onto these, so a caller never sees a pthread or Win32 code.

srn_thread_t

typedef struct srn_thread_t srn_thread_t

Enumeration Type Documentation

srn_thread_status_t

enum srn_thread_status_t

Result of a thread operation.

Each backend maps its own error space onto these, so a caller never sees a pthread or Win32 code.

Enumerator
SRN_THREAD_OK
SRN_THREAD_AGAIN	The system lacked the resources to start the thread, such as a per-process thread limit. Retrying after others exit may succeed.
SRN_THREAD_NOMEM	Out of memory.
SRN_THREAD_PERM	The caller lacks permission for the requested operation.
SRN_THREAD_ERROR	A failure the backend could not map to the above.

Definition at line 61 of file thread.h.

                                 {
  SRN_THREAD_OK = 0,
  /// The system lacked the resources to start the thread, such as a per-process
  /// thread limit. Retrying after others exit may succeed.
  SRN_THREAD_AGAIN,
  /// Out of memory.
  SRN_THREAD_NOMEM,
  /// The caller lacks permission for the requested operation.
  SRN_THREAD_PERM,
  /// A failure the backend could not map to the above.
  SRN_THREAD_ERROR,
} srn_thread_status_t;

Function Documentation

srn_cond_destroy()

srn_thread_status_t srn_cond_destroy

(

srn_cond_t *

c

)

Release a condition's resources.

It must have no waiters, and must not be used again without a fresh srn_cond_init.

Definition at line 160 of file thread_posix.c.

                                                    {
  PANIC_IF_NULL(c);
  int rc = pthread_cond_destroy(&c->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_cond_destroy failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_cond_init()

srn_thread_status_t srn_cond_init

(

srn_cond_t *

c

)

Definition at line 123 of file thread_posix.c.

                                                 {
  PANIC_IF_NULL(c);
  int rc = pthread_cond_init(&c->handle, nullptr);
  if (rc != 0) {
    THREAD_LOG("pthread_cond_init failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_cond_notify_all()

srn_thread_status_t srn_cond_notify_all

(

srn_cond_t *

c

)

Wake every waiter.

Definition at line 151 of file thread_posix.c.

                                                       {
  PANIC_IF_NULL(c);
  int rc = pthread_cond_broadcast(&c->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_cond_broadcast failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_cond_notify_one()

srn_thread_status_t srn_cond_notify_one

(

srn_cond_t *

c

)

Wake one waiter.

Definition at line 142 of file thread_posix.c.

                                                       {
  PANIC_IF_NULL(c);
  int rc = pthread_cond_signal(&c->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_cond_signal failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_cond_wait()

srn_thread_status_t srn_cond_wait	(	srn_cond_t *	c,
		srn_mutex_t *	m )

Release m, sleep until notified, then re-acquire m before returning.

A wait can wake spuriously, so the caller must re-check its predicate in a loop.

Definition at line 132 of file thread_posix.c.

                                                                 {
  PANIC_IF_NULL(c);
  PANIC_IF_NULL(m);
  int rc = pthread_cond_wait(&c->handle, &m->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_cond_wait failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mutex_destroy()

srn_thread_status_t srn_mutex_destroy

(

srn_mutex_t *

m

)

Release a mutex's resources.

The mutex must be unlocked and have no waiters, and must not be used again without a fresh srn_mutex_init.

Definition at line 114 of file thread_posix.c.

                                                      {
  PANIC_IF_NULL(m);
  int rc = pthread_mutex_destroy(&m->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_mutex_destroy failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mutex_init()

srn_thread_status_t srn_mutex_init

(

srn_mutex_t *

m

)

Definition at line 87 of file thread_posix.c.

                                                   {
  PANIC_IF_NULL(m);
  int rc = pthread_mutex_init(&m->handle, nullptr);
  if (rc != 0) {
    THREAD_LOG("pthread_mutex_init failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mutex_lock()

srn_thread_status_t srn_mutex_lock

(

srn_mutex_t *

m

)

Definition at line 96 of file thread_posix.c.

                                                   {
  PANIC_IF_NULL(m);
  int rc = pthread_mutex_lock(&m->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_mutex_lock failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mutex_unlock()

srn_thread_status_t srn_mutex_unlock

(

srn_mutex_t *

m

)

Definition at line 105 of file thread_posix.c.

                                                     {
  PANIC_IF_NULL(m);
  int rc = pthread_mutex_unlock(&m->handle);
  if (rc != 0) {
    THREAD_LOG("pthread_mutex_unlock failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_thread_join()

srn_thread_status_t srn_thread_join

(

srn_thread_t *

t

)

Block until the thread started for t returns.

Definition at line 77 of file thread_posix.c.

                                                     {
  PANIC_IF_NULL(t);
  // The thread's return value is discarded. The trampoline always returns null.
  int rc = pthread_join(t->handle, nullptr);
  if (rc != 0) {
    THREAD_LOG("pthread_join failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_thread_spawn()

srn_thread_status_t srn_thread_spawn	(	srn_thread_t *	t,
		void(*	fn )(void *),
		void *	arg )

Run fn(arg) on a new OS thread.

Returns SRN_THREAD_OK, or a status describing why the thread could not be created. The caller owns t and must keep it alive until srn_thread_join returns.

Definition at line 63 of file thread_posix.c.

                                                                                     {
  PANIC_IF_NULL(t);
  PANIC_IF_NULL(fn);
 
  t->fn = fn;
  t->arg = arg;
 
  int rc = pthread_create(&t->handle, nullptr, posix_trampoline, t);
  if (rc != 0) {
    THREAD_LOG("pthread_create failed (errno %d)", rc);
  }
  return status_from_errno(rc);
}

Here is the call graph for this function:

Here is the caller graph for this function: