2 * GPAC - Multimedia Framework C SDK
\r
4 * Copyright (c) Jean Le Feuvre 2000-2005
\r
5 * All rights reserved
\r
7 * This file is part of GPAC / common tools sub-project
\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
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
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
25 #ifndef _GF_THREAD_H_
\r
26 #define _GF_THREAD_H_
\r
33 * \file <gpac/thread.h>
\r
34 * \brief threading functions.
\r
38 * \addtogroup thr_grp threading
\r
39 * \ingroup utils_grp
\r
40 * \brief Threading and Mutual Exclusion Functions
\r
42 *This section documents the threading of the GPAC framework. These provide an easy way to implement
\r
43 *safe multithreaded tools.
\r
47 #include <gpac/tools.h>
\r
50 *\brief Thread states
\r
52 *Inidcates the execution status of a thread
\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
65 *\brief abstracted thread object
\r
67 *The abstracted thread object allows you to execute some code independently of the main process of your application.
\r
69 typedef struct __tag_thread GF_Thread;
\r
72 *\brief thread constructor
\r
74 *Constructs a new thread object
\r
75 *\param log name of the thread if any
\r
77 GF_Thread *gf_th_new(const char *name);
\r
79 *\brief thread destructor
\r
81 * Kills the thread if running and destroys the object
\r
82 *\param th the thread object
\r
84 void gf_th_del(GF_Thread *th);
\r
87 * \brief thread run function callback
\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
94 typedef u32 (*gf_thread_run)(void *par);
\r
97 *\brief thread execution
\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
105 GF_Err gf_th_run(GF_Thread *th, gf_thread_run run, void *par);
\r
107 *\brief thread stoping
\r
109 *Waits for the thread exit until return
\r
110 *\param th the thread object
\r
112 void gf_th_stop(GF_Thread *th);
\r
114 *\brief thread status query
\r
116 *Gets the thread status
\r
117 *\param th the thread object
\r
119 u32 gf_th_status(GF_Thread *th);
\r
122 * thread priorities
\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
133 GF_THREAD_PRIORITY_LOW,
\r
134 /*!Normal Priority (the default one)*/
\r
135 GF_THREAD_PRIORITY_NORMAL,
\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
147 *\brief thread priority
\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
154 void gf_th_set_priority(GF_Thread *th, s32 priority);
\r
156 *\brief current thread ID
\r
158 *Gets the ID of the current thread the caller is in.
\r
165 *\brief abstracted mutex object
\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
170 typedef struct __tag_mutex GF_Mutex;
\r
172 *\brief mutex constructor
\r
174 *Contructs a new mutex object
\r
175 *\param log name of the thread if any
\r
177 GF_Mutex *gf_mx_new(const char *name);
\r
179 *\brief mutex denstructor
\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
184 void gf_mx_del(GF_Mutex *mx);
\r
186 *\brief mutex locking
\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
192 u32 gf_mx_p(GF_Mutex *mx);
\r
194 *\brief mutex unlocking
\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
199 void gf_mx_v(GF_Mutex *mx);
\r
201 *\brief mutex non-blocking lock
\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
207 Bool gf_mx_try_lock(GF_Mutex *mx);
\r
210 /*********************************************************************
\r
212 **********************************************************************/
\r
214 *\brief abstracted semaphore object
\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
221 typedef struct __tag_semaphore GF_Semaphore;
\r
223 *\brief semaphore constructor
\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
230 GF_Semaphore *gf_sema_new(u32 MaxCount, u32 InitCount);
\r
232 *\brief semaphore destructor
\r
234 *Destructs the semaphore object. This will wait for the semaphore to be released if needed.
\r
236 void gf_sema_del(GF_Semaphore *sm);
\r
238 *\brief semaphore notifivation
\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
245 u32 gf_sema_notify(GF_Semaphore *sm, u32 nb_rel);
\r
247 *\brief semaphore wait
\r
249 *Waits for the semaphore to be accessible (eg, may wait an infinite time).
\r
250 *\param sm the semaphore object
\r
252 void gf_sema_wait(GF_Semaphore *sm);
\r
254 *\brief semaphore time wait
\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
261 Bool gf_sema_wait_for(GF_Semaphore *sm, u32 time_out);
\r
270 #endif /*_GF_THREAD_H_*/
\r