TinyCThread 1.1

- Main Page
- Files

- File List
- Globals

Macros | Typedefs | Functions
tinycthread.h File Reference
`#include <time.h>`
`#include <pthread.h>`

Go to the source code of this file.

## Macros
#define | TINYCTHREAD_VERSION_MAJOR 1
| TinyCThread version (major number). More...
#define | TINYCTHREAD_VERSION_MINOR 2
| TinyCThread version (minor number). More...
#define | TINYCTHREAD_VERSION (TINYCTHREAD_VERSION_MAJOR * 100 + TINYCTHREAD_VERSION_MINOR)
| TinyCThread version (full version). More...
#define | _Thread_local
| Thread local storage keyword. More...
#define | thrd_error 0
| The requested operation failed.
#define | thrd_success 1
| The requested operation succeeded.
#define | thrd_timedout 2
| The time specified in the call was reached without acquiring the requested resource.
#define | thrd_busy 3
| The requested operation failed because a tesource requested by a test and return function is already in use.
#define | thrd_nomem 4
| The requested operation failed because it was unable to allocate memory.
#define | call_once(flag, func) pthread_once(flag,func)
| Invoke a callback exactly once. More...

## Typedefs
typedef int(* | thrd_start_t) (void *arg)
| Thread start function. More...
typedef void(* | tss_dtor_t) (void *val)
| Destructor function for a thread-specific storage. More...

## Functions
int | mtx_init (mtx_t *mtx, int type)
| Create a mutex object. More...
void | mtx_destroy (mtx_t *mtx)
| Release any resources used by the given mutex. More...
int | mtx_lock (mtx_t *mtx)
| Lock the given mutex. More...
int | mtx_timedlock (mtx_t *mtx, const struct timespec *ts)
| Lock the given mutex, or block until a specific point in time. More...
int | mtx_trylock (mtx_t *mtx)
| Try to lock the given mutex. More...
int | mtx_unlock (mtx_t *mtx)
| Unlock the given mutex. More...
int | cnd_init (cnd_t *cond)
| Create a condition variable object. More...
void | cnd_destroy (cnd_t *cond)
| Release any resources used by the given condition variable. More...
int | cnd_signal (cnd_t *cond)
| Signal a condition variable. More...
int | cnd_broadcast (cnd_t *cond)
| Broadcast a condition variable. More...
int | cnd_wait (cnd_t *cond, mtx_t *mtx)
| Wait for a condition variable to become signaled. More...
int | cnd_timedwait (cnd_t *cond, mtx_t *mtx, const struct timespec *ts)
| Wait for a condition variable to become signaled. More...
int | thrd_create (thrd_t *thr, thrd_start_t func, void *arg)
| Create a new thread. More...
thrd_t | thrd_current (void)
| Identify the calling thread. More...
int | thrd_detach (thrd_t thr)
| Dispose of any resources allocated to the thread when that thread exits. More...
int | thrd_equal (thrd_t thr0, thrd_t thr1)
| Compare two thread identifiers. More...
TTHREAD_NORETURN void | thrd_exit (int res)
| Terminate execution of the calling thread. More...
int | thrd_join (thrd_t thr, int *res)
| Wait for a thread to terminate. More...
int | thrd_sleep (const struct timespec *duration, struct timespec *remaining)
| Put the calling thread to sleep. More...
void | thrd_yield (void)
| Yield execution to another thread. More...
int | tss_create (tss_t *key, tss_dtor_t dtor)
| Create a thread-specific storage. More...
void | tss_delete (tss_t key)
| Delete a thread-specific storage. More...
void * | tss_get (tss_t key)
| Get the value for a thread-specific storage. More...
int | tss_set (tss_t key, void *val)
| Set the value for a thread-specific storage. More...

## Macro Definition Documentation

#define _Thread_local

Thread local storage keyword.

A variable that is declared with the `_Thread_local` keyword makes the value of the variable local to each thread (known as thread-local storage, or TLS). Example usage:

1 // This variable is local to each thread.
2 _Thread_local int variable;

Note
  The `_Thread_local` keyword is a macro that maps to the corresponding compiler directive (e.g. `__declspec(thread)`).
  This directive is currently not supported on Mac OS X (it will give a compiler error), since compile-time TLS is not supported in the Mac OS X executable format. Also, some older versions of MinGW (before GCC 4.x) do not support this directive, nor does the Tiny C Compiler.

