Thread's synchronization
[Task]

---

Detailed Description

A task, in the PEAK's context, might process events in parallel, with the help of kernel threads (pthread(3)).

The PEAK library provides a set of functions for kernel threads synchronization within a task. If the task has only one thread to process events, these functions do nothing. Otherwise, they are prefered to more low level primitives as some optimizations can be done within a task. Be careful if you need to synchronize with other threads which are not related to a PEAK's task (eg. another thread in your program created explicitely): in that case you need more general primitives.

When in doubt, for example if you are not very familiar with threads synchronization primitives like mutex, conditions or semaphores, you have always the choice to configure your PEAK's task to not use more than one thread (see peak_task_set_info()) Then, all the problems are over because events aren't processed in parallel anymore and you have only one excecution stream. For most applications, that will do... several events libraries act this way and are already very efficient. But, although you don't block when processing events (and you must not!), if your event's processings are still consuming significative CPU time (eg. cache search for each event, huge I/O's, etc), PEAK task capabilities of processing multiple events in the same time has shown global improvement for the application.

Note: Synchronization between several PEAK's tasks are not yet available, as you can only have one task in the current version of the library.

Typedefs
typedef __peak_task_lock *	peak_task_lock
	Opaque task lock type.
typedef __peak_task_mutex *	peak_task_mutex
	Opaque task mutex type.
Functions
void	peak_task_exclusivity (void)
	Acquire task execution exclusivity.
peak_task_lock	peak_task_lock_create (peak_task task)
	Create a task's lock.
void	peak_task_lock_acquire (peak_task_lock lock)
	Acquire a task's lock.
int	peak_task_lock_try (peak_task_lock lock)
	Try to acquire a task's lock.
void	peak_task_lock_release (peak_task_lock lock)
	Release a task's lock.
void	peak_task_lock_handoff (peak_task_lock lock)
	Hand-off a task's lock.
peak_task_mutex	peak_task_mutex_create (peak_task task)
	Create a task's mutex.
void	peak_task_mutex_lock (peak_task_mutex mutex)
	Lock a task's mutex.
void	peak_task_mutex_trylock (peak_task_mutex mutex)
	Try to lock a task's mutex.
void	peak_task_mutex_unlock (peak_task_mutex mutex)
	Unlock a task's mutex.

---

Function Documentation

void peak_task_exclusivity (  void   )

Acquire task execution exclusivity. This function acquires temporary exclusive task execution among all task's threads. It's usually called at the beginning of an event-callback to avoid conflicts with other events (as they might be processed in parallel), when you deal with a lot of shared data in the callback. This function does nothing if the task has only one running thread, and slow down event processing otherwise. Exclusive execution is garanteed in the whole callback, in fact, it's garanteed until the next event or timer on the current task. Note there is no parameter at all: you can only acquire exclusive execution on the current task.

void peak_task_lock_acquire (  peak_task_lock  lock  )

Acquire a task's lock. This function acquires a task's lock. If the lock is already owned by another thread of the task, then the calling thread will block. However, this function does nothing if the task has only one thread. If a deadlock is detected, the program will abort, so be careful with recursions! Possibly, use peak_task_lock_try(). Note that you can only acquire a lock for the current task.

peak_task_lock peak_task_lock_create (  peak_task  task  )

Create a task's lock. Allow you to lock threads in order to create critical regions, for example, within a task, with peak_task_lock_acquire(), peak_task_lock_release(), etc. Like other PEAK's objets, you can destroy a lock with peak_release(). THEY ARE ACTIVE LOCKS FOR SMALL DATA STRUCTURES PROTECTION ONLY. If you think you will have almost no collision for a critical region, they are for you. Parameters: task  The task to associated with the lock (usually peak_task_self()). Returns: A new peak_task_lock reference.

void peak_task_lock_handoff (  peak_task_lock  lock  )

Hand-off a task's lock. To assume the lock's ownership, this function passes a task's lock from the calling thread to another thread of the task. The lock must be already owned by the calling thread. If no other thread is waiting for acquiring the lock, this call will block until it happens. If the task has only one running thread, this function will abort the program (because if you use this function, you want a special synchronization behaviour that can't happen with one thread only). See peak_task_set_info() to properly configure your task. Note that you can only hand-off a lock for the current task.

void peak_task_lock_release (  peak_task_lock  lock  )

Release a task's lock. This function releases a task's lock, so one another thread of the task can acquire it. However, this function does nothing if the task has only one thread. Note that you can only release a lock for the current task.

int peak_task_lock_try (  peak_task_lock  lock  )

Try to acquire a task's lock. This function attempts to acquire a task's lock without blocking. The return value indicatees whether the lock was acquired. This function does nothing if the task has only one running thread and in that case always succeeds. Note that you can only try a lock for the current task. Return values: 1  if the lock was acquired 0  if the lock is already owned (busy)

peak_task_mutex peak_task_mutex_create (  peak_task  task  )

Create a task's mutex. Allow you to create critical regions within a task, with peak_task_mutex_lock(), peak_task_mutex_unlock(), etc. Like other PEAK's objets, you can destroy a mutex with peak_release(). Task's mutex are more suitable to create large mutual exclusion regions than task's locks are, as they shouldn't spinlock much. However, if you need to protect basic and small data structures, it might be lighter to use task's locks (eg. for a simple operation like "object->i++;" ). Parameters: task  The task to associated with the mutex (usually peak_task_self()). Returns: A new peak_task_mutex reference.

void peak_task_mutex_lock (  peak_task_mutex  mutex  )

Lock a task's mutex. This function locks a task's mutex. If the mutex is already locked then the calling thread will block until the mutex becomes available. However, this function does nothing if the task has only one thread. If a deadlock is detected, the program will abort. Possibly, use peak_task_mutex_trylock(). Note that you can only lock a mutex for the current task.

void peak_task_mutex_trylock (  peak_task_mutex  mutex  )

Try to lock a task's mutex. This function locks a task's mutex. If the mutex is already locked then the calling thread will block until the mutex becomes available. However, this function does nothing if the task has only one thread. Note that you can only lock a mutex for the current task.

void peak_task_mutex_unlock (  peak_task_mutex  mutex  )

Unlock a task's mutex. This function unlocks a task's mutex. However, this function does nothing if the task has only one thread. Note that you can only unlock a mutex for the current task.

---