Nut/OS  4.10.3
API Reference
Event Management

Thread synchronization support. More...

Collaboration diagram for Event Management:

Defines

#define SIGNALED   ((void *)-1)
 Signaled state definition.
#define NUT_WAIT_INFINITE   0
 Infinite waiting time definition.
#define NutEventPostFromIrq(qp)
 Post an event to a specified queue from interrupt context.

Functions

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

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().


Define Documentation

#define SIGNALED   ((void *)-1)

Signaled state definition.

The root of an event queue is set to this value if an event is posted to an empty queue. As this may happen during interrupts, the root of an event queue must be considered volatile.

Timer handles in the THREADINFO structure are set to this value if a timeout occured while waiting for an event.

Definition at line 120 of file event.h.

Referenced by NutDumpThreadList(), NutDumpThreadQueue(), NutEventBroadcastAsync(), NutEventPostAsync(), NutEventTimeout(), NutEventWait(), NutEventWaitNext(), NutSemDestroy(), NutThreadAddPriQueue(), NutThreadRemoveQueue(), NutThreadResume(), TwMasterTransact(), TwSlaveListen(), and TwSlaveRespond().

#define NutEventPostFromIrq (   qp)
Value:
{                                   \
    if (*qp == 0) {                 \
        *qp = SIGNALED;             \
    }                               \
    else if (*qp != SIGNALED) {     \
        NUTTHREADINFO *tp = (NUTTHREADINFO *)(*qp);    \
        tp->td_qpec++;              \
    }                               \
}

Post an event to a specified queue from interrupt context.

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.

Internally a counter is used to keep track of the posted events. This counter will be examined when the currently running thread is ready to release the CPU.

Note:
When calling this function, interrupt routines will change the root of an empty event queue to SIGNALED.
Parameters:
qpIdentifies the queue an event is posted to.

Definition at line 147 of file event.h.

Referenced by At91SpiBus0Interrupt(), Avr32SpiBus0Interrupt(), Avr32SpiBus1Interrupt(), and SIG_INTERRUPT4().


Function Documentation

void NutEventTimeout ( HANDLE  timer,
void *  arg 
)

Timer callback in case of event timeout.

Applications should not call this function. It is provided as a global to enable debugging code inspecting the callbacks in the timer list.

Parameters:
timerHandle of the elapsed timeout timer.
argHandle of an event queue.

Definition at line 196 of file event.c.

References NUTASSERT, NutEnterCritical, NutExitCritical, NutThreadAddPriQueue(), runQueue, SIGNALED, _NUTTHREADINFO::td_qnxt, _NUTTHREADINFO::td_qpec, _NUTTHREADINFO::td_state, _NUTTHREADINFO::td_timer, and TDS_READY.

Referenced by NutDumpTimerList(), and NutEventWait().

Here is the call graph for this function:

int NutEventWait ( volatile HANDLE qhp,
uint32_t  ms 
)

Wait for an event in a specified queue.

Give up the CPU until another thread or an interrupt routine 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:
qhpIdentifies the queue to wait on.
msMaximum 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.

Definition at line 271 of file event.c.

References NUTASSERT, NutEnterCritical, NutEventTimeout(), NutExitCritical, NutThreadAddPriQueue(), NutThreadRemoveQueue(), NutThreadResume(), NutThreadYield(), NutTimerStart(), runningThread, runQueue, SIGNALED, _NUTTHREADINFO::td_state, _NUTTHREADINFO::td_timer, TDS_SLEEP, TM_ONESHOT, TRACE_ADD_ITEM, and TRACE_TAG_THREAD_WAIT.

Referenced by AhdlcAt91Read(), AhdlcAvrRead(), AhdlcRx(), At45dNodeLock(), At91SpiBus0Select(), At91SpiBus0Transfer(), At91SpiTransfer2(), AtCanInput(), AtCanOutput(), Avr32SpiBus0Select(), Avr32SpiBus0Transfer(), Avr32SpiBus1Select(), Avr32SpiBus1Transfer(), Avr32SpiBusWait(), AvrSpiBus0Select(), AvrSpiBus0Transfer(), CAN_Tx(), DmOutput(), EmacOutput(), EmacRxThread(), FATLock(), FeederThread(), GpioSpiBus0Select(), High(), IDELock(), LancOutput(), Low(), main(), MmCardIOCtl(), NicRx(), NicRxAsix(), NicRxLanc(), NplSpiBusSelect(), NutArpCacheQuery(), NutConditionTimedWait(), NutConditionWait(), NutDhcpClient(), NutEventWaitNext(), NutIrGet(), NutMsgQGetMessage(), NutNetIfConfig2(), NutTcpReceive(), NutTcpSend(), NutTcpSm(), NutTcpStateActiveOpenEvent(), NutTcpStatePassiveOpenEvent(), NutUdpReceiveFrom(), PerCiWrite(), PhatSectorLoad(), RxThread(), Sc16is752UsartInterruptProcessing(), SJAInput(), sys_key(), sys_led(), TimerEvent1(), TimerEvent2(), TimerEvent3(), TimerEvent4(), Tlv320DacFlush(), Tlv320DacWrite(), TwMasterRegRead(), TwMasterRegWrite(), TwMasterTransact(), TwSlaveListen(), TwSlaveRespond(), UartAvrFlush(), UartAvrInput(), UsartRead(), VsCodecRead(), VsCodecWaitReady(), and VsCodecWrite().