#define call_once | ( |  | flag,
|  |  | func
| ) |  | pthread_once(flag,func)

Invoke a callback exactly once.

Parameters

  flag | Flag used to ensure the callback is invoked exactly once.
  func | Callback to invoke.

#define TINYCTHREAD_VERSION (TINYCTHREAD_VERSION_MAJOR * 100 + TINYCTHREAD_VERSION_MINOR)

TinyCThread version (full version).

#define TINYCTHREAD_VERSION_MAJOR 1

TinyCThread version (major number).

#define TINYCTHREAD_VERSION_MINOR 2

TinyCThread version (minor number).

## Typedef Documentation

typedef int(* thrd_start_t) (void *arg)

Thread start function.

Any thread that is started with the thrd_create() function must be started through a function of this type.

Parameters

  arg | The thread argument (the `arg` argument of the corresponding thrd_create() call).

Returns
  The thread return value, which can be obtained by another thread by using the thrd_join() function.

typedef void(* tss_dtor_t) (void *val)

Destructor function for a thread-specific storage.

Parameters

  val | The value of the destructed thread-specific storage.

## Function Documentation

int cnd_broadcast | ( | cnd_t * | cond | ) |

Broadcast a condition variable.

Unblocks all of the threads that are blocked on the given condition variable at the time of the call. If no threads are blocked on the condition variable at the time of the call, the function does nothing and return success.

Parameters

  cond | A condition variable object.

Returns
  thrd_success on success, or thrd_error if the request could not be honored.

void cnd_destroy | ( | cnd_t * | cond | ) |

Release any resources used by the given condition variable.

Parameters

  cond | A condition variable object.

int cnd_init | ( | cnd_t * | cond | ) |

Create a condition variable object.

Parameters

  cond | A condition variable object.

Returns
  thrd_success on success, or thrd_error if the request could not be honored.

int cnd_signal | ( | cnd_t * | cond | ) |

Signal a condition variable.

Unblocks one of the threads that are blocked on the given condition variable at the time of the call. If no threads are blocked on the condition variable at the time of the call, the function does nothing and return success.

Parameters

  cond | A condition variable object.

Returns
  thrd_success on success, or thrd_error if the request could not be honored.

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

Wait for a condition variable to become signaled.

The function atomically unlocks the given mutex and endeavors to block until the given condition variable is signaled by a call to cnd_signal or to cnd_broadcast, or until after the specified time. When the calling thread becomes unblocked it locks the mutex before it returns.

Parameters

  cond | A condition variable object.
  mtx | A mutex object.
  xt | A point in time at which the request will time out (absolute time).

Returns
  thrd_success upon success, or thrd_timeout if the time specified in the call was reached without acquiring the requested resource, or thrd_error if the request could not be honored.

int cnd_wait | ( | cnd_t * | cond,
|  | mtx_t * | mtx
| ) |  |

Wait for a condition variable to become signaled.

The function atomically unlocks the given mutex and endeavors to block until the given condition variable is signaled by a call to cnd_signal or to cnd_broadcast. When the calling thread becomes unblocked it locks the mutex before it returns.

Parameters

  cond | A condition variable object.
  mtx | A mutex object.

Returns
  thrd_success on success, or thrd_error if the request could not be honored.

void mtx_destroy | ( | mtx_t * | mtx | ) |

Release any resources used by the given mutex.

Parameters

  mtx | A mutex object.

int mtx_init | ( | mtx_t * | mtx,
|  | int | type
| ) |  |

Create a mutex object.

Parameters

  mtx | A mutex object.
  type | Bit-mask that must have one of the following six values: `mtx_plain` for a simple non-recursive mutex `mtx_timed` for a non-recursive mutex that supports timeout `mtx_plain` | `mtx_recursive` (same as `mtx_plain`, but recursive) `mtx_timed` | `mtx_recursive` (same as `mtx_timed`, but recursive)

Returns
  thrd_success on success, or thrd_error if the request could not be honored.

int mtx_lock | ( | mtx_t * | mtx | ) |

Lock the given mutex.

Blocks until the given mutex can be locked. If the mutex is non-recursive, and the calling thread already has a lock on the mutex, this call will block forever.

Parameters

  mtx | A mutex object.

Returns
  thrd_success on success, or thrd_error if the request could not be honored.

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

