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 (void)
	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 that object. All of KOS' sync primitives (other than spinlocks) are based on this concept, and it can be used for some fairly useful things.

Author

Megan Potter

Lawrence Sebald

Function Documentation

genwait_check_timeouts()

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

now	The current system time, in milliseconds since boot

genwait_next_timeout()

uint64 genwait_next_timeout

(

void

)

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

genwait_wait()

int genwait_wait	(	void *	obj,
		const char *	mesg,
		int	timeout,
		void(*	callback )(void *) )

Sleep on an object.

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

Parameters

obj	The object to sleep on
mesg	A message to show in the status
timeout	If not woken before this many milliseconds have passed, wake up anyway
callback	If 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

0	On successfully being woken up (not by timeout)
-1	On error or being woken by timeout

Error Conditions:

EAGAIN - on timeout

genwait_wake_all()

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

obj	The object to wake threads that are sleeping on it

See also

genwait_wake_cnt()

genwait_wake_all_err()

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

obj	The object to wake threads that are sleeping on it
err	The value to set in the threads' errno values

See also

genwait_wake_cnt()

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

obj	The object to wake threads that are sleeping on it
cnt	The number of threads to wake, if <= 0, wake all
err	The 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

genwait_wake_one()

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

obj	The object to wake threads that are sleeping on it

See also

genwait_wake_cnt()

genwait_wake_one_err()

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

obj	The object to wake threads that are sleeping on it
err	The value to set in the threads' errno values

See also

genwait_wake_cnt()

genwait_wake_thd()

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 specified thread, assuming it is sleeping on the specified object.

Parameters

obj	The object to wake the thread from
thd	The specific thread to wake
err	The 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.