KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
genwait.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2 
3  include/kos/genwait.h
4  Copyright (C) 2003 Dan Potter
5  Copyright (C) 2012 Lawrence Sebald
6 
7 */
8 
9 /** \file kos/genwait.h
10  \brief Generic wait system.
11 
12  The generic wait system in KOS, like many other portions of KOS, is based on
13  an idea from the BSD kernel. It allows you to sleep on any random object and
14  later wake up any threads that happen to be sleeping on thta object. All of
15  KOS' sync primatives (other than spinlocks) are based on this concept, and
16  it can be used for some fairly useful things.
17 
18  \author Dan Potter
19  \author Lawrence Sebald
20 */
21 
22 #ifndef __KOS_GENWAIT_H
23 #define __KOS_GENWAIT_H
24 
25 #include <sys/cdefs.h>
26 __BEGIN_DECLS
27 
28 #include <kos/thread.h>
29 
30 /** \brief Sleep on an object.
31 
32  This function sleeps on the specified object. You are not allowed to call
33  this function inside an interrupt.
34 
35  \param obj The object to sleep on
36  \param mesg A message to show in the status
37  \param timeout If not woken before this many milliseconds have
38  passed, wake up anyway
39  \param callback If non-NULL, call this function with obj as its
40  argument if the wait times out (but before the
41  calling thread has been woken back up)
42  \retval 0 On successfully being woken up (not by timeout)
43  \retval -1 On error or being woken by timeout
44 
45  \par Error Conditions:
46  \em EAGAIN - on timeout
47 */
48 int genwait_wait(void * obj, const char * mesg, int timeout, void (*callback)(void *));
49 
50 /* Wake up N threads waiting on the given object. If cnt is <=0, then we
51  wake all threads. Returns the number of threads actually woken. */
52 /** \brief Wake up a number of threads sleeping on an object.
53 
54  This function wakes up the specified number of threads sleeping on the
55  object specified.
56 
57  \param obj The object to wake threads that are sleeping on it
58  \param cnt The number of threads to wake, if <= 0, wake all
59  \param err The errno code to set as the errno value on the
60  woken threads. If this is 0 (EOK), then the thread's
61  errno will not be changed, and the thread will get a
62  return value of 0 from the genwait_wait(). If it is
63  non-zero, the thread will get a return value of -1
64  and errno will be set to this value for the woken
65  threads.
66  \return The number of threads woken
67 */
68 int genwait_wake_cnt(void * obj, int cnt, int err);
69 
70 /** \brief Wake up all threads sleeping on an object.
71 
72  This function simply calls genwait_wake_cnt(obj, -1, 0).
73 
74  \param obj The object to wake threads that are sleeping on it
75  \see genwait_wake_cnt()
76 */
77 void genwait_wake_all(void * obj);
78 
79 /** \brief Wake up one thread sleeping on an object.
80 
81  This function simply calls genwait_wake_cnt(obj, 1, 0).
82 
83  \param obj The object to wake threads that are sleeping on it
84  \see genwait_wake_cnt()
85 */
86 void genwait_wake_one(void * obj);
87 
88 /** \brief Wake up all threads sleeping on an object, with an error.
89 
90  This function simply calls genwait_wake_cnt(obj, -1, err).
91 
92  \param obj The object to wake threads that are sleeping on it
93  \param err The value to set in the threads' errno values
94  \see genwait_wake_cnt()
95 */
96 void genwait_wake_all_err(void *obj, int err);
97 
98 /** \brief Wake up one thread sleeping on an object, with an error.
99 
100  This function simply calls genwait_wake_cnt(obj, 1, err).
101 
102  \param obj The object to wake threads that are sleeping on it
103  \param err The value to set in the threads' errno values
104  \see genwait_wake_cnt()
105 */
106 void genwait_wake_one_err(void *obj, int err);
107 
108 /** \brief Wake up a specific thread that is sleeping on an object.
109 
110  This function wakes up the specfied thread, assuming it is sleeping on the
111  specified object.
112 
113  \param obj The object to wake the thread from
114  \param thd The specific thread to wake
115  \param err The errno code to set as the errno value on the
116  woken thread. If this is 0 (EOK), then the thread's
117  errno will not be changed, and the thread will get a
118  return value of 0 from the genwait_wait(). If it is
119  non-zero, the thread will get a return value of -1
120  and errno will be set to this value for the woken
121  threads.
122  \return The number of threads woken, which should be 1 on
123  success.
124 */
125 int genwait_wake_thd(void *obj, kthread_t *thd, int err);
126 
127 /** \brief Look for timed out genwait_wait() calls.
128 
129  There should be no reason you need to call this function, it is called
130  internally by the scheduler for you.
131 
132  \param now The current system time, in milliseconds since boot
133 */
134 void genwait_check_timeouts(uint64 now);
135 
136 /** \brief Look for the next timeout event time.
137 
138  This function looks up when the next genwait_wait() call will timeout. This
139  function is for the internal use of the scheduler, and should not be called
140  from user code.
141 
142  \return The next timeout time in milliseconds since boot, or
143  0 if there are no pending genwait_wait() calls
144 */
145 uint64 genwait_next_timeout();
146 
147 /** \cond */
148 /* Initialize the genwait system */
149 int genwait_init();
150 
151 /* Shut down the genwait system */
152 void genwait_shutdown();
153 /** \endcond */
154 
155 
156 __END_DECLS
157 
158 #endif /* __KOS_GENWAIT_H */
159 
Generated by   doxygen 1.8.1.1