Detailed Description

A data queue is a FIFO that stores pointer (of type void *) in each cell, called (in uITRON style) a data element.

A data queue also has an associated wait queue each for sending (wait_send queue) and for receiving (wait_receive queue). A task that sends a data element tries to put the data element into the FIFO. If there is no space left in the FIFO, the task is switched to the waiting state and placed in the data queue's wait_send queue until space appears (another task gets a data element from the data queue).

A task that receives a data element tries to get a data element from the FIFO. If the FIFO is empty (there is no data in the data queue), the task is switched to the waiting state and placed in the data queue's wait_receive queue until data element arrive (another task puts some data element into the data queue). To use a data queue just for the synchronous message passing, set size of the FIFO to 0. The data element to be sent and received can be interpreted as a pointer or an integer and may have value 0 (TN_NULL).

For the useful pattern on how to use queue together with fixed memory pool, refer to the example: examples/queue. Be sure to examine the readme there.

TNeo offers a way to wait for a message from multiple queues in just a single call, refer to the section Connecting an event group to other system objects for details. Related queue services:

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_dqueue.h.

Go to the source code of this file.

Data Structures
struct	TN_DQueue
	Structure representing data queue object. More...

struct	TN_DQueueTaskWait
	DQueue-specific fields related to waiting task, to be included in struct TN_Task. More...

Functions
enum TN_RCode	tn_queue_create (struct TN_DQueue dque, void *data_fifo, int items_cnt)
	Construct data queue. More...

enum TN_RCode	tn_queue_delete (struct TN_DQueue *dque)
	Destruct data queue. More...

enum TN_RCode	tn_queue_send (struct TN_DQueue dque, void p_data, TN_TickCnt timeout)
	Send the data element specified by the `p_data` to the data queue specified by the `dque`. More...

enum TN_RCode	tn_queue_send_polling (struct TN_DQueue dque, void p_data)
	The same as `tn_queue_send()` with zero timeout. More...

enum TN_RCode	tn_queue_isend_polling (struct TN_DQueue dque, void p_data)
	The same as `tn_queue_send()` with zero timeout, but for using in the ISR. More...

enum TN_RCode	tn_queue_receive (struct TN_DQueue dque, void *pp_data, TN_TickCnt timeout)
	Receive the data element from the data queue specified by the `dque` and place it into the address specified by the `pp_data`. More...

enum TN_RCode	tn_queue_receive_polling (struct TN_DQueue dque, void *pp_data)
	The same as `tn_queue_receive()` with zero timeout. More...

enum TN_RCode	tn_queue_ireceive_polling (struct TN_DQueue dque, void *pp_data)
	The same as `tn_queue_receive()` with zero timeout, but for using in the ISR. More...

int	tn_queue_free_items_cnt_get (struct TN_DQueue *dque)
	Returns number of free items in the queue. More...

int	tn_queue_used_items_cnt_get (struct TN_DQueue *dque)
	Returns number of used (non-free) items in the queue. More...

enum TN_RCode	tn_queue_eventgrp_connect (struct TN_DQueue dque, struct TN_EventGrp eventgrp, TN_UWord pattern)
	Connect an event group to the queue. More...

enum TN_RCode	tn_queue_eventgrp_disconnect (struct TN_DQueue *dque)
	Disconnect a connected event group from the queue. More...

Function Documentation

◆ tn_queue_create()

enum TN_RCode tn_queue_create	(	struct TN_DQueue *	dque,
		void **	data_fifo,
		int	items_cnt
	)

Construct data queue.

id_dque member should not contain TN_ID_DATAQUEUE, otherwise, TN_RC_WPARAM is returned.

(refer to Legend for details)

Parameters

dque	pointer to already allocated struct TN_DQueue.
data_fifo	pointer to already allocated array of `void *` to store data queue items. Can be `TN_NULL`.
items_cnt	capacity of queue (count of elements in the `data_fifo` array) Can be 0.

Returns

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

◆ tn_queue_delete()

enum TN_RCode tn_queue_delete ( struct TN_DQueue * dque )

Destruct data queue.

All tasks that wait for writing to or reading from the queue become runnable with TN_RC_DELETED code returned.

(refer to Legend for details)

Parameters

dque	pointer to data queue to be deleted

Returns

TN_RC_OK if queue 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_queue_send()

enum TN_RCode tn_queue_send	(	struct TN_DQueue *	dque,
		void *	p_data,
		TN_TickCnt	timeout
	)

Send the data element specified by the p_data to the data queue specified by the dque.

