SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
threads.h File Reference

C11 threads (<threads.h>) for STK: thin wrappers over the pthread shim (stk_c_pthread.h). Implemented by stk_c_threads.cpp. Needs stk_pthread_bind_kernel() as the pthread shim does. More...

#include "stk_c_pthread.h"
#include <time.h>
Include dependency graph for threads.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define ONCE_FLAG_INIT   PTHREAD_ONCE_INIT
#define TSS_DTOR_ITERATIONS   (4)

Typedefs

typedef pthread_t thrd_t
typedef int(* thrd_start_t) (void *)
typedef pthread_mutex_t mtx_t
typedef pthread_cond_t cnd_t
typedef pthread_key_t tss_t
typedef void(* tss_dtor_t) (void *)
typedef pthread_once_t once_flag

Enumerations

enum  {
  thrd_success = 0 ,
  thrd_busy = 1 ,
  thrd_error = 2 ,
  thrd_nomem = 3 ,
  thrd_timedout = 4
}
enum  {
  mtx_plain = 0 ,
  mtx_recursive = 1 ,
  mtx_timed = 2
}

Functions

int thrd_create (thrd_t *thr, thrd_start_t func, void *arg)
int thrd_equal (thrd_t lhs, thrd_t rhs)
thrd_t thrd_current (void)
int thrd_sleep (const struct timespec *duration, struct timespec *remaining)
void thrd_yield (void)
void thrd_exit (int res)
int thrd_detach (thrd_t thr)
int thrd_join (thrd_t thr, int *res)
int mtx_init (mtx_t *mtx, int type)
int mtx_lock (mtx_t *mtx)
int mtx_timedlock (mtx_t *mtx, const struct timespec *ts)
int mtx_trylock (mtx_t *mtx)
int mtx_unlock (mtx_t *mtx)
void mtx_destroy (mtx_t *mtx)
int cnd_init (cnd_t *cond)
int cnd_signal (cnd_t *cond)
int cnd_broadcast (cnd_t *cond)
int cnd_wait (cnd_t *cond, mtx_t *mtx)
int cnd_timedwait (cnd_t *cond, mtx_t *mtx, const struct timespec *ts)
void cnd_destroy (cnd_t *cond)
int tss_create (tss_t *key, tss_dtor_t dtor)
void * tss_get (tss_t key)
int tss_set (tss_t key, void *val)
void tss_delete (tss_t key)
void call_once (once_flag *flag, void(*func)(void))

Detailed Description

C11 threads (<threads.h>) for STK: thin wrappers over the pthread shim (stk_c_pthread.h). Implemented by stk_c_threads.cpp. Needs stk_pthread_bind_kernel() as the pthread shim does.

All mutexes are recursive in practice (as pthread mutexes of the shim), mtx_plain and mtx_timed behave like mtx_recursive. thrd_create() uses a short-lived start record from a static table of STK_C_PTHREAD_MAX_THREADS entries, so no heap is needed. thrd_sleep() is a cancellation point and uses nanosleep() of time.h.

Definition in file threads.h.

Macro Definition Documentation

◆ ONCE_FLAG_INIT

#define ONCE_FLAG_INIT   PTHREAD_ONCE_INIT

Definition at line 41 of file threads.h.

◆ TSS_DTOR_ITERATIONS

#define TSS_DTOR_ITERATIONS   (4)

Definition at line 42 of file threads.h.

Typedef Documentation

◆ cnd_t

Definition at line 33 of file threads.h.

◆ mtx_t

Definition at line 32 of file threads.h.

◆ once_flag

Definition at line 36 of file threads.h.

◆ thrd_start_t

typedef int(* thrd_start_t) (void *)

Definition at line 31 of file threads.h.

◆ thrd_t

typedef pthread_t thrd_t

Definition at line 30 of file threads.h.

◆ tss_dtor_t

typedef void(* tss_dtor_t) (void *)

Definition at line 35 of file threads.h.

◆ tss_t

Definition at line 34 of file threads.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
mtx_plain 
mtx_recursive 
mtx_timed 

