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.

pthread_join, pthread_create, pthread_detach

#include <oskit/threads/pthread.h>

int pthread_key_create(pthread_key_t *key, void (*destructor)(void *));

Create a thread-specific key for use with pthread_setspecific. If specified, the destructor is called on any non-NULL key/value pair when a thread exits.

key:

Address where the new key value should be stored.

destructor:

Pointer to the destructor function, which may be NULL.

Returns zero on success, and stores the new key value at *key. Returns EAGAIN if the are no more keys available.

pthread_key_delete, pthread_setspecific, pthread_getspecific

#include <oskit/threads/pthread.h>

int pthread_key_delete(pthread_key_t *key);

Delete the thread-specific key. Attempts to use a key via pthread_setspecific or pthread_getspecific after it has been deleted is undefined.

key:

The key that should be deleted.

Returns zero on success. Returns EINVAL if key refers to an invalid key.

pthread_key_create, pthread_setspecific, pthread_getspecific

#include <oskit/threads/pthread.h>

int pthread_setspecific(pthread_key_t key, const void *value);

Associate a new thread-specific value with the specified key.

key:

The key that should be set.

value:

The new value to associate with the key.

Returns zero on success. Returns EINVAL if key refers to an invalid key.

pthread_key_create, pthread_key_delete, pthread_getspecific

#include <oskit/threads/pthread.h>

void *pthread_getspecific(pthread_key_t key);

Get the thread-specific value associated the specified key.

key:

The key for the value that should be retrieved.

Returns the value of the key. Errors always return zero.

pthread_key_create, pthread_key_delete, pthread_setspecific

#include <oskit/threads/pthread.h>

int pthread_mutex_init(pthread_mutex_t *m, pthread_mutexattr_t *attr);

Initialize a mutex object, using the provided mutex attributes object. The attributes object may be a NULL pointer, in which case pthread_mutexattr_default is used.

mutex:

A pointer to the mutex object.

attr:

A pointer to the mutex attributes object.

Returns zero on success.

pthread_mutex_destroy, pthread_mutex_lock, pthread_mutex_unlock

#include <oskit/threads/pthread.h>

int pthread_mutex_destroy(pthread_mutex_t *m);

The mutex object is destroyed, although the memory for the object is not deallocated. The mutex must not be held.

mutex:

A pointer to the mutex object.

Returns zero on success. Returns EBUSY if the mutex is still held.

pthread_mutex_init

#include <oskit/threads/pthread.h>

int pthread_mutex_lock(pthread_mutex_t *m);

Lock a mutex object. If the mutex is currently locked, the thread waits (is suspended) for the mutex to become available.

mutex:

A pointer to the mutex object.

Returns zero on success.

pthread_mutex_init, pthread_mutex_unlock, pthread_mutex_trylock

#include <oskit/threads/pthread.h>

int pthread_mutex_trylock(pthread_mutex_t *m);

Attempt to lock a mutex object. This function always returns immediately.

mutex:

A pointer to the mutex object.

Returns zero on success. Returns EBUSY if the mutex object is locked.

pthread_mutex_init, pthread_mutex_unlock, pthread_mutex_lock

#include <oskit/threads/pthread.h>

int pthread_mutex_unlock(pthread_mutex_t *m);

Unlock a mutex object. If there other threads waiting to acquire the mutex, the highest priority thread is woken up and granted the mutex.

mutex:

A pointer to the mutex object.

Returns zero on success.

pthread_mutex_init, pthread_mutex_trylock, pthread_mutex_lock

#include <oskit/threads/pthread.h>

pthread_t pthread_self(void);

Return the thread identifier of the current thread.

Returns the thread identifier.

pthread_create

#include <oskit/threads/pthread.h>

int pthread_setschedparam(pthread_t tid, int policy, const struct sched_param *param);

Change the scheduling parameters for a thread. The thread’s scheduling policy and priority are changed. If the change causes a thread to have a higher priority than the currently running thread, a reschedule operation is performed.

tid:

The thread identifier of the thread whose scheduling parameters should be changed.

