threading
[utils]

Threading and Mutual Exclusion Functions. More...

Typedefs
typedef __tag_thread	GF_Thread
	abstracted thread object
typedef u32(*)	gf_thread_run (void *par)
	thread run function callback
typedef __tag_mutex	GF_Mutex
	abstracted mutex object
typedef __tag_semaphore	GF_Semaphore
	abstracted semaphore object
Enumerations
enum	{ GF_THREAD_STATUS_STOP = 0, GF_THREAD_STATUS_RUN = 1, GF_THREAD_STATUS_DEAD = 2 }
	Thread states. More...
enum	{   GF_THREAD_PRIORITY_IDLE = 0, GF_THREAD_PRIORITY_LESS_IDLE, GF_THREAD_PRIORITY_LOWEST, GF_THREAD_PRIORITY_LOW,   GF_THREAD_PRIORITY_NORMAL, GF_THREAD_PRIORITY_HIGH, GF_THREAD_PRIORITY_HIGHEST, GF_THREAD_PRIORITY_REALTIME,   GF_THREAD_PRIORITY_REALTIME_END = 255 }
Functions
GF_Thread *	gf_th_new (const char *name)
	thread constructor
void	gf_th_del (GF_Thread *th)
	thread destructor
GF_Err	gf_th_run (GF_Thread *th, gf_thread_run run, void *par)
	thread execution
void	gf_th_stop (GF_Thread *th)
	thread stoping
u32	gf_th_status (GF_Thread *th)
	thread status query
void	gf_th_set_priority (GF_Thread *th, s32 priority)
	thread priority
u32	gf_th_id ()
	current thread ID
GF_Mutex *	gf_mx_new (const char *name)
void	gf_mx_del (GF_Mutex *mx)
u32	gf_mx_p (GF_Mutex *mx)
void	gf_mx_v (GF_Mutex *mx)
Bool	gf_mx_try_lock (GF_Mutex *mx)
GF_Semaphore *	gf_sema_new (u32 MaxCount, u32 InitCount)
void	gf_sema_del (GF_Semaphore *sm)
u32	gf_sema_notify (GF_Semaphore *sm, u32 nb_rel)
void	gf_sema_wait (GF_Semaphore *sm)
Bool	gf_sema_wait_for (GF_Semaphore *sm, u32 time_out)

---

Detailed Description

This section documents the threading of the GPAC framework. These provide an easy way to implement safe multithreaded tools.

---

Typedef Documentation

typedef struct __tag_thread GF_Thread

The abstracted thread object allows you to execute some code independently of the main process of your application.

typedef u32(*) gf_thread_run(void *par)

The gf_thread_run type is the type for the callback of the gf_thread_run function

Parameters:

par

opaque user data

Returns:

exit code of the thread, usually 1 for error and 0 if normal execution

typedef struct __tag_mutex GF_Mutex

The abstracted mutex object allows you to make sure that portions of the code (typically access to variables) cannot be executed by two threads (or a thread and the main process) at the same time.

typedef struct __tag_semaphore GF_Semaphore

The abstracted semaphore object allows you to control how portions of the code (typically access to variables) are executed by two threads (or a thread and the main process) at the same time. The best image for a semaphore is a limited set of money coins (always easy to understand hmm?). If no money is in the set, nobody can buy anything until a coin is put back in the set. When the set is full, the money is wasted (call it "the bank"...).

---

Enumeration Type Documentation

anonymous enum

Inidcates the execution status of a thread

Enumerator:

GF_THREAD_STATUS_STOP	the thread has been initialized but is not started yet
GF_THREAD_STATUS_RUN	the thread is running
GF_THREAD_STATUS_DEAD	the thread has exited its body function

anonymous enum

thread priorities

Enumerator:

GF_THREAD_PRIORITY_IDLE	Idle Priority
GF_THREAD_PRIORITY_LESS_IDLE	Less Idle Priority
GF_THREAD_PRIORITY_LOWEST	Lowest Priority
GF_THREAD_PRIORITY_LOW	Low Priority
GF_THREAD_PRIORITY_NORMAL	Normal Priority (the default one)
GF_THREAD_PRIORITY_HIGH	High Priority
GF_THREAD_PRIORITY_HIGHEST	Highest Priority
GF_THREAD_PRIORITY_REALTIME	First real-time priority
GF_THREAD_PRIORITY_REALTIME_END	Last real-time priority

---

Function Documentation

GF_Thread* gf_th_new

(

const char *

name

)

Constructs a new thread object

Parameters:

log

name of the thread if any

void gf_th_del

(

GF_Thread *

th

)

Kills the thread if running and destroys the object

Parameters:

th

the thread object

GF_Err gf_th_run	(	GF_Thread *	th,
		gf_thread_run	run,
		void *	par
	)

Executes the thread with the given function

Parameters:

	th	the thread object
	run	the function this thread will call
	par	the argument to the function the thread will call

Note:

A thread may be run several times but cannot be run twice in the same time.

void gf_th_stop

(

GF_Thread *

th

)

Waits for the thread exit until return

Parameters:

th

the thread object

u32 gf_th_status

(

GF_Thread *

th

)

Gets the thread status

Parameters:

th

the thread object

void gf_th_set_priority	(	GF_Thread *	th,
		s32	priority
	)

Sets the thread execution priority level.

Parameters:

	th	the thread object
	priority	the desired priority

Note:

this should be used with caution, especially use of real-time priorities.

u32 gf_th_id

(

)

Gets the ID of the current thread the caller is in.

---