Definition at line 39 of file threads.h.

39{ mtx_plain = 0, mtx_recursive = 1, mtx_timed = 2 };
@ mtx_timed
Definition threads.h:39
@ mtx_plain
Definition threads.h:39
@ mtx_recursive
Definition threads.h:39

◆ anonymous enum

anonymous enum
Enumerator
thrd_success 
thrd_busy 
thrd_error 
thrd_nomem 
thrd_timedout 

Definition at line 38 of file threads.h.

38{ thrd_success = 0, thrd_busy = 1, thrd_error = 2, thrd_nomem = 3, thrd_timedout = 4 };
@ thrd_timedout
Definition threads.h:38
@ thrd_success
Definition threads.h:38
@ thrd_busy
Definition threads.h:38
@ thrd_nomem
Definition threads.h:38
@ thrd_error
Definition threads.h:38

Function Documentation

◆ call_once()

void call_once ( once_flag * flag,
void(* func )(void) )

Definition at line 230 of file stk_c_threads.cpp.

230{ (void)pthread_once(flag, func); }
int pthread_once(pthread_once_t *once_control, void(*init_routine)(void))
Call init_routine exactly once for a given once_control, no matter how many threads call pthread_once...

References pthread_once().

Here is the call graph for this function:

◆ cnd_broadcast()

int cnd_broadcast ( cnd_t * cond)

Definition at line 217 of file stk_c_threads.cpp.

217{ return ToThrd(pthread_cond_broadcast(cond)); }
int pthread_cond_broadcast(pthread_cond_t *cond)
Wake all threads waiting on cond (no effect if none is waiting).

References pthread_cond_broadcast().

Here is the call graph for this function:

◆ cnd_destroy()

void cnd_destroy ( cnd_t * cond)

Definition at line 223 of file stk_c_threads.cpp.

223{ (void)pthread_cond_destroy(cond); }
int pthread_cond_destroy(pthread_cond_t *cond)
Destroy a condition variable, releasing the underlying STK object.

References pthread_cond_destroy().

Here is the call graph for this function:

◆ cnd_init()

int cnd_init ( cnd_t * cond)

Definition at line 215 of file stk_c_threads.cpp.

215{ return ToThrd(pthread_cond_init(cond, nullptr)); }
int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr)
Initialize a condition variable.

References pthread_cond_init().

Here is the call graph for this function:

◆ cnd_signal()

int cnd_signal ( cnd_t * cond)

Definition at line 216 of file stk_c_threads.cpp.

216{ return ToThrd(pthread_cond_signal(cond)); }
int pthread_cond_signal(pthread_cond_t *cond)
Wake one thread waiting on cond (no effect if none is waiting).

References pthread_cond_signal().

Here is the call graph for this function:

◆ cnd_timedwait()

int cnd_timedwait ( cnd_t * cond,
mtx_t * mtx,
const struct timespec * ts )

Definition at line 219 of file stk_c_threads.cpp.

220{
221 return ToThrd(pthread_cond_timedwait(cond, mtx, ts));
222}
int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime)
As pthread_cond_wait(), with an absolute deadline.

References pthread_cond_timedwait().

Here is the call graph for this function:

◆ cnd_wait()

int cnd_wait ( cnd_t * cond,
mtx_t * mtx )

Definition at line 218 of file stk_c_threads.cpp.

218{ return ToThrd(pthread_cond_wait(cond, mtx)); }
int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex)
Atomically unlock mutex and wait for a signal; re-locks mutex before returning.

References pthread_cond_wait().

Here is the call graph for this function:

◆ mtx_destroy()

void mtx_destroy ( mtx_t * mtx)

Definition at line 213 of file stk_c_threads.cpp.

213{ (void)pthread_mutex_destroy(mtx); }
int pthread_mutex_destroy(pthread_mutex_t *mutex)
Destroy a mutex, releasing the underlying STK mutex object.

References pthread_mutex_destroy().

Here is the call graph for this function:

◆ mtx_init()