If there are tasks in the data queue's wait_receive list already, the function releases the task from the head of the wait_receive list, makes this task runnable and transfers the parameter p_data to task's function, that caused it to wait.

If there are no tasks in the data queue's wait_receive list, parameter p_data is placed to the tail of data FIFO. If the data FIFO is full, behavior depends on the timeout value: refer to TN_TickCnt.

(refer to Legend for details)

Parameters

dque	pointer to data queue to send data to
p_data	value to send
timeout	refer to `TN_TickCnt`

Returns

TN_RC_OK if data was successfully sent;
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.

See also: TN_TickCnt

◆ tn_queue_send_polling()

enum TN_RCode tn_queue_send_polling	(	struct TN_DQueue *	dque,
		void *	p_data
	)

The same as tn_queue_send() with zero timeout.

(refer to Legend for details)

◆ tn_queue_isend_polling()

enum TN_RCode tn_queue_isend_polling	(	struct TN_DQueue *	dque,
		void *	p_data
	)

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

(refer to Legend for details)

◆ tn_queue_receive()

enum TN_RCode tn_queue_receive	(	struct TN_DQueue *	dque,
		void **	pp_data,
		TN_TickCnt	timeout
	)

Receive the data element from the data queue specified by the dque and place it into the address specified by the pp_data.

If the FIFO already has data, function removes an entry from the end of the data queue FIFO and returns it into the pp_data function parameter.

If there are task(s) in the data queue's wait_send list, first one gets removed from the head of wait_send list, becomes runnable and puts the data entry, stored in this task, to the tail of data FIFO. If there are no entries in the data FIFO and there are no tasks in the wait_send list, behavior depends on the timeout value: refer to TN_TickCnt.

(refer to Legend for details)

Parameters

dque	pointer to data queue to receive data from
pp_data	pointer to location to store the value
timeout	refer to `TN_TickCnt`

Returns

TN_RC_OK if data was successfully received;
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.

See also: TN_TickCnt

◆ tn_queue_receive_polling()

enum TN_RCode tn_queue_receive_polling	(	struct TN_DQueue *	dque,
		void **	pp_data
	)

The same as tn_queue_receive() with zero timeout.

(refer to Legend for details)

◆ tn_queue_ireceive_polling()

enum TN_RCode tn_queue_ireceive_polling	(	struct TN_DQueue *	dque,
		void **	pp_data
	)

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

(refer to Legend for details)

◆ tn_queue_free_items_cnt_get()

int tn_queue_free_items_cnt_get ( struct TN_DQueue * dque )

Returns number of free items in the queue.

(refer to Legend for details)

Parameters

dque	Pointer to queue.

Returns: Number of free items in the queue, or -1 if wrong params were given (the check is performed if only TN_CHECK_PARAM is non-zero)

◆ tn_queue_used_items_cnt_get()

int tn_queue_used_items_cnt_get ( struct TN_DQueue * dque )

Returns number of used (non-free) items in the queue.

(refer to Legend for details)

Parameters

dque	Pointer to queue.

Returns: Number of used (non-free) items in the queue, or -1 if wrong params were given (the check is performed if only TN_CHECK_PARAM is non-zero)

◆ tn_queue_eventgrp_connect()

enum TN_RCode tn_queue_eventgrp_connect	(	struct TN_DQueue *	dque,
		struct TN_EventGrp *	eventgrp,
		TN_UWord	pattern
	)

Connect an event group to the queue.

Refer to the section Connecting an event group to other system objects for details.

Only one event group can be connected to the queue at a time. If you connect event group while another event group is already connected, the old link is discarded.

Parameters

dque	queue to which event group should be connected
eventgrp	event groupt to connect
pattern	flags pattern that should be managed by the queue automatically

(refer to Legend for details)

◆ tn_queue_eventgrp_disconnect()

enum TN_RCode tn_queue_eventgrp_disconnect ( struct TN_DQueue * dque )

Disconnect a connected event group from the queue.

Refer to the section Connecting an event group to other system objects for details.

If there is no event group connected, nothing is changed.

Parameters

dque	queue from which event group should be disconnected

(refer to Legend for details)

Detailed Description

Data Structures

Functions

Function Documentation

◆ tn_queue_create()

◆ tn_queue_delete()

◆ tn_queue_send()

◆ tn_queue_send_polling()

◆ tn_queue_isend_polling()

◆ tn_queue_receive()

◆ tn_queue_receive_polling()

◆ tn_queue_ireceive_polling()

◆ tn_queue_free_items_cnt_get()

◆ tn_queue_used_items_cnt_get()

◆ tn_queue_eventgrp_connect()

◆ tn_queue_eventgrp_disconnect()