This header file defines the following standard symbols.

PRIORITY_MIN:

Lowest possible thread scheduling priority.

PRIORITY_NORMAL:

Default thread scheduling priority.

PRIORITY_MAX:

Highest possible thread scheduling priority.

SCHED_FIFO:

The “first in first out” thread scheduling policy.

SCHED_RR:

The “round robin” thread scheduling policy.

PTHREAD_STACK_MIN:

The minumum allowed stack size.

PTHREAD_CREATE_JOINABLE:

Thread attribute; thread is created joinable.

PTHREAD_CREATE_DETACHED:

Thread attribute; thread is created detached.

PTHREAD_PRIO_NONE:

Mutex attribute; mutex does not do priority inheritance.

PTHREAD_PRIO_INHERIT:

Mutex attribute; mutex does priority inheritance.

PTHREAD_MUTEX_NORMAL:

Mutex attribute; normal error checking, no recursion.

PTHREAD_MUTEX_ERRORCHECK:

Mutex attribute; extra error checking, no recursion.

PTHREAD_MUTEX_RECURSIVE:

Mutex attribute; normal error checking, recursion allowed.

PTHREAD_MUTEX_DEFAULT:

Mutex attribute; normal error checking, no recursion.

PTHREAD_CANCEL_ENABLE:

Cancelation state; Cancelation state is enabled.

PTHREAD_CANCEL_DISABLE:

Cancelation state; Cancelation state is disabled.

PTHREAD_CANCEL_DEFERRED:

Cancelation type; Cancelation type deferred,

PTHREAD_CANCEL_ASYNCHRONOUS:

Cancelation type; Cancelation type is asynchronous.

PTHREAD_CANCELED:

The exit status returned by pthread_join for a canceled thread.

pthread_t:

Thread identifier type definition.

pthread_mutex_t:

Mutex type definition.

pthread_cond_t:

Condition variable type definition.

pthread_attr_t:

Thread attributes type definition.

pthread_attr_default:

Default thread attributes object.

pthread_mutexattr_t:

Mutex attributes type definition.

pthread_mutexattr_default:

Default mutex attributes object.

pthread_condattr_t:

Condition variable attributes type definition.

pthread_condattr_default:

Default condition variable attributes object.

sched_param_t:

Type definition for the pthread_setschedparam interface function.

#include <oskit/threads/pthread.h>

void pthread_init(int preemptible);

This function initializes the threads system. It should be called as the first function in the application’s main program function.

When pthread_init returns, the caller is now running within the main thread, although on the same stack as when called. One or more idle threads have also been created, and are running at low priority. At this point, the application is free to use any of the pthread interface functions described in this section.

preemptible:

A boolean value specifying whether the threads system should use preemption based scheduling. When preemption based scheduling is not used, it is up to the application to yield the processor using sched_yield as necessary.

#include <oskit/threads/pthread.h>

int pthread_attr_init(pthread_attr_t *attr);

Initialize a thread attributes object for use with pthread_create.

attr:

A pointer to the pthread_attr_t object representing the attributes for a thread creation.

Returns zero on success.

pthread_create, pthread_attr_setprio, pthread_attr_setstacksize

#include <oskit/threads/pthread.h>

int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate);

Set the thread detach state in a previously initialized threads attribute object, for use with pthread_create.

attr:

A pointer to the pthread_attr_t object representing the attributes for a thread creation.

detachstate:

Either PTHREAD_CREATE_JOINABLE or PTHREAD_CREATE_DETACHED.

Returns zero on success. Returns EINVAL if detachstate is invalid.

pthread_create, pthread_attr_init

#include <oskit/threads/pthread.h>

int pthread_attr_setprio(pthread_attr_t *attr, int pri);

Set the priority value in a previously initialized threads attribute object, for use with pthread_create.

attr:

A pointer to the pthread_attr_t object representing the attributes for a thread creation.

pri:

A value between PRIORITY_MIN and PRIORITY_MAX.

Returns zero on success. Returns EINVAL if priority is outside the range of PRIORITY_MIN to PRIORITY_MAX.

pthread_create, pthread_attr_init, pthread_attr_setstacksize

#include <oskit/threads/pthread.h>

int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr);

Set the stack address in a previously initialized threads attribute object, for use with pthread_create. The new thread will be created using the provided stack. It is necessary to call pthread_attr_setstacksize() if the size is not PTHREAD_STACK_MIN.

attr:

A pointer to the pthread_attr_t object representing the attributes for a thread creation.

stackaddr:

The address of the stack.

Returns zero on success.

pthread_create, pthread_attr_init, pthread_attr_setstacksize

#include <oskit/threads/pthread.h>

int pthread_attr_setguardsize(pthread_attr_t *attr, oskit_size_t guardsize);

