1 /*------------------------------------------------------------- 2 3 lwp.h -- Thread subsystem I 4 5 Copyright (C) 2004 6 Michael Wiedenbauer (shagkur) 7 Dave Murphy (WinterMute) 8 9 This software is provided 'as-is', without any express or implied 10 warranty. In no event will the authors be held liable for any 11 damages arising from the use of this software. 12 13 Permission is granted to anyone to use this software for any 14 purpose, including commercial applications, and to alter it and 15 redistribute it freely, subject to the following restrictions: 16 17 1. The origin of this software must not be misrepresented; you 18 must not claim that you wrote the original software. If you use 19 this software in a product, an acknowledgment in the product 20 documentation would be appreciated but is not required. 21 22 2. Altered source versions must be plainly marked as such, and 23 must not be misrepresented as being the original software. 24 25 3. This notice may not be removed or altered from any source 26 distribution. 27 28 -------------------------------------------------------------*/ 29 30 #ifndef __LWP_H__ 31 #define __LWP_H__ 32 33 /*! \file lwp.h 34 \brief Thread subsystem I 35 36 */ 37 38 #include <gctypes.h> 39 40 #define LWP_CLOSED -1 41 #define LWP_SUCCESSFUL 0 42 #define LWP_ALREADY_SUSPENDED 1 43 #define LWP_NOT_SUSPENDED 2 44 45 #define LWP_PRIO_IDLE 0 46 #define LWP_PRIO_HIGHEST 127 47 48 #define LWP_THREAD_NULL 0xffffffff 49 #define LWP_TQUEUE_NULL 0xffffffff 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /*! \typedef u32 lwp_t 56 \brief typedef for the thread context handle 57 */ 58 typedef u32 lwp_t; 59 60 /*! \typedef u32 lwpq_t 61 \brief typedef for the thread queue's context handle 62 */ 63 typedef u32 lwpq_t; 64 65 /*! \fn s32 LWP_CreateThread(lwp_t *thethread,void* (*entry)(void *),void *arg,void *stackbase,u32 stack_size,u8 prio) 66 \brief Spawn a new thread with the given parameters 67 \param[out] thethread pointer to a lwp_t handle 68 \param[in] entry pointer to the thread's entry function. 69 \param[in] arg pointer to an argument for the thread's entry function. 70 \param[in] stackbase pointer to the threads stackbase address. If NULL, the stack is allocated by the thread system. 71 \param[in] stack_size size of the provided stack. If 0, the default STACKSIZE of 8Kb is taken. 72 \param[in] prio priority on which the newly created thread runs. 73 74 \return 0 on success, <0 on error 75 */ 76 s32 LWP_CreateThread(lwp_t *thethread,void* (*entry)(void *),void *arg,void *stackbase,u32 stack_size,u8 prio); 77 78 /*! \fn s32 LWP_SuspendThread(lwp_t thethread) 79 \brief Suspend the given thread. 80 \param[in] thethread handle to the thread context which should be suspended. 81 82 \return 0 on success, <0 on error 83 */ 84 s32 LWP_SuspendThread(lwp_t thethread); 85 86 /*! \fn s32 LWP_ResumeThread(lwp_t thethread) 87 \brief Resume the given thread. 88 \param[in] thethread handle to the thread context which should be resumed. 89 90 \return 0 on success, <0 on error 91 */ 92 s32 LWP_ResumeThread(lwp_t thethread); 93 94 /*! \fn BOOL LWP_ThreadIsSuspended(lwp_t thethread) 95 \brief Test whether the given thread is suspended or not 96 \param[in] thethread handle to the thread context which should be tested. 97 98 \return TRUE or FALSE 99 */ 100 BOOL LWP_ThreadIsSuspended(lwp_t thethread); 101 102 /*! \fn lwp_t LWP_GetSelf() 103 \brief Return the handle to the current thread. 104 105 \return thread context handle 106 */ 107 lwp_t LWP_GetSelf(); 108 109 /*! \fn void LWP_SetThreadPriority(lwp_t thethread,u32 prio) 110 \brief Set the priority of the given thread. 111 \param[in] thethread handle to the thread context whos priority should be changed. If NULL, the current thread will be taken. 112 \param[in] prio new priority to set 113 114 \return none 115 */ 116 void LWP_SetThreadPriority(lwp_t thethread,u32 prio); 117 118 /*! \fn void LWP_YieldThread() 119 \brief Yield the current thread to another one with higher priority or if not running at the same priority which state is runnable. 120 121 \return none 122 */ 123 void LWP_YieldThread(); 124 125 /*! \fn void LWP_Reschedule(u32 prio) 126 \brief Reschedule all threads running at the given priority 127 \param[in] prio priority level to reschedule 128 129 \return none 130 */ 131 void LWP_Reschedule(u32 prio); 132 133 /*! \fn s32 LWP_JoinThread(lwp_t thethread,void **value_ptr) 134 \brief Join the given thread. 135 \param[in] thethread handle to the thread's context which should be joined to wait on termination. 136 \param[in] value_ptr pointer-pointer to a variable to receive the return code of the terminated thread. 137 138 \return 0 on success, <0 on error 139 */ 140 s32 LWP_JoinThread(lwp_t thethread,void **value_ptr); 141 142 /*! \fn void LWP_InitQueue(lwpq_t *thequeue) 143 \brief Initialize the thread synchronization queue 144 \param[in] thequeue pointer to a lwpq_t handle. 145 146 \return 0 on success, <0 on error 147 */ 148 s32 LWP_InitQueue(lwpq_t *thequeue); 149 150 /*! \fn void LWP_CloseQueue(lwpq_t thequeue) 151 \brief Close the thread synchronization queue and releas the handle 152 \param[in] thequeue handle to the thread's synchronization queue 153 154 \return none 155 */ 156 void LWP_CloseQueue(lwpq_t thequeue); 157 158 /*! \fn s32 LWP_ThreadSleep(lwpq_t thequeue) 159 \brief Pushes the current thread onto the given thread synchronization queue and sets the thread state to blocked. 160 \param[in] thequeue handle to the thread's synchronization queue to push the thread on 161 162 \return none 163 */ 164 s32 LWP_ThreadSleep(lwpq_t thequeue); 165 166 /*! \fn void LWP_ThreadSignal(lwpq_t thequeue) 167 \brief Signals one thread to be revmoved from the thread synchronization queue and sets it back to running state. 168 \param[in] thequeue handle to the thread's synchronization queue to pop the blocked thread off 169 170 \return none 171 */ 172 void LWP_ThreadSignal(lwpq_t thequeue); 173 174 /*! \fn void LWP_ThreadBroadcast(lwpq_t thequeue) 175 \brief Removes all blocked threads from the thread synchronization queue and sets them back to running state. 176 \param[in] thequeue handle to the thread's synchronization queue to pop the blocked threads off 177 178 \return none 179 */ 180 void LWP_ThreadBroadcast(lwpq_t thequeue); 181 182 #ifdef __cplusplus 183 } 184 #endif 185 186 #endif 187