TNeo  BETA v1.08-11-g97e5a6d
Data Structures | Enumerations | Functions
tn_eventgrp.h File Reference

Detailed Description

Event group.

An event group has an internal variable (of type TN_UWord), which is interpreted as a bit pattern where each bit represents an event. An event group also has a wait queue for the tasks waiting on these events. A task may set specified bits when an event occurs and may clear specified bits when necessary.

The tasks waiting for an event(s) are placed in the event group's wait queue. An event group is a very suitable synchronization object for cases where (for some reasons) one task has to wait for many tasks, or vice versa, many tasks have to wait for one task.

Connecting an event group to other system objects

Sometimes task needs to wait for different system events, the most common examples are:

If the kernel doesn't offer a mechanism for that, programmer usually have to use polling services on these queues and sleep for a few system ticks. Obviously, this approach has serious drawbacks: we have a lot of useless context switches, and response for the message gets much slower. Actually, we lost the main goal of the preemptive kernel when we use polling services like that.

TNeo offers a solution: an event group can be connected to other kernel objects, and these objects will maintain certain flags inside that event group automatically.

So, in case of multiple queues, we can act as follows (assume we have two queues: Q1 and Q2) :

Please note that task waiting for the event should not clear the flag manually: this flag is maintained completely by the queue. If the queue is non-empty, the flag is set. If the queue becomes empty, the flag is cleared.

For the information on system services related to queue, refer to the queue reference.

There is an example project available that demonstrates event group connection technique: examples/queue_eventgrp_conn. Be sure to examine the readme there.

Definition in file tn_eventgrp.h.

Go to the source code of this file.

Data Structures

struct  TN_EventGrp
 Event group. More...
 
struct  TN_EGrpTaskWait
 EventGrp-specific fields related to waiting task, to be included in struct TN_Task. More...
 
struct  TN_EGrpLink
 A link to event group: used when event group can be connected to some kernel object, such as queue. More...
 

Enumerations

enum  TN_EGrpWaitMode { TN_EVENTGRP_WMODE_OR = (1 << 0), TN_EVENTGRP_WMODE_AND = (1 << 1), TN_EVENTGRP_WMODE_AUTOCLR = (1 << 2) }
 Events waiting mode that should be given to tn_eventgrp_wait() and friends. More...
 
enum  TN_EGrpOp { TN_EVENTGRP_OP_SET, TN_EVENTGRP_OP_CLEAR, TN_EVENTGRP_OP_TOGGLE }
 Modify operation: set, clear or toggle. More...
 
enum  TN_EGrpAttr { TN_EVENTGRP_ATTR_SINGLE = (1 << 0), TN_EVENTGRP_ATTR_MULTI = (1 << 1), TN_EVENTGRP_ATTR_CLR = (1 << 2), TN_EVENTGRP_ATTR_NONE = (0) }
 Attributes that could be given to the event group object. More...
 

Functions

enum TN_RCode tn_eventgrp_create_wattr (struct TN_EventGrp *eventgrp, enum TN_EGrpAttr attr, TN_UWord initial_pattern)
 The same as tn_eventgrp_create(), but takes additional argument: attr. More...
 
_TN_STATIC_INLINE enum TN_RCode tn_eventgrp_create (struct TN_EventGrp *eventgrp, TN_UWord initial_pattern)
 Construct event group. More...
 
enum TN_RCode tn_eventgrp_delete (struct TN_EventGrp *eventgrp)
 Destruct event group. More...
 
enum TN_RCode tn_eventgrp_wait (struct TN_EventGrp *eventgrp, TN_UWord wait_pattern, enum TN_EGrpWaitMode wait_mode, TN_UWord *p_flags_pattern, TN_TickCnt timeout)
 Wait for specified event(s) in the event group. More...
 
enum TN_RCode tn_eventgrp_wait_polling (struct TN_EventGrp *eventgrp, TN_UWord wait_pattern, enum TN_EGrpWaitMode wait_mode, TN_UWord *p_flags_pattern)
 The same as tn_eventgrp_wait() with zero timeout. More...
 