Set the stack guard size in a previously initialized threads attribute object, for use with pthread_create. This much extra space will be allocated at the end of the stack and set as a redzone to catch stack overflow. The guard size is rounded up to a multiple of the native page size. Stack guards are not created for stacks provided with pthread_attr_setstackaddr.

attr:

A pointer to the pthread_attr_t object representing the attributes for a thread creation.

guardsize:

A reasonable stack guard size.

Returns zero on success.

pthread_create, pthread_attr_init, pthread_attr_setstackaddr

#include <oskit/threads/pthread.h>

int pthread_attr_setstacksize(pthread_attr_t *attr, oskit_size_t stacksize);

Set the stack size in a previously initialized threads attribute object, for use with pthread_create.

attr:

A pointer to the pthread_attr_t object representing the attributes for a thread creation.

stacksize:

A reasonable stack size.

Returns zero on success. Returns EINVAL if stacksize is less than PTHREAD_STACK_MIN.

pthread_create, pthread_attr_init, pthread_attr_setprio

#include <oskit/threads/pthread.h>

int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);

Set the scheduling policy in a previously initialized threads attribute object, for use with pthread_create.

attr:

A pointer to the pthread_attr_t object representing the attributes for a thread creation.

policy:

Either SCHED_FIFO or SCHED_RR.

Returns zero on success. Returns EINVAL if policy is invalid.

pthread_create, pthread_attr_init

#include <oskit/threads/pthread.h>

int pthread_mutexattr_init(pthread_mutexattr_t *attr);

Initialize an mutex attributes object for use with pthread_mutex_init.

attr:

A pointer to the pthread_mutexattr_t object representing the attributes for a mutex initialization.

Returns zero on success.

pthread_mutex_init, pthread_mutex_setprotocol

#include <oskit/threads/pthread.h>

int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int protocol);

Set the protocol in a previously initialized mutex attribute object. When a mutex is created with the protocol PTHREAD_PRIO_INHERIT, threads that blocked on the mutex will result in a transfer of priority from higher to lower priority threads.

attr:

A pointer to the pthread_mutexattr_t object representing the attributes for a mutex initialization.

protocol:

Either PTHREAD_PRIO_NONE or PTHREAD_PRIO_INHERIT.

Returns zero on success.

pthread_mutex_init

#include <oskit/threads/pthread.h>

int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);

Set the type in a previously initialized mutex attribute object. PTHREAD_MUTEX_NORMAL, PTHREAD_MUTEX_ERRORCHECK, and PTHREAD_MUTEX_DEFAULT are equivalent. PTHREAD_MUTEX_RECURSIVE allows a mutex to be recursively locked.

attr:

A pointer to the pthread_mutexattr_t object representing the attributes for a mutex initialization.

type:

One of PTHREAD_MUTEX_NORMAL, PTHREAD_MUTEX_ERRORCHECK, PTHREAD_MUTEX_DEFAULT, or PTHREAD_MUTEX_RECURSIVE.

Returns zero on success.

pthread_mutex_init

#include <oskit/threads/pthread.h>

int pthread_condattr_init(pthread_condattr_t *attr);

Initialize an condition variable attributes object for use with pthread_cond_init.

attr:

A pointer to the pthread_condattr_t object representing the attributes for a condition variable initialization.

Returns zero on success.

pthread_cond_init

#include <oskit/threads/pthread.h>

int pthread_cancel(pthread_t tid);

Cancel the thread specified by tid. The thread is marked for cancellation, but because of scheduling and device delays, might not be acted upon until some future time.

tid:

The thread identifier of the thread to be canceled.

Returns zero on success. EINVAL if tid specifies an invalid thread.

pthread_create, pthread_sleep

#include <oskit/threads/pthread.h>

void pthread_cleanup_push(void (*routine)(void *), void *arg);

Push a cancellation cleanup handler routine onto the calling thread’s cancellation cleanup stack. When requested, the cleanup routine will be popped from the cancellation stack, and invoked with the argument arg.

routine:

The cleanup handler routine.

arg:

The argument to pass to the cleanup handler routine.

pthread_cancel, pthread_cleaup_pop

#include <oskit/threads/pthread.h>

void pthread_setcancelstate(int state, int *oldstate);

Set the cancel state for the current thread, returning the old state in oldstate. Valid states are either PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE. This routine is async-cancel safe.

state:

New cancel state.

oldstate:

Location in which to place the original cancel state.

pthread_cancel, pthread_setcanceltype

#include <oskit/threads/pthread.h>

void pthread_setcanceltype(int type, int *oldtype);

Set the cancel type for the current thread, returning the old type in oldtype. Valid types are either PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS. This routine is async-cancel safe.