int mtx_init ( mtx_t * mtx,
int type )

Definition at line 190 of file stk_c_threads.cpp.

191{
193 int result = thrd_error;
194
195 if ((mtx != nullptr) && (pthread_mutexattr_init(&attr) == 0))
196 {
199 {
200 result = ToThrd(pthread_mutex_init(mtx, &attr));
201 }
202
203 (void)pthread_mutexattr_destroy(&attr);
204 }
205
206 return result;
207}
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr)
Destroy a mutex attributes object (no-op; no owned resources).
#define PTHREAD_MUTEX_DEFAULT
#define PTHREAD_MUTEX_RECURSIVE
int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr)
Initialize a mutex.
int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type)
Set the mutex type.
int pthread_mutexattr_init(pthread_mutexattr_t *attr)
Initialize a mutex attributes object with default values (PTHREAD_MUTEX_DEFAULT).
Mutex attributes.

References mtx_recursive, PTHREAD_MUTEX_DEFAULT, pthread_mutex_init(), PTHREAD_MUTEX_RECURSIVE, pthread_mutexattr_destroy(), pthread_mutexattr_init(), pthread_mutexattr_settype(), and thrd_error.

Here is the call graph for this function:

◆ mtx_lock()

int mtx_lock ( mtx_t * mtx)

Definition at line 209 of file stk_c_threads.cpp.

209{ return ToThrd(pthread_mutex_lock(mtx)); }
int pthread_mutex_lock(pthread_mutex_t *mutex)
Lock a mutex, blocking until it becomes available.

References pthread_mutex_lock().

Here is the call graph for this function:

◆ mtx_timedlock()

int mtx_timedlock ( mtx_t * mtx,
const struct timespec * ts )

Definition at line 210 of file stk_c_threads.cpp.

210{ return ToThrd(pthread_mutex_timedlock(mtx, ts)); }
int pthread_mutex_timedlock(pthread_mutex_t *mutex, const struct timespec *abstime)
Lock with an absolute deadline.

References pthread_mutex_timedlock().

Here is the call graph for this function:

◆ mtx_trylock()

int mtx_trylock ( mtx_t * mtx)

Definition at line 211 of file stk_c_threads.cpp.

211{ return ToThrd(pthread_mutex_trylock(mtx)); }
int pthread_mutex_trylock(pthread_mutex_t *mutex)
Try to lock a mutex without blocking.

References pthread_mutex_trylock().

Here is the call graph for this function:

◆ mtx_unlock()

int mtx_unlock ( mtx_t * mtx)

Definition at line 212 of file stk_c_threads.cpp.

212{ return ToThrd(pthread_mutex_unlock(mtx)); }
int pthread_mutex_unlock(pthread_mutex_t *mutex)
Unlock a mutex held by the calling thread.

References pthread_mutex_unlock().

Here is the call graph for this function:

◆ thrd_create()

int thrd_create ( thrd_t * thr,
thrd_start_t func,
void * arg )

Definition at line 109 of file stk_c_threads.cpp.

110{
111 int result = thrd_error;
112
113 if ((thr != nullptr) && (func != nullptr))
114 {
115 ThrdStart *const rec = ClaimStart(func, arg);
116
117 if (rec == nullptr)
118 {
119 result = thrd_nomem;
120 }
121 else
122 {
123 const int err = pthread_create(thr, nullptr, &Trampoline, rec);
124
125 if (err != 0)
126 {
127 ReleaseStart(rec);
128 result = (err == EAGAIN) ? thrd_nomem : thrd_error;
129 }
130 else
131 {
132 result = thrd_success;
133 }
134 }
135 }
136
137 return result;
138}
int pthread_create(pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void *), void *arg)
Create and start a new thread.

References pthread_create(), thrd_error, thrd_nomem, and thrd_success.

Here is the call graph for this function:

◆ thrd_current()

thrd_t thrd_current ( void )

Definition at line 145 of file stk_c_threads.cpp.

146{
147 return pthread_self();
148}
pthread_t pthread_self(void)
Return the calling thread's own handle.

