KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Functions
genwait.h File Reference

Generic wait system. More...

#include <sys/cdefs.h>
#include <kos/thread.h>

Go to the source code of this file.

Functions

int genwait_wait (void *obj, const char *mesg, int timeout, void(*callback)(void *))
 Sleep on an object.
int genwait_wake_cnt (void *obj, int cnt, int err)
 Wake up a number of threads sleeping on an object.
void genwait_wake_all (void *obj)
 Wake up all threads sleeping on an object.
void genwait_wake_one (void *obj)
 Wake up one thread sleeping on an object.
void genwait_wake_all_err (void *obj, int err)
 Wake up all threads sleeping on an object, with an error.
void genwait_wake_one_err (void *obj, int err)
 Wake up one thread sleeping on an object, with an error.
int genwait_wake_thd (void *obj, kthread_t *thd, int err)
 Wake up a specific thread that is sleeping on an object.
void genwait_check_timeouts (uint64 now)
 Look for timed out genwait_wait() calls.
uint64 genwait_next_timeout ()
 Look for the next timeout event time.

Detailed Description

Generic wait system.

The generic wait system in KOS, like many other portions of KOS, is based on an idea from the BSD kernel. It allows you to sleep on any random object and later wake up any threads that happen to be sleeping on thta object. All of KOS' sync primatives (other than spinlocks) are based on this concept, and it can be used for some fairly useful things.

Author:
Dan Potter
Lawrence Sebald

Function Documentation

void genwait_check_timeouts ( uint64  now)

Look for timed out genwait_wait() calls.

There should be no reason you need to call this function, it is called internally by the scheduler for you.

Parameters:
nowThe current system time, in milliseconds since boot
uint64 genwait_next_timeout ( )

Look for the next timeout event time.

This function looks up when the next genwait_wait() call will timeout. This function is for the internal use of the scheduler, and should not be called from user code.

Returns:
The next timeout time in milliseconds since boot, or 0 if there are no pending genwait_wait() calls
int genwait_wait ( void *  obj,
const char *  mesg,
int  timeout,
void(*)(void *)  callback 
)

Sleep on an object.

This function sleeps on the specified object. You are not allowed to call this function inside an interrupt.

Parameters:
objThe object to sleep on
mesgA message to show in the status
timeoutIf not woken before this many milliseconds have passed, wake up anyway
callbackIf non-NULL, call this function with obj as its argument if the wait times out (but before the calling thread has been woken back up)
Return values:
0On successfully being woken up (not by timeout)
-1On error or being woken by timeout
Error Conditions:
EAGAIN - on timeout
void genwait_wake_all ( void *  obj)

Wake up all threads sleeping on an object.

This function simply calls genwait_wake_cnt(obj, -1, 0).

Parameters:
objThe object to wake threads that are sleeping on it
See also:
genwait_wake_cnt()
void genwait_wake_all_err ( void *  obj,
int  err 
)

Wake up all threads sleeping on an object, with an error.

This function simply calls genwait_wake_cnt(obj, -1, err).

Parameters:
objThe object to wake threads that are sleeping on it
errThe value to set in the threads' errno values
See also:
genwait_wake_cnt()
int genwait_wake_cnt ( void *  obj,
int  cnt,
int  err 
)

Wake up a number of threads sleeping on an object.

This function wakes up the specified number of threads sleeping on the object specified.

Parameters:
objThe object to wake threads that are sleeping on it
cntThe number of threads to wake, if <= 0, wake all
errThe errno code to set as the errno value on the woken threads. If this is 0 (EOK), then the thread's errno will not be changed, and the thread will get a return value of 0 from the genwait_wait(). If it is non-zero, the thread will get a return value of -1 and errno will be set to this value for the woken threads.
Returns:
The number of threads woken
void genwait_wake_one ( void *  obj)

Wake up one thread sleeping on an object.

This function simply calls genwait_wake_cnt(obj, 1, 0).

Parameters:
objThe object to wake threads that are sleeping on it
See also:
genwait_wake_cnt()
void genwait_wake_one_err ( void *  obj,
int  err 
)

Wake up one thread sleeping on an object, with an error.

This function simply calls genwait_wake_cnt(obj, 1, err).

Parameters:
objThe object to wake threads that are sleeping on it
errThe value to set in the threads' errno values
See also:
genwait_wake_cnt()
int genwait_wake_thd ( void *  obj,
kthread_t thd,
int  err 
)

Wake up a specific thread that is sleeping on an object.

This function wakes up the specfied thread, assuming it is sleeping on the specified object.

Parameters:
objThe object to wake the thread from
thdThe specific thread to wake
errThe errno code to set as the errno value on the woken thread. If this is 0 (EOK), then the thread's errno will not be changed, and the thread will get a return value of 0 from the genwait_wait(). If it is non-zero, the thread will get a return value of -1 and errno will be set to this value for the woken threads.
Returns:
The number of threads woken, which should be 1 on success.