Implements a queue to transmit text from one RTOS task to another. More...

#include <textqueue.h>

Inheritance diagram for TextQueue:

[legend]

Collaboration diagram for TextQueue:

[legend]

Public Member Functions
	TextQueue (BaseType_t queue_size, const char *p_name=NULL, TickType_t wait_time=portMAX_DELAY)
	Construct a queue object, allocating memory for the buffer. More...

virtual size_t	write (uint8_t a_char)
	Write a character into the queue in the `Print` style. More...

Public Member Functions inherited from Queue< char >
	Queue (BaseType_t queue_size, const char *p_name=NULL, TickType_t=portMAX_DELAY)
	Construct a queue object, allocating memory for the buffer. More...

bool	put (const char item)
	Put an item into the queue behind other items. More...

bool	ISR_put (const char item)
	Put an item into the queue from within an ISR. More...

bool	butt_in (const char item)
	Put an item into the front of the queue to be retrieved first. More...

bool	ISR_butt_in (const char item)
	Put an item into the front of the queue from within an ISR. More...

bool	is_empty (void)
	Return true if the queue is empty. More...

bool	ISR_is_empty (void)
	Return true if the queue is empty, from within an ISR. More...

void	get (char &recv_item)
	Retrieve and remove the item at the head of the queue. More...

char	get (void)
	Retrieve, remove, and return the item at the head of the queue. More...

void	ISR_get (char &recv_item)
	Remove the item at the head of the queue from within an ISR. More...

char	ISR_get (void)
	Retrieve, remove, and return the item at the head of the queue when called by ISR code. More...

void	peek (char &recv_item)
	Get the item at the queue head without removing it. More...

char	peek (void)
	Return a copy of the item at the queue head without removing it. More...

void	ISR_peek (char &recv_item)
	Get the item at the front of the queue without deleting it, from within an ISR. More...

char	ISR_peek (void)
	Return a copy of the item at the front of the queue without deleting it, from within an ISR. More...

bool	any (void)
	Return true if the queue has contents which can be read. More...

void	operator<< (char new_data)
	Operator which inserts data into the queue. More...

void	operator>> (char &put_here)
	Read data from the queue. More...

bool	ISR_any (void)
	Return true if the queue has items in it, from within an ISR. More...

unsigned portBASE_TYPE	available (void)
	Return the number of items in the queue. More...

unsigned portBASE_TYPE	ISR_available (void)
	Return the number of items in the queue, to an ISR. More...

void	print_in_list (Print &print_dev)
	Print the queue's status to a serial device. More...

bool	usable (void)
	Indicates whether this queue is usable. More...

QueueHandle_t	get_handle (void)
	Return a handle to the FreeRTOS structure which runs this queue. More...

Public Member Functions inherited from BaseShare
	BaseShare (const char *p_name=NULL)
	Construct a base shared data item. More...

Additional Inherited Members
Protected Attributes inherited from Queue< char >
QueueHandle_t	handle
	Hhandle for the FreeTOS queue.

TickType_t	ticks_to_wait
	RTOS ticks to wait for empty.

uint16_t	buf_size
	Size of queue buffer in bytes.

uint16_t	max_full
	Maximum number of bytes in queue.

Protected Attributes inherited from BaseShare
char	name [16]
	The name of the shared item. More...

BaseShare *	p_next
	Pointer to the next item in the linked list of shares. More...

Static Protected Attributes inherited from BaseShare
static BaseShare *	p_newest = NULL
	Pointer to the most recently created shared data item. More...

Detailed Description

Implements a queue to transmit text from one RTOS task to another.

Since multithreaded tasks must not use unprotected shared data items for communication, queues are a primary means of intertask communication. Other means include shared data items (see taskshare.h) and carrier pigeons. The use of a C++ class template allows the compiler to check that you're putting the correct type of data into each queue and getting the correct type of data out, thus helping to prevent programming mistakes that can corrupt your data.

The size of FreeRTOS queues is limited to 255 items in 8-bit microcontrollers whose portBASE_TYPE is an 8-bit number. This is a FreeRTOS feature.

Usage

The following bits of code show how to set up and use a queue to transfer text from one hypothetical task called task_A to another called task_B.

Near the top of the file which contains setup() we create a queue. The constructor of the TextQueue class is given the maximum number of characters which can be stored in the queue (100 in this example) and an optional name for the queue:

#include <PrintStream.h>
#include "textqueue.h"
...
/// This queue holds angry complaints
TextQueue whiny_queue (100, "Complaints");

In a location which is before we use the queue in any other file than the one in which the queue was created, we re-declare the queue with the keyword extern to make it accessible to any task within that file:

extern TextQueue whiny_queue;

In the sending task, task_A, text is put into the queue:

int16_t n_fish = -3;                  ///< I guess we owe someone
...
/// Write into the queue the easy way, with stream insertions
whiny_queue << "I only have " << fish << " fish!" << endl;

In the receiving task, data is read from the queue one character at a time using the >> operator. In typical usage, the call to >> will block the receiving task until data has been put into the queue by the sending task:

char recv_ch;                         ///< Holds received data
...
for (;;)
{
    whiny_queue.get (recv_ch);        // Get data from the queue
    Serial.print (recv_ch);           // Or use << to print
}

Constructor & Destructor Documentation

◆ TextQueue()

TextQueue::TextQueue	(	BaseType_t	queue_size,
		const char *	p_name = `NULL`,
		TickType_t	wait_time = `portMAX_DELAY`
	)

inline

Construct a queue object, allocating memory for the buffer.

This constructor creates the FreeRTOS queue which is wrapped by the Queue class.

Parameters

queue_size	The number of chars which can be stored in the queue
p_name	A name to be shown in the list of task shares (default empty String)
wait_time	How long, in RTOS ticks, to wait for a queue to empty before a character can be sent. (Default: `portMAX_DELAY`, which causes the sending task to block until sending occurs.)

Member Function Documentation

◆ write()

virtual size_t TextQueue::write ( uint8_t a_char )

inlinevirtual

Write a character into the queue in the Print style.

This method is pure virtual in class Print, so it must be specified here. It puts one character into the queue.

Parameters

a_char The character to be queued

Returns: The number of characters written, which is one when returning

The documentation for this class was generated from the following file:

textqueue.h