policy:

The new scheduling policy, as defined in pthread.h

param:

A pointer to the sched_param_t object representing the new scheduling parameters.

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

pthread_create, sched_yield, pthread_setprio

#include <oskit/threads/pthread.h>
#include <signal.h>

int pthread_sigmask(int how, const sigset_t *set, [out] sigset_t *oset);

Examine or change the per-thread signal mask. This function operates identically to the POSIX function sigprocmask, but on the current thread.

how:

One of SIG_BLOCK, SIG_UNBLOCK, or SIG_SETMASK.

set:

If not a null pointer, a pointer to the new signal set.

oset:

If not a null pointer, a pointer to where the old signal set should be stored.

Returns zero on success. No errors are reported.

pthread_kill sigprocmask

#include <oskit/threads/pthread.h>
#include <signal.h>

int pthread_kill(pthread_t tid, int sig);

Send a signal to a specific thread.

tid:

The thread to send the signal to.

sig:

The signal to send.

Returns zero on success.

pthread_sigmask

#include <oskit/threads/pthread.h>

void sched_yield(void);

The calling thread voluntarily yields the processor. The highest priority thread is chosen for execution.

pthread_setprio, pthread_setschedparam

#include <oskit/threads/pthread.h>

int oskit_pthread_sleep(oskit_s64_t milliseconds);

The calling thread is put to sleep for the number of milliseconds specified. The thread will be woken up after the elapsed time, and will return ETIMEDOUT. If the timeout is zero, the thread is put to sleep forever. The thread may be woken up early, using the oskit_pthread_wakeup function, in which case the return value is zero.

milliseconds:

The number of milliseconds the thread should sleep for.

Returns ETIMEDOUT if the timeout expires, or zero if the thread is woken up early.

oskit_pthread_wakeup

#include <oskit/threads/pthread.h>

int oskit_pthread_wakeup(pthread_t tid);

Wakeup a thread that is sleeping in oskit_pthread_sleep, causing it to return from its sleep before the timeout expires.

tid:

The thread to wakeup.

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

oskit_pthread_sleep

#include <oskit/threads/pthread.h>

int oskit_pthread_setprio(pthread_t tid, int newpri);

Change the priority of a thread. If the change causes a thread to have a higher priority than the currently running thread, a reschedule operation is performed.

tid:

The thread identifier of the thread whose priority should be changed.

newpri:

The new priority, which must be from PRIORITY_MIN to PRIORITY_MAX.

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

pthread_create, sched_yield, pthread_setschedparam

#include <oskit/threads/pthread.h>

void osenv_process_lock(void);

Attempt to lock the process lock. If the lock cannot be immediately granted, the thread is put to sleep until it can be. The process lock is provided so that the client operating system can protect the device driver framework from concurrent execution. It is expected than any entry into the device framework will first take the process lock. If the thread executing inside the device driver framework blocks by calling osenv_sleep, the process lock will be released so that another thread may enter it safely. When the thread is woken up later, it will take the process lock again before returning from the sleep.

Attempts to recursively lock the process lock will result in a panic. This is intended as a debugging measure to prevent indiscriminate nesting of components that try to take the lock.

osenv_process_unlock, osenv_sleep, osenv_wakeup

#include <oskit/threads/pthread.h>

void osenv_process_unlock(void);

Release the process lock. If another thread is waiting to lock the process lock, it will be woken up. The process lock is provided so that the client operating system can protect the device driver framework from concurrent execution.

osenv_process_lock, osenv_sleep, osenv_wakeup

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_socket(struct oskit_socket *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_socket **out);

Create and return an oskit_socket thread-safe adaptor.

in:

The oskit_socket COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_socket adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_stream(struct oskit_stream *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_stream **out);

Create and return an oskit_dir thread-safe adaptor.

in:

The oskit_stream COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_stream adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_asyncio(struct oskit_asyncio *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_asyncio **out);

Create and return an oskit_dir thread-safe adaptor.

in:

The oskit_asyncio COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_asyncio adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_sockio(struct oskit_sockio *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_sockio **out);

Create and return an oskit_dir thread-safe adaptor.

in:

The oskit_sockio COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_sockio adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_posixio(struct oskit_posixio *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_posixio **out);

Create and return an oskit_dir thread-safe adaptor.

in:

The oskit_posixio COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_posixio adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_file(struct oskit_file *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_file **out);

Create and return an oskit_dir thread-safe adaptor.

in:

The oskit_file COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_file adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_dir(struct oskit_dir *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_dir **out);

Create and return an oskit_dir thread-safe adaptor.

in:

The oskit_dir COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_dir adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_filesystem(struct oskit_filesystem *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_filesystem **out);

Create and return an oskit_dir thread-safe adaptor.

in:

The oskit_filesystem COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_filesystem adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_openfile(struct oskit_openfile *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_openfile **out);

Create and return an oskit_dir thread-safe adaptor.

in:

The oskit_openfile COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_openfile adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_blkio(struct oskit_blkio *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_blkio **out);

Create and return an oskit_blkio thread-safe adaptor.

in:

The oskit_blkio COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_blkio adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/com/wrapper.h>

oskit_error_t oskit_wrap_absio(struct oskit_absio *in, void (*lock)(void *), void (*unlock)(void *), void *cookie, struct oskit_absio **out);

Create and return an oskit_absio thread-safe adaptor.

in:

The oskit_absio COM interface to be wrapped.

lock:

The process lock routine.

unlock:

The process unlock routine.

cookie:

A cookie to be passed to the lock and unlock routines.

out:

The oskit_absio adaptor COM interface.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/threads/pthread.h>
#include <oskit/threads/ipc.h>

oskit_error_t oskit_ipc_send(pthread_t dst, void *msg, oskit_size_t msg_size, oskit_s32_t timeout);

Send a message to another thread. The destination thread is specified by its pthread_t. The sending thread blocks until the receiving thread notices the message and actually initiates a receive operation for it. Control returns to the caller only when the receiver has initiated the receive.

The timeout value is currently ignored.

dst:

The pthread_t of the destination thread.

msg:

The message buffer.

msg_size:

The size of the message, in bytes.

timeout:

A timeout value. Currently ignored.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/threads/pthread.h>
#include <oskit/threads/ipc.h>

oskit_error_t oskit_ipc_recv(pthread_t src, void *msg, oskit_size_t msg_size, oskit_size_t *actual, oskit_s32_t timeout);

Receive a message from another thread. The sending thread is specified by its pthread_t. If the specified sending thread has not attempted to send a message to current thread, the thread is blocked until such time as the sender initiates a send operation to the current thread. However, if the sender is blocked trying to send a message to the current thread, the message is immediately received and the sender is woken up.

The timeout value is either zero or non-zero. A zero value means do not wait, but simply check to see if a message from the sender is pending. A non-zero value means wait forever.

src:

The pthread_t of the sending thread.

msg:

The message buffer.

msg_size:

The size of the message buffer, in bytes.

actual:

The location in which to place the number of bytes received.

timeout:

A timeout value. Currently only zero and non-zero values are legal. Zero means no wait, non-zero means wait forever.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/threads/pthread.h>
#include <oskit/threads/ipc.h>

oskit_error_t oskit_ipc_wait(pthread_t *src, void *msg, oskit_size_t msg_size, oskit_size_t *actual, oskit_s32_t timeout);

This function operates identically to oskit_ipc_recv, except that the sending thread does not need to be a specific thread. The first thread that attempts to send to the current thread will succeed. The pthread_t of that thread is returned to the caller in src.

src:

The location in which to place the pthread_t of the sending thread.

msg:

The message buffer.

msg_size:

The size of the message buffer, in bytes.

actual:

The location in which to place the number of bytes received.

timeout:

A timeout value. Currently only zero and non-zero values are legal. Zero means no wait, non-zero means wait forever.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/threads/pthread.h>
#include <oskit/threads/ipc.h>

oskit_error_t oskit_ipc_call(pthread_t dst, void *sendmsg, oskit_size_t sendmsg_size, void *recvmsg, oskit_size_t recvmsg_size, oskit_size_t *actual, oskit_s32_t timeout);

Make a synchronous IPC call to another thread, and wait for a reply. The destination thread is specified by its pthread_t. The sending thread is blocked until the receiving thread replies to the IPC using oskit_ipc_reply. The send buffer and the reply buffer are specified separately, with the actual number bytes contained in the reply returned in the location pointed to by actual.

dst:

The pthread_t of the destination thread.

sendmsg:

The message buffer to send.

sendmsg_size:

The size of the send message buffer, in bytes.

recvmsg:

The message receive buffer.

recvmsg_size:

The size of the receive message buffer, in bytes.

actual:

The location in which to place the number of bytes contained in the reply message.

timeout:

A timeout value. Currently ignored.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/threads/pthread.h>
#include <oskit/threads/ipc.h>

oskit_error_t oskit_ipc_reply(pthread_t src, void *msg, oskit_size_t msg_size);

Reply to a synchronous IPC invocation made with oskit_ipc_call. The destination thread is specified by its pthread_t, and it must be blocked in a call operation, waiting for the reply message. If the destination thread is canceled before the reply is made, this call with return OSKIT_ECANCELED.

dst:

The pthread_t of the destination thread.

msg:

The message buffer.

msg_size:

The size of the message, in bytes.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>

void pthread_sched_become_scheduler(void);

Inform the CPU inheritance framework that the current thread is an application level scheduler. Certain initializations are performed that allow the current thread to donate its own CPU resources to other threads, and to receive scheduling messages regarding threads under its controls. Once this call is performed, the thread will generally enter a loop waiting for scheduling messages to inform it of new threads that it needs to schedule, or changes in the status of threads already under its control. For example, when a thread blocked on a mutex finally takes the mutex, an unblock message will be sent to that thread’s scheduler informing it that the thread in question should now be run.

#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>

int pthread_sched_donate_wait_recv(pthread_t tid, sched_wakecond_t wakecond, schedmsg_t *msg, oskit_s32_t timeout);

Donate CPU time to a target thread whose pthread identifier is tid. The donation will terminate when the thread gives up the CPU, or when the timeout value is reached. In this way, a scheduler can implement preemptive scheduling by allowing each thread to run for a maximum time value, at which time control returns to the dontating scheduler.

The wakecond flag specifies under which circumstances control should be returned to the scheduler when the target thread blocks. There are currently just two values allowed:

WAKEUP_ON_BLOCK:

Control returns to the scheduler whenever the target thread blocks or otherwise gives up the CPU. This allows the scheduler to make a new scheduling decision.

WAKEUP_ON_SWITCH:

Control returns to the scheduler’s scheduler whenever the target thread blocks or otherwise gives up the CPU. This is typically used when a scheduler has just one thread to schedule, and is not interested in when the target thread blocks or unblocks, but only when some other thread wakes up, requiring an actual scheduling decision to be made.

The return value indicates how the donation was terminated, and is one of the following constants. Its is up to the scheduler to determine the course of action. For example, a donation that returns a SCHEDULE_YIELDED would typically result in the target thread being placed back on the scheduler’s run queue so that it will be run at some later point.

SCHEDULE_NOTREADY:

The target thread is not ready to receive the donation, perhaps because the target thread is blocked.

SCHEDULE_BLOCKED:

The target thread ran and then blocked for some reason. The thread should not be run until the scheduler receives an MSG_SCHED_UNBLOCK message for the target thread.

SCHEDULE_YIELDED:

The target thread ran and then voluntarily gave up the CPU. The thread will typically be placed back on the run queue for that scheduler.

SCHEDULE_PREEMPTED:

The target thread ran and was then preempted by the threads system. The thread will typically be placed back on the run queue for that scheduler.

SCHEDULE_TIMEDOUT:

The target thread ran until the timeout expired, and was then preempted so that the scheduler may pick another thread to run. The thread will typically be placed back on the run queue for that scheduler.

SCHEDULE_MSGRECV:

This constant is bitwise or’ed into the result value whenever a thread donation terminates and a scheduling message was returned in the message block pointed to by msg. The scheduler will need to take appropriate action based on the both the return value of the donation, and the contents of the message.

Upon return from the donation, it is possible that a scheduling message will also be ready. Rather than have the scheduler invoke a separate message operation to retrieve the message, the message reception operation is combined with the donation. This is indicated in the return value when the SCHEDULE_MSGRECV bit is set. The format of the message is as follows:

typedef struct schedmsg {                  schedmsg_types_t        type;                  pthread_t               tid;                  oskit_u32_t             opaque;                  oskit_u32_t             opaque2;          } schedmsg_t;

The message refers to the thread identifed by tid, while opaque and opaque2 are message specific values. Only some message types have associated message values (described below). The message types are as follows:

MSG_SCHED_NEWTHREAD:

A new thread was created for the current scheduler. The scheduler for a thread is specified using the thread attributes and the textttpthread_attr_setscheduler routine. Once the thread is created and ready to be scheduled, a message is sent to the specified scheduler so that it may set up the necessary data structures, and add the new thread to its run queue. The thread id of the new thread is given by the tid field of the message. Depending on the scheduler, the opaque and opaque2 fields may also be valid.

MSG_SCHED_UNBLOCK:

The thread specified by the tid field of the message has been unblocked. The scheduler will typically add the thread to its internal run queue so that it will be run again.

MSG_SCHED_SETSTATE:

Alter the scheduling parameters for the thread specified by the tid field. This message is sent as a result of the application calling pthread_sched_setstate. The opaque and opaque2 fields are obviously specific to the scheduler.

MSG_SCHED_EXITED:

The thread specified by the tid field of the message has called pthread_exit. The scheduler will typically remove the thread from its internal data structures and free any associated resources.

tid:

The pthread_t of the thread to donate to.

wakecond:

The wakeup condition.

msg:

A message buffer in which to place a message if one is available when the donation ends.

timeout:

A timeout value, in milliseconds. The donation will be terminated after the time has elapsed.

The return values are described above.

pthread_sched_setstate, pthread_attr_setscheduler

#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>

oskit_error_t pthread_sched_message_recv(schedmsg_t *msg, oskit_s32_t timeout);

Initiate a scheduling message receive operation. If there are any scheduling messages queued on the scheduler’s message queue, the first message will be dequeued and copied into the message buffer pointed to by msg. The format of the message is described in Section 29.7.2. If timeout is zero, and no message is ready for delivery, the call will return immediately with the error value OSKIT_EAGAIN. If timeout is any non-zero value, the caller will block until a message is available. A future release will allow the specification of an actual timeout value.

msg:

A message buffer in which to place a message if one is available.

timeout:

A timeout value, in milliseconds.

Returns 0 on success, or OSKIT_EAGAIN if the caller specified a non-blocking receive and no message was available.

pthread_sched_donate_wait_recv

#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>

int pthread_sched_setstate(pthread_t tid, int opaque);

Change the scheduling parameter for the thread specified by tid. An scheduler specific opaque value should be passed, which is then sent via a scheduling message to the message queue of the scheduler responsible for the given thread. This interface routine is entirely ad-hoc, and is intended to be used until something better is formulated.

tid:

The pthread_t of the thread to donate to.

opaque:

An opaque value that hopefully makes sense to the thread’s scheduler.

Always returns zero.

#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>

int pthread_cond_donate_wait(pthread_cond_t *c, pthread_mutex_t *m, oskit_timespec_t *abstime, pthread_t donee_tid);

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.

In addition to the normal operation for timed conditional wait, the caller specifies a thread to which the current thread’s CPU time should be donated. This allows a thread to wait on a condition, but specify that any CPU time that it would have received is donated to thread donee_tid.

cond:

A pointer to the condition variable object.

mutex:

A pointer to the mutex object.

abstime:

A pointer to an oskit_timespec structure.

donee_tid:

The pthread_t of the thread to which the current thread’s CPU time should be donated.

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

#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>

int pthread_attr_setscheduler(pthread_attr_t *attr, pthread_t tid);

Set the scheduler thread in a previously initialized threads attribute object, for use with pthread_create. Any thread created with the given attributes object will have it’s scheduler thread set to tid. The caller can thus set up an arbitrary scheduler and thread hierarchy by using this routine.

attr:

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

tid:

The pthread_t of the thread that will function as the scheduler for new threads.

Returns zero on success.

pthread_attr_setopaque

#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>

int pthread_attr_setopaque(pthread_attr_t *attr, oskit_u32_t opaque);

Set the scheduling parameter in a previously initialized threads attribute object, for use with pthread_create. This opaque value will be passed to the thread’s scheduler in the initial MSG_SCHED_NEWTHREAD message, after the thread is created and ready to be scheduled. The opaque value should make sense to the scheduler selected with pthread_attr_setscheduler.

attr:

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

opaque:

An opaque value that hopefully makes sense to the scheduler.

Returns zero on success.

pthread_attr_setscheduler

#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>

int create_fixedpri_scheduler(pthread_t *tid, const pthread_attr_t *attr, int preemptible);

Create a new Fixed Priority scheduler. The pthread_t of the new scheduler is returned in tid. The attributes structure to use when creating the new thread is attr. The preemptible flag indicates whether the new scheduler should use time-based preemption to achieve fairness. Aside from the usual attributes that can be specified, the caller may also specify the new scheduler’s scheduler by using pthread_attr_setscheduler. Thus, the caller can set up an arbitrary hierarchy of schedulers and threads.

This fixed priority scheduler roughly corresponds to the POSIX pthread scheduler, and implements both FIFO and round robin policies. The standard pthread scheduling interface routines may be used when altering the scheduling parameters for threads that are scheduled by this scheduler.

tid:

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

attr:

A pointer to the thread creation attributes object.

preemptible:

A flag indicating whether the new scheduler should use time-based preemption.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>

int create_lotto_scheduler(pthread_t *tid, const pthread_attr_t *attr, int preemptible);

Create a new Lottery scheduler. The pthread_t of the new scheduler is returned in tid. The attributes structure to use when creating the new thread is attr. The preemptible flag indicates whether the new scheduler should use time-based preemption to achieve fairness. Aside from the usual attributes that can be specified, the caller may also specify the new scheduler’s scheduler by using pthread_attr_setscheduler. Thus, the caller can set up an arbitrary hierarchy of schedulers and threads.

When creating threads that are scheduled by a Lottery scheduler, the caller should set the opaque scheduling parameter in the thread creation attributes structure. This opaque value represents a ticket value, and should be an integer (usually a small to moderately sized integer). As with any Lottery scheduler, the larger the ticket value, the more CPU a thread is likely to receive.

tid:

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

attr:

A pointer to the thread creation attributes object.

preemptible:

A flag indicating whether the new scheduler should use time-based preemption.

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

#include <oskit/threads/pthread.h>
#include <oskit/threads/cpuinherit.h>

int create_stride_scheduler(pthread_t *tid, const pthread_attr_t *attr, int preemptible);

Create a new Stride scheduler. The pthread_t of the new scheduler is returned in tid. The attributes structure to use when creating the new thread is attr. The preemptible flag indicates whether the new scheduler should use time-based preemption to achieve fairness. Aside from the usual attributes that can be specified, the caller may also specify the new scheduler’s scheduler by using pthread_attr_setscheduler. Thus, the caller can set up an arbitrary hierarchy of schedulers and threads.

When creating threads that are scheduled by a Stride scheduler, the caller should set the opaque scheduling parameter in the thread creation attributes structure. This opaque value represents a ticket value, and should be an integer (usually a small to moderately sized integer). As with any Stride scheduler, the larger the ticket value, the more CPU a thread is likely to receive.

tid:

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

attr:

A pointer to the thread creation attributes object.

preemptible:

A flag indicating whether the new scheduler should use time-based preemption.