topic.h File Reference

#include "FreeRTOS.h"
#include "queue.h"
#include "stdbool.h"

Go to the source code of this file.

Data Structures
struct	Message
	Type definition for generic message struct. More...
struct	Topic
	Public representation of a Topic. More...

Macros
#define	SUBSCRIBE_TOPIC(topic, inbox, length, size)
	Macro to declare a subscription to a specific topic.
#define	CREATE_MESSAGE(name, length_)
	Macro to define, on the stack, a named message struct.

Functions
bool	Topic_comment (Topic *topic, uint8_t *comment)
	Send a "comment" back to the originator of a topic.

---

Data Structure Documentation

Message

struct Message

Type definition for generic message struct.

Typically variables of this type should not be defined on their own, however the Message structure is useful in parsing received messages from their raw binary.

For initialisation of a message to be sent on a topic refer to CREATE_MESSAGE.

Definition at line 29 of file topic.h.

Topic

struct Topic

Public representation of a Topic.

This structure provides the necessary handle for subscribers (or others) to send data back to the topic authors.

Definition at line 71 of file topic.h.

Data Fields
PubInbox_t	commentInbox	Queue handle used to send messages back to topic authors.

Macro Definition Documentation

SUBSCRIBE_TOPIC

#define SUBSCRIBE_TOPIC	(		topic,
			inbox,
			length,
			size )

Value:

  SubInbox_t __attribute__((section("." #topic "_subscription"))) inbox; \
  inbox = xQueueCreate(length, size);

Macro to declare a subscription to a specific topic.

This macro declares a FreeRTOS queue handle (subscription) and places it into a special linker section named ".<topic>_subscription". The CREATE_TOPIC macro uses these sections to automatically discover all subscribers for a given topic at runtime during initialization.

Note

The subscriber task MUST create the queue assigned to the subscription variable. This macro only declares the handle and places it in the linker section for discovery.

Definition at line 46 of file topic.h.

CREATE_MESSAGE

#define CREATE_MESSAGE	(		name,
			length_ )

Value:

  struct {                            \
    uint8_t length;                   \
    uint8_t data[length_];            \
  } name = {.length = length_};

Macro to define, on the stack, a named message struct.

This structure provides receivers of messages on a topic with the associated data and its length for parsing.

The message length is encoded in the first byte, with data as a fixed length array member.

Definition at line 59 of file topic.h.

Function Documentation

Topic_comment()

bool Topic_comment	(	Topic *	topic,
		uint8_t *	comment )

Send a "comment" back to the originator of a topic.

This function allows a task (typically a subscriber, but not necessarily) to send data back to the task that created the topic.

Parameters

topic	Pointer to the public Topic structure representing the target topic. This structure must have been properly initialized.
comment	Pointer to the data buffer containing the comment message to send. The size and structure of this data must be known by both the sender and the topic originator's receiving task.

Returns

true if the comment was successfully sent to the topic's queue (or if arguments were valid).

false if topic or comment is NULL.

TODO: Implement optional argument for block time to allow readers to define how long the task should block when the queue is full.

---

Definition at line 43 of file topic.c.