Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages | Examples

Event Management
[Nut/OS API]

Collaboration diagram for Event Management:


Detailed Description

Thread synchronization support.

Threads may wait for events from other threads or interrupts or may post or broadcast events to other threads.

Waiting threads line up in priority ordered queues, so more than one thread may wait for the same event. A waiting queue is a simple linked list of waiting threads.

Events are posted to a waiting queue, moving the thread from waiting (sleeping) state to ready-to-run state. A running thread may also broadcast an event to a specified queue, waking up all threads on that queue.

Usually a woken up thread takes over the CPU, if it's priority is equal or higher than the currently running thread. However, events can be posted asynchronously, in which case the posting thread continues to run.

Interrupt can also post events, but have to use the specific function NutEventPostFromIrq().


Functions

*void NutEventTimeout (HANDLE timer, void *arg)
 Timer callback in case of event timeout.
int NutEventWait (volatile HANDLE *qhp, u_long ms)
 Wait for an event in a specified queue.
int NutEventWaitNext (volatile HANDLE *qhp, u_long ms)
 Wait for a new event in a specified queue.
int NutEventPostAsync (HANDLE volatile *qhp)
 Asynchronously post an event to a specified queue.
int NutEventPostFromIrq (HANDLE volatile *qhp)
 Asynchronously post an event to a specified queue from IRQ.
int NutEventPost (HANDLE *qhp)
 Post an event to a specified queue.
int NutEventBroadcastAsync (HANDLE *qhp)
 Asynchronously broadcast an event to a specified queue.
int NutEventBroadcast (HANDLE *qhp)
 Broadcast an event to a specified queue.


Function Documentation

int NutEventBroadcast HANDLE qhp  ) 
 

Broadcast an event to a specified queue.

Wake up all threads waiting on this queue. If the priority of any waiting thread is higher or equal than the current thread's priority, then the current thread is stopped and CPU control is passed to the woken up thread with the highest priority.

In opposite to NutEventPost(), the queue will be cleared in any case, even if it is in signaled state. Applications may use this call to make sure, that a queue is cleared before initiating some event triggering action.

Parameters:
qhp Identifies the queue an event is broadcasted to.
Returns:
The number of threads woken up.

int NutEventBroadcastAsync HANDLE qhp  ) 
 

Asynchronously broadcast an event to a specified queue.

Wake up all threads waiting on this queue. But even if the priority of any woken thread is higher than the current thread's priority, the current one continues running.

In opposite to NutEventPostAsync(), the queue will be cleared in any case, even if it is in signaled state. Applications may use this call to make sure, that a queue is cleared before initiating some event triggering action.

Note:
It is save to call this function from within an interrupt handler.
Parameters:
qhp Identifies the queue an event is broadcasted to.
Returns:
The number of threads woken up.

int NutEventPost HANDLE qhp  ) 
 

Post an event to a specified queue.

Wake up the thread with the highest priority waiting on this queue. If the priority of the waiting thread is higher or equal than the current thread's priority, then the current thread is stopped and CPU control is passed to the waiting thread.

If no thread is waiting, the queue will be set to the signaled state.

Parameters:
qhp Identifies the queue an event is posted to.
Returns:
The number of threads woken up, either 0 or 1.

int NutEventPostAsync HANDLE volatile *  qhp  ) 
 

Asynchronously post an event to a specified queue.

Wake up the thread with the highest priority waiting on the specified queue. But even if the priority of the woken thread is higher than the current thread's priority, the current one continues running.

If no thread is waiting, then the queue will be set to the signaled state.

Parameters:
qhp Identifies the queue an event is posted to.
Returns:
The number of threads woken up, either 0 or 1.

int NutEventPostFromIrq HANDLE volatile *  qhp  ) 
 

Asynchronously post an event to a specified queue from IRQ.

Wake up the thread with the highest priority waiting on the specified queue. This function is explicitly provided for IRQ handlers to wakeup waiting user threads

Note:
It is save to call this function from within an interrupt handler.
Parameters:
qhp Identifies the queue an event is posted to.
Returns:
The number of threads woken up, either 0 or 1.

* void NutEventTimeout HANDLE  timer,
void *  arg
 

Timer callback in case of event timeout.

Parameters:
timer Handle of the elapsed timeout timer.
arg Handle of an event queue.

int NutEventWait volatile HANDLE qhp,
u_long  ms
 

Wait for an event in a specified queue.

Give up the CPU until another thread posts an event to this queue or until a time-out occurs, whichever comes first.

If previously an event had been posted to this queue without any thread waiting, then the thread will not wait for a new event, but may still pass CPU control, if another thread with equal or higher priority is ready to run.

Parameters:
qhp Identifies the queue to wait on.
ms Maximum wait time in milliseconds. To disable timeout, set this parameter to NUT_WAIT_INFINITE.
Returns:
0 if event received, -1 on timeout.
Note:
Timeout is limited to the granularity of the system timer.

int NutEventWaitNext volatile HANDLE qhp,
u_long  ms
 

Wait for a new event in a specified queue.

Give up the CPU until another thread posts an event to this queue or until a time-out occurs, whichever comes first.

This call is similar to NutEventWait(), but will ignore the signaled state of the queue. This way, previously posted events to an empty queue are not considered.

Parameters:
qhp Identifies the queue to wait on.
ms Maximum wait time in milliseconds.
Returns:
0 if event received, -1 on timeout.
Note:
Timeout is limited to the granularity of the system timer.


© 2000-2006 by egnite Software GmbH - visit http://www.ethernut.de/