Lock the given mutex, or block until a specific point in time.

Blocks until either the given mutex can be locked, or the specified TIME_UTC based time.

Parameters

  mtx | A mutex object.
  ts | A UTC based calendar time

Returns
  The mtx_timedlock function returns thrd_success on success, or thrd_timedout if the time specified was reached without acquiring the requested resource, or thrd_error if the request could not be honored.

int mtx_trylock | ( | mtx_t * | mtx | ) |

Try to lock the given mutex.

The specified mutex shall support either test and return or timeout. If the mutex is already locked, the function returns without blocking.

Parameters

  mtx | A mutex object.

Returns
  thrd_success on success, or thrd_busy if the resource requested is already in use, or thrd_error if the request could not be honored.

int mtx_unlock | ( | mtx_t * | mtx | ) |

Unlock the given mutex.

Parameters

  mtx | A mutex object.

Returns
  thrd_success on success, or thrd_error if the request could not be honored.

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

Create a new thread.

Parameters

  thr | Identifier of the newly created thread.
  func | A function pointer to the function that will be executed in the new thread.
  arg | An argument to the thread function.

Returns
  thrd_success on success, or thrd_nomem if no memory could be allocated for the thread requested, or thrd_error if the request could not be honored.

Note
  A thread’s identifier may be reused for a different thread once the original thread has exited and either been detached or joined to another thread.

thrd_t thrd_current | ( | void |  | ) |

Identify the calling thread.

Returns
  The identifier of the calling thread.

int thrd_detach | ( | thrd_t | thr | ) |

Dispose of any resources allocated to the thread when that thread exits.

Returns
  thrd_success, or thrd_error on error

int thrd_equal | ( | thrd_t | thr0,
|  | thrd_t | thr1
| ) |  |

Compare two thread identifiers.

The function determines if two thread identifiers refer to the same thread.

Returns
  Zero if the two thread identifiers refer to different threads. Otherwise a nonzero value is returned.

TTHREAD_NORETURN void thrd_exit | ( | int | res | ) |

Terminate execution of the calling thread.

Parameters

  res | Result code of the calling thread.

int thrd_join | ( | thrd_t | thr,
|  | int * | res
| ) |  |

Wait for a thread to terminate.

The function joins the given thread with the current thread by blocking until the other thread has terminated.

Parameters

  thr | The thread to join with.
  res | If this pointer is not NULL, the function will store the result code of the given thread in the integer pointed to by `res`.

Returns
  thrd_success on success, or thrd_error if the request could not be honored.

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

Put the calling thread to sleep.

Suspend execution of the calling thread.

Parameters

  duration | Interval to sleep for
  remaining | If non-NULL, this parameter will hold the remaining time until time_point upon return. This will typically be zero, but if the thread was woken up by a signal that is not ignored before duration was reached `remaining` will hold a positive time.

Returns
  0 (zero) on successful sleep, -1 if an interrupt occurred, or a negative value if the operation fails.

void thrd_yield | ( | void |  | ) |

Yield execution to another thread.

Permit other threads to run, even if the current thread would ordinarily continue to run.

int tss_create | ( | tss_t * | key,
|  | tss_dtor_t | dtor
| ) |  |

Create a thread-specific storage.

Parameters

  key | The unique key identifier that will be set if the function is successful.
  dtor | Destructor function. This can be NULL.

Returns
  thrd_success on success, or thrd_error if the request could not be honored.

Note
  On Windows, the `dtor` will definitely be called when appropriate for threads created with thrd_create. It will be called for other threads in most cases, the possible exception being for DLLs loaded with LoadLibraryEx. In order to be certain, you should use thrd_create whenever possible.

void tss_delete | ( | tss_t | key | ) |

Delete a thread-specific storage.

The function releases any resources used by the given thread-specific storage.

Parameters

  key | The key that shall be deleted.

void* tss_get | ( | tss_t | key | ) |

Get the value for a thread-specific storage.

Parameters

  key | The thread-specific storage identifier.

Returns
  The value for the current thread held in the given thread-specific storage.

int tss_set | ( | tss_t | key,
|  | void * | val
| ) |  |

Set the value for a thread-specific storage.

Parameters

  key | The thread-specific storage identifier.
  val | The value of the thread-specific storage to set for the current thread.

Returns
  thrd_success on success, or thrd_error if the request could not be honored.