TNeoKernel
v1.04
|
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.
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.
TNeoKernel 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) :
tn_eventgrp_wait()
.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) } |
Events waiting mode: wait for all flags to be set or just for any of the specified flags to be set. More... | |
enum | TN_EGrpOp { TN_EVENTGRP_OP_SET, TN_EVENTGRP_OP_CLEAR, TN_EVENTGRP_OP_TOGGLE } |
Modify operation: set, clear or toggle. More... | |
Functions | |
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_Timeout 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... | |
enum TN_EGrpWaitMode |
Events waiting mode: wait for all flags to be set or just for any of the specified flags to be set.
Definition at line 124 of file tn_eventgrp.h.
enum TN_EGrpOp |
Modify operation: set, clear or toggle.
To be used in tn_eventgrp_modify()
/ tn_eventgrp_imodify()
functions.
Definition at line 139 of file tn_eventgrp.h.
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.
eventgrp | Pointer to already allocated struct TN_EventGrp |
initial_pattern | Initial events pattern. |
TN_RC_OK
if event group was successfully created;TN_CHECK_PARAM
is non-zero, additional return code is available: TN_RC_WPARAM
. 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.
eventgrp | Pointer to event groupt to be deleted. |
TN_RC_OK
if event group was successfully deleted;TN_RC_WCONTEXT
if called from wrong context;TN_CHECK_PARAM
is non-zero, additional return codes are available: TN_RC_WPARAM
and TN_RC_INVALID_OBJ
. 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_Timeout | 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_Timeout
.
eventgrp | Pointer to event group to wait events from |
wait_pattern | Events bit pattern for which task should wait |
wait_mode | Specifies 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_pattern | Pointer to the TN_UWord variable in which actual event pattern that caused task to stop waiting will be stored. May be TN_NULL . |
timeout | refer to TN_Timeout |
TN_RC_OK
if specified event is active (so the task can check variable pointed to by p_flags_pattern
if it wasn't TN_NULL
).TN_RC_WCONTEXT
if called from wrong context;timeout
value, refer to TN_Timeout
TN_CHECK_PARAM
is non-zero, additional return codes are available: TN_RC_WPARAM
and TN_RC_INVALID_OBJ
. 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 | ||
) |
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.
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
eventgrp | Pointer to event group to modify events in |
operation | Actual operation to perform: set, clear or toggle. Refer to enum TN_EGrpOp |
pattern | Events pattern to be applied (depending on operation value) |
TN_RC_OK
on success;TN_RC_WCONTEXT
if called from wrong context;TN_CHECK_PARAM
is non-zero, additional return codes are available: TN_RC_WPARAM
and TN_RC_INVALID_OBJ
. enum TN_RCode tn_eventgrp_imodify | ( | struct TN_EventGrp * | eventgrp, |
enum TN_EGrpOp | operation, | ||
TN_UWord | pattern | ||
) |