enum TN_RCode tn_eventgrp_iwait_polling (struct TN_EventGrp *eventgrp, TN_UWord wait_pattern, enum TN_EGrpWaitMode wait_mode, TN_UWord *p_flags_pattern)
 The same as tn_eventgrp_wait() with zero timeout, but for using in the ISR. More...
 
enum TN_RCode tn_eventgrp_modify (struct TN_EventGrp *eventgrp, enum TN_EGrpOp operation, TN_UWord pattern)
 Modify current events bit pattern in the event group. More...
 
enum TN_RCode tn_eventgrp_imodify (struct TN_EventGrp *eventgrp, enum TN_EGrpOp operation, TN_UWord pattern)
 The same as tn_eventgrp_modify(), but for using in the ISR. More...
 

Enumeration Type Documentation

◆ TN_EGrpWaitMode

Events waiting mode that should be given to tn_eventgrp_wait() and friends.

Enumerator
TN_EVENTGRP_WMODE_OR 

Task waits for any of the event bits from the wait_pattern to be set in the event group.

This flag is mutually exclusive with TN_EVENTGRP_WMODE_AND.

TN_EVENTGRP_WMODE_AND 

Task waits for all of the event bits from the wait_pattern to be set in the event group.

This flag is mutually exclusive with TN_EVENTGRP_WMODE_OR.

TN_EVENTGRP_WMODE_AUTOCLR 

When a task successfully ends waiting for event bit(s), these bits get cleared atomically and automatically.

Other bits stay unchanged.

Definition at line 124 of file tn_eventgrp.h.

◆ TN_EGrpOp

enum TN_EGrpOp

Modify operation: set, clear or toggle.

To be used in tn_eventgrp_modify() / tn_eventgrp_imodify() functions.

Enumerator
TN_EVENTGRP_OP_SET 

Set flags that are set in given pattern argument.

Note that this operation can lead to the context switch, since other high-priority task(s) might wait for the event.

TN_EVENTGRP_OP_CLEAR 

Clear flags that are set in the given pattern argument.

This operation can not lead to the context switch, since tasks can't wait for events to be cleared.

TN_EVENTGRP_OP_TOGGLE 

Toggle flags that are set in the given pattern argument.

Note that this operation can lead to the context switch, since other high-priority task(s) might wait for the event that was just set (if any).

Definition at line 146 of file tn_eventgrp.h.

◆ TN_EGrpAttr

Attributes that could be given to the event group object.

Makes sense if only TN_OLD_EVENT_API option is non-zero; otherwise, there's just one dummy attribute available: TN_EVENTGRP_ATTR_NONE.

Enumerator
TN_EVENTGRP_ATTR_SINGLE 
Attention
deprecated. Available if only TN_OLD_EVENT_API option is non-zero.

Indicates that only one task could wait for events in this event group. This flag is mutually exclusive with TN_EVENTGRP_ATTR_MULTI flag.

TN_EVENTGRP_ATTR_MULTI 
Attention
deprecated. Available if only TN_OLD_EVENT_API option is non-zero.

Indicates that multiple tasks could wait for events in this event group. This flag is mutually exclusive with TN_EVENTGRP_ATTR_SINGLE flag.

TN_EVENTGRP_ATTR_CLR 
Attention
strongly deprecated. Available if only TN_OLD_EVENT_API option is non-zero. Use TN_EVENTGRP_WMODE_AUTOCLR instead.

Can be specified only in conjunction with TN_EVENTGRP_ATTR_SINGLE flag. Indicates that ALL flags in this event group should be cleared when task successfully waits for any event in it.

This actually makes little sense to clear ALL events, but this is what compatibility mode is for (see TN_OLD_EVENT_API)

TN_EVENTGRP_ATTR_NONE 

Dummy attribute that does not change anything.

It is needed only for the assistance of the events compatibility mode (see TN_OLD_EVENT_API)

Definition at line 171 of file tn_eventgrp.h.

Function Documentation

◆ tn_eventgrp_create_wattr()

enum TN_RCode tn_eventgrp_create_wattr ( struct TN_EventGrp eventgrp,
enum TN_EGrpAttr  attr,
TN_UWord  initial_pattern 
)

The same as tn_eventgrp_create(), but takes additional argument: attr.