Here is the call graph for this function:

int NutEventWaitNext ( volatile HANDLE qhp,
uint32_t  ms 
)

Wait for a new event in a specified queue.

Give up the CPU until another thread or an interrupt routine 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:
qhpIdentifies the queue to wait on.
msMaximum 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.

Definition at line 350 of file event.c.

References NUTASSERT, NutEnterCritical, NutEventWait(), NutExitCritical, and SIGNALED.

Referenced by AceFlush(), AceInput(), CFChange(), and NutMutexLock().

Here is the call graph for this function:

int NutEventPostAsync ( volatile HANDLE 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.

Note:
Interrupts must not call this function but use NutEventPostFromIrq() to post events to specific queues.
Parameters:
qhpIdentifies the queue an event is posted to.
Returns:
The number of threads woken up, either 0 or 1.

Definition at line 384 of file event.c.

References NUTASSERT, NutEnterCritical, NutExitCritical, NutThreadAddPriQueue(), NutTimerStop(), runQueue, SIGNALED, _NUTTHREADINFO::td_qnxt, _NUTTHREADINFO::td_qpec, _NUTTHREADINFO::td_state, _NUTTHREADINFO::td_timer, and TDS_READY.

Referenced by AceIOCtl(), KeyTimerCb(), NutEventBroadcastAsync(), NutEventPost(), NutMsgQGetMessage(), NutMsgQPost(), NutThreadResume(), PhatSectorLoad(), SJAOutput(), and TimerCallback().

Here is the call graph for this function:

int NutEventPost ( volatile 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.

Note:
Interrupts must not call this function but use NutEventPostFromIrq() to post events to specific queues.
Parameters:
qhpIdentifies the queue an event is posted to.
Returns:
The number of threads woken up, either 0 or 1.

Definition at line 454 of file event.c.

References NutEventPostAsync(), and NutThreadYield().

Referenced by AhdlcAt91IOCtl(), AhdlcAvrIOCtl(), At45dNodeUnlock(), At91SpiBus0Deselect(), At91SpiBus0Select(), Avr32SpiBus0Deselect(), Avr32SpiBus0Select(), Avr32SpiBus1Deselect(), Avr32SpiBus1Select(), AvrSpiBus0Deselect(), AvrSpiBus0Select(), DmOutput(), EmacOutput(), EmacRxThread(), FATFree(), FATSemaInit(), FeederThread(), GpioSpiBus0Deselect(), GpioSpiBus0Select(), High(), IDEFree(), IDESemaInit(), IpcpClose(), IpcpLowerDown(), IpcpRxConfAck(), IpcpRxConfReq(), LancOutput(), Low(), main(), MmCardIOCtl(), NicRxLanc(), NplSpiBusDeselect(), NplSpiBusSelect(), NutConditionSignal(), NutMutexUnlock(), NutRegisterSpiDevice(), NutSemPost(), NutTcpStateMachine(), NutUdpInput(), NutUdpSetSocketError(), PerCiOpen(), PerCiWrite(), PhatVolMount(), RawFsMount(), sys_key(), TwInit(), TwMasterRegRead(), TwMasterRegWrite(), TwMasterTransact(), UFlashAttach(), UFlashFormat(), VsCodecIOCtl(), VsCodecRead(), VsCodecWrite(), and wlandrv_Attach().

Here is the call graph for this function:

int NutEventBroadcastAsync ( volatile 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.

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

Definition at line 486 of file event.c.

References NUTASSERT, NutEnterCritical, NutEventPostAsync(), NutExitCritical, and SIGNALED.

Referenced by NutEventBroadcast().

Here is the call graph for this function:

int NutEventBroadcast ( volatile 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:
qhpIdentifies the queue an event is broadcasted to.
Returns:
The number of threads woken up.

Definition at line 533 of file event.c.

References NutEventBroadcastAsync(), and NutThreadYield().

Referenced by NutArpCacheUpdate(), NutConditionBroadcast(), NutDhcpClient(), NutNetIfConfig2(), NutTcpAbortSocket(), and UsartClose().

Here is the call graph for this function: