_topic.h File Reference

#include "topic.h"
#include "stdbool.h"

Go to the source code of this file.

Data Structures
struct	PrivateTopic
	Internal representation of a Topic instance. More...

Macros
#define	DECLARE_TOPIC(topic)
	Macro to declare a topic instance.
#define	INIT_TOPIC(topic, commentInboxSize, messageSize)
	Macro to initialise a declared topic instance.
#define	CREATE_TOPIC(topic, commentInboxSize, messageSize)
	Macro to define and initialize a topic instance.

Functions
bool	Topic_publish (PrivateTopic *topic, uint8_t *article)
	Publish an "article" to all discovered subscribers of a topic.

---

Data Structure Documentation

PrivateTopic

struct PrivateTopic

Internal representation of a Topic instance.

Holds the complete state for a topic managed by the publisher. This structure is primarily manipulated by the CREATE_TOPIC macro and the Topic_publish function.

Definition at line 73 of file _topic.h.

Data Fields
Topic	public	Public topic interface.
const SubInbox_t *	subscriptions	Subscription inbox array pointer.
size_t	numSubscriptions	Number of subscriptions to the topic.

Macro Definition Documentation

DECLARE_TOPIC

#define DECLARE_TOPIC

(

topic

)

Value:

  PrivateTopic topic;                                        \
  extern const SubInbox_t __##topic##_subscriptions_start[]; \
  extern const SubInbox_t __##topic##_subscriptions_end[];

Macro to declare a topic instance.

This macro performs several key actions for creating a publishable topic:

1. Declares a static PrivateTopic variable named topic.
2. Declares external symbols defined by the linker script to mark the beginning and end of the memory section containing all subscribtion queues. (__<topic>_subscriptions_start, __<topic>_subscriptions_end)

Definition at line 24 of file _topic.h.

INIT_TOPIC

#define INIT_TOPIC	(		topic,
			commentInboxSize,
			messageSize )

Value:

  topic.public.commentInbox = xQueueCreate(commentInboxSize, messageSize);                  \
  if (topic.public.commentInbox == NULL)                                                    \
    while (1);                                                                              \
  topic.subscriptions    = __##topic##_subscriptions_start;                                 \
  topic.numSubscriptions = __##topic##_subscriptions_end - __##topic##_subscriptions_start;

Macro to initialise a declared topic instance.

This macro:

1. Defines a static function startTopic decorated with the constructor attribute. This ensures startTopic runs automatically before main().
2. Inside startTopic:
   • Creates the FreeRTOS queue (commentInbox) for receiving "comments" sent via Topic_comment.
   • Determines the start address and number of subscriber queues by inspecting the linker-defined start/end symbols.
   • Stores this information in the topic variable.

Definition at line 42 of file _topic.h.

CREATE_TOPIC

#define CREATE_TOPIC	(		topic,
			commentInboxSize,
			messageSize )

Value:

  DECLARE_TOPIC(topic)                                     \
  __attribute__((constructor)) static void startTopic() {  \
    INIT_TOPIC(topic, commentInboxSize, messageSize)       \
  }

Macro to define and initialize a topic instance.

This macro combines the DECLARE_TOPIC and INIT_TOPIC macros to create a topic in one step and initialise it automatically at run-time prior to main function entry.

NOTE: If used, this macro must be placed at global scope within a file

TODO: Replace while(1) with assert when printf redirect is implemented

Definition at line 60 of file _topic.h.

Function Documentation

Topic_publish()

bool Topic_publish	(	PrivateTopic *	topic,
		uint8_t *	article )

Publish an "article" to all discovered subscribers of a topic.

Iterate through the array of subscriber queues that were discovered during initialization. For each valid (non-NULL) queue handle found in the array, attempt to send the provided article data to the queue without blocking.

Parameters

topic	Pointer to the PrivateTopic structure representing the topic to publish from. This contains the discovered subscriber list.
article	Pointer to the data buffer containing the article/message to publish. The size and structure must be consistent with what subscribers expect and the size used when subscribers created their queues.

Returns

true if the arguments (topic, article) are valid and the publishing loop completed. Note: Does not guarantee successful delivery to all subscribers (queues might be full, handles might be invalid if subscriber didn't create queue correctly, etc.).

false if topic or article is NULL.

---

Definition at line 74 of file topic.c.