References pthread_self().

Here is the call graph for this function:

◆ thrd_detach()

int thrd_detach ( thrd_t thr)

Definition at line 172 of file stk_c_threads.cpp.

173{
174 return (pthread_detach(thr) == 0) ? thrd_success : thrd_error;
175}
int pthread_detach(pthread_t thread)
Mark a thread as detached.

References pthread_detach(), thrd_error, and thrd_success.

Here is the call graph for this function:

◆ thrd_equal()

int thrd_equal ( thrd_t lhs,
thrd_t rhs )

Definition at line 140 of file stk_c_threads.cpp.

141{
142 return pthread_equal(lhs, rhs);
143}
int pthread_equal(pthread_t t1, pthread_t t2)
Compare two thread handles for equality.

References pthread_equal().

Here is the call graph for this function:

◆ thrd_exit()

void thrd_exit ( int res)

Definition at line 167 of file stk_c_threads.cpp.

168{
169 pthread_exit(reinterpret_cast<void *>(static_cast<std::intptr_t>(res)));
170}
void pthread_exit(void *retval)
Terminate the calling thread.

References pthread_exit().

Here is the call graph for this function:

◆ thrd_join()

int thrd_join ( thrd_t thr,
int * res )

Definition at line 177 of file stk_c_threads.cpp.

178{
179 void *retval = nullptr;
180 int result = ToThrd(pthread_join(thr, &retval));
181
182 if ((result == thrd_success) && (res != nullptr))
183 {
184 *res = static_cast<int>(reinterpret_cast<std::intptr_t>(retval));
185 }
186
187 return result;
188}
int pthread_join(pthread_t thread, void **retval)
Block until the given joinable thread finishes, then reclaim its resources.

References pthread_join(), and thrd_success.

Here is the call graph for this function:

◆ thrd_sleep()

int thrd_sleep ( const struct timespec * duration,
struct timespec * remaining )

Definition at line 150 of file stk_c_threads.cpp.

151{
152 int result = 0;
153
154 if (nanosleep(duration, remaining) != 0)
155 {
156 result = (errno == EINTR) ? -1 : -2; // C11: -1 interrupted, other negative value for an error
157 }
158
159 return result;
160}
int nanosleep(const struct timespec *req, struct timespec *rem)
Suspend the calling task for a relative time (rounded UP to whole ticks). Cancellation point.

References nanosleep().

Here is the call graph for this function:

◆ thrd_yield()

void thrd_yield ( void )

Definition at line 162 of file stk_c_threads.cpp.

163{
164 (void)sched_yield();
165}
int sched_yield(void)
Yield the CPU to another ready task.

References sched_yield().

Here is the call graph for this function:

◆ tss_create()

int tss_create ( tss_t * key,
tss_dtor_t dtor )

Definition at line 225 of file stk_c_threads.cpp.

225{ return ToThrd(pthread_key_create(key, dtor)); }
int pthread_key_create(pthread_key_t *key, void(*destructor)(void *))
Allocate a new thread-specific data key.

References pthread_key_create().

Here is the call graph for this function:

◆ tss_delete()

void tss_delete ( tss_t key)

Definition at line 228 of file stk_c_threads.cpp.

228{ (void)pthread_key_delete(key); }
int pthread_key_delete(pthread_key_t key)
Free a thread-specific data key.

References pthread_key_delete().

Here is the call graph for this function:

◆ tss_get()

void * tss_get ( tss_t key)

Definition at line 226 of file stk_c_threads.cpp.

226{ return pthread_getspecific(key); }
void * pthread_getspecific(pthread_key_t key)
Get the calling thread's value for key.

References pthread_getspecific().

Here is the call graph for this function:

◆ tss_set()

int tss_set ( tss_t key,
void * val )

Definition at line 227 of file stk_c_threads.cpp.

227{ return ToThrd(pthread_setspecific(key, val)); }
int pthread_setspecific(pthread_key_t key, const void *value)
Set the calling thread's value for key.

References pthread_setspecific().

Here is the call graph for this function: