Generic wait system. More...

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

Functions
int	genwait_wait (void obj, const char mesg, int timeout, void(callback)(void ))
	Sleep on an object. More...

int	genwait_wake_cnt (void *obj, int cnt, int err)
	Wake up a number of threads sleeping on an object. More...

void	genwait_wake_all (void *obj)
	Wake up all threads sleeping on an object. More...

void	genwait_wake_one (void *obj)
	Wake up one thread sleeping on an object. More...

void	genwait_wake_all_err (void *obj, int err)
	Wake up all threads sleeping on an object, with an error. More...

void	genwait_wake_one_err (void *obj, int err)
	Wake up one thread sleeping on an object, with an error. More...

int	genwait_wake_thd (void obj, kthread_t thd, int err)
	Wake up a specific thread that is sleeping on an object. More...

void	genwait_check_timeouts (uint64 now)
	Look for timed out genwait_wait() calls. More...

uint64	genwait_next_timeout ()
	Look for the next timeout event time. More...

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

now	The 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

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

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()

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()

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

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()

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()

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

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.

Functions

Detailed Description

Function Documentation