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:

wait for a message from the queue(s) plus wait for some application-dependent event (such as a flag to finish the task, or whatever);
wait for messages from multiple queues.

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) :

create event group EG;
connect EG with flag 1 to Q1;
connect EG with flag 2 to Q2;
when task needs to receive a message from either Q1 or Q2, it just waits for the any of flags 1 or 2 in the EG, this is done in the single call to tn_eventgrp_wait().
when that event happened, task checks which flag is set, and receive message from the appropriate queue.

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

enum 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

enum 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

eventgrp	Pointer to already allocated struct TN_EventGrp
attr	Attributes for that particular event group object, see `struct TN_EGrpAttr`
initial_pattern	Initial 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.

(refer to Legend for details)

Parameters

eventgrp	Pointer to already allocated struct TN_EventGrp
initial_pattern	Initial events pattern.

Returns

TN_RC_OK if event group was successfully created;
If TN_CHECK_PARAM is non-zero, additional return code is available: TN_RC_WPARAM.

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.

(refer to Legend for details)

Parameters

eventgrp Pointer to event groupt to be deleted.

Returns

TN_RC_OK if event group was successfully deleted;
TN_RC_WCONTEXT if called from wrong context;
If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

◆ 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.

(refer to Legend for details)

Parameters

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_TickCnt`

Returns

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;
Other possible return codes depend on timeout value, refer to TN_TickCnt
If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

◆ 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.

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

(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

(refer to Legend for details)

Parameters

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)

Returns

TN_RC_OK on success;
TN_RC_WCONTEXT if called from wrong context;
If TN_CHECK_PARAM is non-zero, additional return codes are available: TN_RC_WPARAM and TN_RC_INVALID_OBJ.

◆ 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.

(refer to Legend for details)

Detailed Description

Connecting an event group to other system objects

Data Structures

Enumerations

Functions

Enumeration Type Documentation

◆ TN_EGrpWaitMode

◆ TN_EGrpOp

◆ TN_EGrpAttr

Function Documentation

◆ tn_eventgrp_create_wattr()

◆ tn_eventgrp_create()

◆ tn_eventgrp_delete()

◆ tn_eventgrp_wait()

◆ tn_eventgrp_wait_polling()

◆ tn_eventgrp_iwait_polling()

◆ tn_eventgrp_modify()

◆ tn_eventgrp_imodify()