It makes sense if only TN_OLD_EVENT_API option is non-zero.

Parameters
eventgrpPointer to already allocated struct TN_EventGrp
attrAttributes for that particular event group object, see struct TN_EGrpAttr
initial_patternInitial events pattern.

◆ tn_eventgrp_create()

_TN_STATIC_INLINE enum TN_RCode tn_eventgrp_create ( struct TN_EventGrp eventgrp,
TN_UWord  initial_pattern 
)

Construct event group.

id_event field should not contain TN_ID_EVENTGRP, otherwise, TN_RC_WPARAM is returned.

attr_call_task.png
attr_call_int.png
(refer to Legend for details)

Parameters
eventgrpPointer to already allocated struct TN_EventGrp
initial_patternInitial events pattern.
Returns

Definition at line 314 of file tn_eventgrp.h.

◆ tn_eventgrp_delete()

enum TN_RCode tn_eventgrp_delete ( struct TN_EventGrp eventgrp)

Destruct event group.

All tasks that wait for the event(s) become runnable with TN_RC_DELETED code returned.

attr_call_task.png
attr_call_ct_sw.png
(refer to Legend for details)

Parameters
eventgrpPointer to event groupt to be deleted.
Returns

◆ tn_eventgrp_wait()

enum TN_RCode tn_eventgrp_wait ( struct TN_EventGrp eventgrp,
TN_UWord  wait_pattern,
enum TN_EGrpWaitMode  wait_mode,
TN_UWord p_flags_pattern,
TN_TickCnt  timeout 
)

Wait for specified event(s) in the event group.

If the specified event is already active, function returns TN_RC_OK immediately. Otherwise, behavior depends on timeout value: refer to TN_TickCnt.

attr_call_task.png
attr_call_ct_sw.png
attr_timeout.png
(refer to Legend for details)

Parameters
eventgrpPointer to event group to wait events from
wait_patternEvents bit pattern for which task should wait
wait_modeSpecifies whether task should wait for all the event bits from wait_pattern to be set, or for just any of them (see enum TN_EGrpWaitMode)
p_flags_patternPointer to the TN_UWord variable in which actual event pattern that caused task to stop waiting will be stored. May be TN_NULL.
timeoutrefer to TN_TickCnt
Returns

◆ tn_eventgrp_wait_polling()

enum TN_RCode tn_eventgrp_wait_polling ( struct TN_EventGrp eventgrp,
TN_UWord  wait_pattern,
enum TN_EGrpWaitMode  wait_mode,
TN_UWord p_flags_pattern 
)

The same as tn_eventgrp_wait() with zero timeout.

attr_call_task.png
attr_call_ct_sw.png
(refer to Legend for details)

◆ tn_eventgrp_iwait_polling()

enum TN_RCode tn_eventgrp_iwait_polling ( struct TN_EventGrp eventgrp,
TN_UWord  wait_pattern,
enum TN_EGrpWaitMode  wait_mode,
TN_UWord p_flags_pattern 
)

The same as tn_eventgrp_wait() with zero timeout, but for using in the ISR.

attr_call_int.png
attr_call_ct_sw.png
(refer to Legend for details)

◆ tn_eventgrp_modify()

enum TN_RCode tn_eventgrp_modify ( struct TN_EventGrp eventgrp,
enum TN_EGrpOp  operation,
TN_UWord  pattern 
)

Modify current events bit pattern in the event group.

Behavior depends on the given operation: refer to enum TN_EGrpOp

attr_call_task.png
attr_call_ct_sw.png
(refer to Legend for details)

Parameters
eventgrpPointer to event group to modify events in
operationActual operation to perform: set, clear or toggle. Refer to enum TN_EGrpOp
patternEvents pattern to be applied (depending on operation value)
Returns

◆ tn_eventgrp_imodify()

enum TN_RCode tn_eventgrp_imodify ( struct TN_EventGrp eventgrp,
enum TN_EGrpOp  operation,
TN_UWord  pattern 
)

The same as tn_eventgrp_modify(), but for using in the ISR.

attr_call_int.png
attr_call_ct_sw.png
(refer to Legend for details)