tstools/DtsEdit/src/gpac/thread.h

   1 /*\r
   2  *                      GPAC - Multimedia Framework C SDK\r
   3  *\r
   4  *                      Copyright (c) Jean Le Feuvre 2000-2005 \r
   5  *                                      All rights reserved\r
   6  *\r
   7  *  This file is part of GPAC / common tools sub-project\r
   8  *\r
   9  *  GPAC is free software; you can redistribute it and/or modify\r
  10  *  it under the terms of the GNU Lesser General Public License as published by\r
  11  *  the Free Software Foundation; either version 2, or (at your option)\r
  12  *  any later version.\r
  13  *   \r
  14  *  GPAC is distributed in the hope that it will be useful,\r
  15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  17  *  GNU Lesser General Public License for more details.\r
  18  *   \r
  19  *  You should have received a copy of the GNU Lesser General Public\r
  20  *  License along with this library; see the file COPYING.  If not, write to\r
  21  *  the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. \r
  22  *\r
  23  */\r
  24 \r
  25 #ifndef _GF_THREAD_H_\r
  26 #define _GF_THREAD_H_\r
  27 \r
  28 #ifdef __cplusplus\r
  29 extern "C" {\r
  30 #endif\r
  31 \r
  32 /*!\r
  33  *      \file <gpac/thread.h>\r
  34  *      \brief threading functions.\r
  35  */\r
  36 \r
  37  /*!\r
  38  *      \addtogroup thr_grp threading\r
  39  *      \ingroup utils_grp\r
  40  *      \brief Threading and Mutual Exclusion Functions\r
  41  *\r
  42  *This section documents the threading of the GPAC framework. These provide an easy way to implement\r
  43  *safe multithreaded tools.\r
  44  *      @{\r
  45  */\r
  46 \r
  47 #include <gpac/tools.h>\r
  48 \r
  49 /*!\r
  50  *\brief Thread states\r
  51  *\r
  52  *Inidcates the execution status of a thread\r
  53  */\r
  54 enum\r
  55 {\r
  56         /*! the thread has been initialized but is not started yet*/\r
  57         GF_THREAD_STATUS_STOP = 0,\r
  58         /*! the thread is running*/\r
  59         GF_THREAD_STATUS_RUN = 1,\r
  60         /*! the thread has exited its body function*/\r
  61         GF_THREAD_STATUS_DEAD = 2\r
  62 };\r
  63 \r
  64 /*!\r
  65  *\brief abstracted thread object\r
  66  *\r
  67  *The abstracted thread object allows you to execute some code independently of the main process of your application.\r
  68 */\r
  69 typedef struct __tag_thread GF_Thread;\r
  70 \r
  71 /*!\r
  72  *\brief thread constructor\r
  73  *\r
  74  *Constructs a new thread object\r
  75  *\param log name of the thread if any\r
  76  */\r
  77 GF_Thread *gf_th_new(const char *name);\r
  78 /*!\r
  79  *\brief thread destructor\r
  80  *\r
  81  * Kills the thread if running and destroys the object\r
  82  *\param th the thread object\r
  83  */\r
  84 void gf_th_del(GF_Thread *th);\r
  85 \r
  86 /*!\r
  87  *      \brief thread run function callback\r
  88  *\r
  89  *The gf_thread_run type is the type for the callback of the \ref gf_thread_run function\r
  90  *\param par opaque user data\r
  91  *\return exit code of the thread, usually 1 for error and 0 if normal execution\r
  92  *\r
  93  */\r
  94 typedef u32 (*gf_thread_run)(void *par);\r
  95 \r
  96 /*!\r
  97  *\brief thread execution\r
  98  *\r
  99  *Executes the thread with the given function\r
 100  *\param th the thread object\r
 101  *\param run the function this thread will call\r
 102  *\param par the argument to the function the thread will call\r
 103  *\note A thread may be run several times but cannot be run twice in the same time.\r
 104  */\r
 105 GF_Err gf_th_run(GF_Thread *th, gf_thread_run run, void *par);\r
 106 /*!\r
 107  *\brief thread stoping\r
 108  *\r
 109  *Waits for the thread exit until return\r
 110  *\param th the thread object\r
 111  */\r
 112 void gf_th_stop(GF_Thread *th);\r
 113 /*!\r
 114  *\brief thread status query\r
 115  *\r
 116  *Gets the thread status\r
 117  *\param th the thread object\r
 118  */\r
 119 u32 gf_th_status(GF_Thread *th);\r
 120 \r
 121 /*!\r
 122  * thread priorities\r
 123  */\r
 124 enum\r
 125 {\r
 126         /*!Idle Priority*/\r
 127         GF_THREAD_PRIORITY_IDLE=0,\r
 128         /*!Less Idle Priority*/\r
 129         GF_THREAD_PRIORITY_LESS_IDLE,\r
 130         /*!Lowest Priority*/\r
 131         GF_THREAD_PRIORITY_LOWEST,\r
 132         /*!Low Priority*/\r
 133         GF_THREAD_PRIORITY_LOW,\r
 134         /*!Normal Priority (the default one)*/\r
 135         GF_THREAD_PRIORITY_NORMAL,\r
 136         /*!High Priority*/\r
 137         GF_THREAD_PRIORITY_HIGH,\r
 138         /*!Highest Priority*/\r
 139         GF_THREAD_PRIORITY_HIGHEST,\r
 140         /*!First real-time priority*/\r
 141         GF_THREAD_PRIORITY_REALTIME,\r
 142         /*!Last real-time priority*/\r
 143         GF_THREAD_PRIORITY_REALTIME_END=255\r
 144 };\r
 145 \r
 146 /*!\r
 147  *\brief thread priority\r
 148  *\r
 149  *Sets the thread execution priority level.\r
 150  *\param th the thread object\r
 151  *\param priority the desired priority\r
 152  *\note this should be used with caution, especially use of real-time priorities.\r
 153  */\r
 154 void gf_th_set_priority(GF_Thread *th, s32 priority);\r
 155 /*!\r
 156  *\brief current thread ID \r
 157  *\r
 158  *Gets the ID of the current thread the caller is in.\r
 159 */\r
 160 u32 gf_th_id();\r
 161 \r
 162 \r
 163 \r
 164 /*!\r
 165  *\brief abstracted mutex object\r
 166  *\r
 167  *The abstracted mutex object allows you to make sure that portions of the code (typically access to variables) cannot be executed\r
 168  *by two threads (or a thread and the main process) at the same time.\r
 169 */\r
 170 typedef struct __tag_mutex GF_Mutex;\r
 171 /*\r
 172  *\brief mutex constructor\r
 173  *\r
 174  *Contructs a new mutex object\r
 175  *\param log name of the thread if any\r
 176 */\r
 177 GF_Mutex *gf_mx_new(const char *name);\r
 178 /*\r
 179  *\brief mutex denstructor\r
 180  *\r
 181  *Destroys a mutex object. This will wait for the mutex to be released if needed.\r
 182  *\param mx the mutex object\r
 183 */\r
 184 void gf_mx_del(GF_Mutex *mx);\r
 185 /*\r
 186  *\brief mutex locking\r
 187  *\r
 188  *Locks the mutex object, making sure that another thread locking this mutex cannot exectute until the mutex is unlocked.\r
 189  *\param mx the mutex object\r
 190  *\return 1 if success, 0 if error locking the mutex (which should never happen)\r
 191 */\r
 192 u32 gf_mx_p(GF_Mutex *mx);\r
 193 /*\r
 194  *\brief mutex unlocking\r
 195  *\r
 196  *Unlocks the mutex object, allowing other threads waiting on this mutex to continue their execution\r
 197  *\param mx the mutex object\r
 198 */\r
 199 void gf_mx_v(GF_Mutex *mx);\r
 200 /*\r
 201  *\brief mutex non-blocking lock\r
 202  *\r
 203  *Attemps to lock the mutex object without blocking until the object is released.\r
 204  *\param mx the mutex object\r
 205  *\return 1 if the mutex has been successfully locked, in which case it shall then be unlocked, or 0 if the mutex is locked by another thread.\r
 206 */\r
 207 Bool gf_mx_try_lock(GF_Mutex *mx);\r
 208 \r
 209 \r
 210 /*********************************************************************\r
 211                                         Semaphore Object\r
 212 **********************************************************************/\r
 213 /*!\r
 214  *\brief abstracted semaphore object\r
 215  *\r
 216  *The abstracted semaphore object allows you to control how portions of the code (typically access to variables) are executed\r
 217  *by two threads (or a thread and the main process) at the same time. The best image for a semaphore is a limited set \r
 218  *of money coins (always easy to understand hmm?). If no money is in the set, nobody can buy anything until a coin is \r
 219  *put back in the set. When the set is full, the money is wasted (call it "the bank"...).\r
 220 */\r
 221 typedef struct __tag_semaphore GF_Semaphore;\r
 222 /*\r
 223  *\brief semaphore constructor\r
 224  *\r
 225  *Constructs a new semaphore object\r
 226  *\param MaxCount the maximum notification count of this semaphore\r
 227  *\param InitCount the initial notification count of this semaphore upon construction\r
 228  *\return the semaphore object\r
 229  */\r
 230 GF_Semaphore *gf_sema_new(u32 MaxCount, u32 InitCount);\r
 231 /*\r
 232  *\brief semaphore destructor\r
 233  *\r
 234  *Destructs the semaphore object. This will wait for the semaphore to be released if needed.\r
 235  */\r
 236 void gf_sema_del(GF_Semaphore *sm);\r
 237 /*\r
 238  *\brief semaphore notifivation\r
 239  *\r
 240  *Notifies the semaphore of a certain amount of releases.\r
 241  *\param sm the semaphore object\r
 242  *\param nb_rel sm the number of release to notify\r
 243  *\return the number of previous notification count in the semaphore \r
 244 */\r
 245 u32 gf_sema_notify(GF_Semaphore *sm, u32 nb_rel);\r
 246 /*\r
 247  *\brief semaphore wait\r
 248  *\r
 249  *Waits for the semaphore to be accessible (eg, may wait an infinite time).\r
 250  *\param sm the semaphore object\r
 251 */\r
 252 void gf_sema_wait(GF_Semaphore *sm);\r
 253 /*\r
 254  *\brief semaphore time wait\r
 255  *\r
 256  *Waits for a certain for the semaphore to be accessible, and returns when semaphore is accessible or wait time has passed.\r
 257  *\param sm the semaphore object\r
 258  *\param time_out the amount of time to wait for the release in milliseconds\r
 259  *\return returns 1 if the semaphore was released before the timeout, 0 if the semaphore is still not released after the timeout.\r
 260 */\r
 261 Bool gf_sema_wait_for(GF_Semaphore *sm, u32 time_out);\r
 262 \r
 263 /*! @} */\r
 264 \r
 265 #ifdef __cplusplus\r
 266 }\r
 267 #endif\r
 268 \r
 269 \r
 270 #endif          /*_GF_THREAD_H_*/\r
 271 \r