type:

New cancel type.

oldtype:

Location in which to place the original cancel type.

pthread_cancel, pthread_setcancelstate

#include <oskit/threads/pthread.h>

void pthread_testcancel(void);

Test whether a cancelation is pending, and deliver the cancelation if the cancel state is PTHREAD_CANCEL_ENABLED.

pthread_cancel, pthread_setcancelstate

#include <oskit/threads/pthread.h>

int pthread_cond_broadcast(pthread_cond_t *cond);

Wakeup all threads waiting on a condition variable.

cond:

A pointer to the condition variable object.

Returns zero on success.

pthread_cond_init, pthread_cond_wait, pthread_cond_signal

#include <oskit/threads/pthread.h>

int pthread_cond_destroy(pthread_cond_t *cond);

Destroy a condition variable object. The condition variable should be unused, with no threads waiting for it. The memory for the object is left intact; it is up to the caller to deallocate it.

cond:

A pointer to the condition variable object.

Returns zero on success. EINVAL if there are threads still waiting.

pthread_cond_init

#include <oskit/threads/pthread.h>

int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t *attr);

Initialize a condition variable object, using the provided condition attributes object. The attributes object may be a NULL pointer, in which case pthread_condattr_default is used.

cond:

A pointer to the condition variable object.

attr:

A pointer to the condition variable attributes object.

Returns zero on success.

pthread_cond_destroy

#include <oskit/threads/pthread.h>

int pthread_cond_signal(pthread_cond_t *cond);

Wakeup the highest priority thread waiting on a condition variable.

cond:

A pointer to the condition variable object.

Returns zero on success.

pthread_cond_wait, pthread_cond_broadcast

#include <oskit/threads/pthread.h>

int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);

The current thread is made to wait until the condition variable is signaled or broadcast. The mutex is released prior to waiting, and reacquired before returning.

cond:

A pointer to the condition variable object.

mutex:

A pointer to the mutex object.

Returns zero on success.

pthread_cond_signal, pthread_cond_broadcast, pthread_cond_timedwait

#include <oskit/threads/pthread.h>

int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, oskit_timespec_t *abstime);

The current thread is made to wait until the condition variable is signaled or broadcast, or until the timeout expires. The mutex is released prior to waiting, and reacquired before returning. The timeout is given as an absolute time in the future that bounds the wait.

cond:

A pointer to the condition variable object.

mutex:

A pointer to the mutex object.

abstime:

A pointer to an oskit_timespec structure.

Returns zero on success. Returns ETIMEDOUT if the timeout expires.

pthread_cond_signal, pthread_cond_broadcast, pthread_cond_wait

#include <oskit/threads/pthread.h>

int pthread_create(pthread_t *tid, const pthread_attr_t *attr, void (*function)(void *), void *arg);

Create a new thread and schedule it to run. The thread is created using the attributes object attr, which specifies the initial priority, stack size, and detach state. If a NULL attributes object is provided, a system default attributes object is used instead, specifying that the thread is detachable, has priority PRIORITY_NORMAL, and with a reasonable stack size.

This call returns immediately, with the thread id stored in the location given by tid. This thread id should be saved if the application wishes to manipulate the thread’s state at some future time.

The new thread is scheduled to run. When the thread starts up, it will call void (*function)(void *arg).

tid:

A pointer to the location where the thread id should be stored.

attr:

A pointer to the thread creation attributes object.

function:

The initial function to call when the thread first starts.

arg:

The argument to the initial function.

Returns zero on success, storing the tid of the new thread into *tid.

pthread_join, pthread_detach, pthread_exit

#include <oskit/threads/pthread.h>

int pthread_detach(pthread_t tid);

The thread specified by tid is detached from its parent. If the thread has already exited, its resources are released.

tid:

The thread id of the thread being detached.

Returns zero on success. EINVAL if tid refers to a non-existent thread.

pthread_join, pthread_create, pthread_exit

#include <oskit/threads/pthread.h>

int pthread_exit(void *status);

The current thread is terminated, with its status value made available to the parent using pthread_join.

status:

The exit status.

This function does not return.

pthread_join, pthread_create, pthread_detach

#include <oskit/threads/pthread.h>

int pthread_join(pthread_t tid, void **status);

The current thread indicates that it would like to join with the target thread specified by tid. If the target thread has already terminated, its exit status is provided immediately to the caller. If the target thread has not yet exited, the caller is made to wait. Once the target has exited, all of the threads waiting to join with it are woken up, and the target’s exit status provided to each.

tid:

The thread id of the thread being joined with.

status:

A pointer to a location where the target’s exit status is placed.

Returns zero on success, storing the target’s exit status in *status. EINVAL if tid refers to a non-existent thread.