Message broker. More...

#include <stdarg.h>
#include <stddef.h>

Include dependency graph for broker.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	StLoadVt
	Vtable for message construction. More...

Typedefs
typedef char	StLoad
	Opaque data type that represents the message load.

typedef struct StBroker	StBroker
	The message broker.

typedef struct StSubscriber	StSubscriber
	The subscriber.

typedef struct StChannel	StChannel
	The channel for messages.

Functions
void	st_publish (StChannel *ch,...)
	Broadcast the message.

void	st_subscribe (StSubscriber sber, const char topic)
	Subscribe to a topic.

StBroker *	st_broker_create (const struct StLoadVt *vp)
	Create the message broker.

void	st_broker_destroy (StBroker *broker)
	Destroy the message broker.

StChannel *	st_broker_search (StBroker broker, const char topic)
	Find the channel that is assigned to the given topic.

const char *	st_channel_gettopic (const StChannel *ch)
	Get the topic for the given channel.

StSubscriber *	st_subscriber_create (StBroker *broker)
	Create the subscriber.

void	st_subscriber_destroy (StSubscriber *sber)
	Destroy the subscriber.

StLoad *	st_subscriber_await (StSubscriber *sber)
	Wait for the messages that are wanted by the subscriber.

StLoad *	st_subscriber_poll (StSubscriber *sber)
	Poll for the messages that are wanted by the subscriber.

void	st_subscriber_unload (StSubscriber *sber)
	Inform the broker that the message can be released for the given subscriber.

StChannel *	st_load_getchan (const StLoad *load)
	Get the source channel of the message.

Detailed Description

Message broker.

This header file provides data types and functions that implement the publish-subscribe messaging pattern.

Typedef Documentation

◆ StBroker

typedef struct StBroker StBroker

The message broker.

The broker holds the list of all subscribers (StSubscriber) in usage and a dictionary of channels (StChannel). All the messaging done through channels created by the same broker will also use the same API for message construction (StLoadVt).

◆ StChannel

typedef struct StChannel StChannel

The channel for messages.

Note: Channel is related to the topic through the dictionary owned by the message broker.

See also: st_broker_search()

◆ StLoad

typedef char StLoad

Opaque data type that represents the message load.

The memory for each message has two contexts:

direct - allocated from the memory pool;
indirect - optional, allocated within StLoadVt::ctor.

It is for the user to decide how to use those contexts by defining the message constructor (StLoadVt::ctor).

Direct context is a contiguous memory block allocated from fixed-size memory pool and its size is constant for all messages. The size of the block is a multiple of the size of the metadata, big enough to hold one instance of the metadata and one instance of the user defined load. The size of the load for the direct context is defined with the StLoadVt::size callback.

See also: StPool

Direct context
Array	meta + load (StLoad*)
0	meta
...	load
n-1
n

The indirect context is optional and it is everything that is allocated by the contructor callback - StLoadVt::ctor and that is accessible through pointers placed somewhere in the direct context.

Function Documentation

◆ st_broker_create()

StBroker * st_broker_create ( const struct StLoadVt * vp )

Create the message broker.

Parameters

[in] vp The pointer to the vtable for the StLoad.

The chosen vtable will influence the behaviour of the functions that are responsible for constructing and receiving the messages:

Returns: The pointer to the new broker.

◆ st_broker_destroy()

void st_broker_destroy ( StBroker * broker )

Destroy the message broker.

Parameters

[in] broker The pointer to the broker.

◆ st_broker_search()

StChannel * st_broker_search	(	StBroker *	broker,
		const char *	topic
	)

Find the channel that is assigned to the given topic.

Parameters

[in,out]	broker	The message broker.
[in]	topic	The topic. It is also used as the key for the channel's dictionary.

This function also creates the channel if none is found.

Returns: The pointer to the channel or NULL if NULL topic was passed.

◆ st_channel_gettopic()

const char * st_channel_gettopic ( const StChannel * ch )

Get the topic for the given channel.

Parameters

[in] ch The channel.

Returns: The topic (named channel).

◆ st_load_getchan()

StChannel * st_load_getchan ( const StLoad * load )

Get the source channel of the message.

Parameters

[in] load The pointer to the message load.

Returns: The channel

◆ st_publish()

void st_publish	(	StChannel *	ch,
			...
	)

Broadcast the message.

Parameters

[in,out]	ch	The channel to which the message is sent.
[in]	...	The list of arguments used by the StLoadVt::ctor.

Note: Channels without any subscribers are allowed. Publishing to such channel is safe and it does not have any meaningful behaviour (it does "nothing").

◆ st_subscribe()

void st_subscribe	(	StSubscriber *	sber,
		const char *	topic
	)

Subscribe to a topic.

Parameters

[in,out]	sber	The subscriber that expresses the interest in the topic.
[in]	topic	The topic to which the subscription will be made.

◆ st_subscriber_await()

StLoad * st_subscriber_await ( StSubscriber * sber )

Wait for the messages that are wanted by the subscriber.

Parameters

[in,out] sber The pointer to the subscriber.

This function will receive the message immediately and return the load, if the subscriber's message queue is not empty. Otherwise, with multithreading enabled, this will block the thread that has called this function until some other thread publishes to topic that the given subscriber is interested in. With a single thread application, the blocking is not supported.

Returns: The load.

◆ st_subscriber_create()

StSubscriber * st_subscriber_create ( StBroker * broker )

Create the subscriber.

Parameters

[in,out] broker The message broker.

Returns: The pointer to the new subscriber.

◆ st_subscriber_destroy()

void st_subscriber_destroy ( StSubscriber * sber )

Destroy the subscriber.

Parameters

[in,out] sber The pointer to the subscriber.

◆ st_subscriber_poll()

StLoad * st_subscriber_poll ( StSubscriber * sber )

Poll for the messages that are wanted by the subscriber.

Parameters

[in,out] sber The pointer to the subscriber.

This function will receive the message and return the load, if the subscriber's message queue is not empty. Otherwise, it will return NULL.

Returns: The load.

◆ st_subscriber_unload()

void st_subscriber_unload ( StSubscriber * sber )

Inform the broker that the message can be released for the given subscriber.

Parameters

[in,out] sber The pointer to the subscriber.

Release the last message received by the subscriber - decrement the subscribers counter for the message. When the counter hits 0, the message is returned to the memory pool.

Note: The functions st_subscriber_await() and st_subscriber_poll() call this function automatically, there is no need to release the last received message if the subscriber attempts to receive another message.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ StBroker

◆ StChannel

◆ StLoad

Function Documentation

◆ st_broker_create()

◆ st_broker_destroy()

◆ st_broker_search()

◆ st_channel_gettopic()

◆ st_load_getchan()

◆ st_publish()

◆ st_subscribe()

◆ st_subscriber_await()

◆ st_subscriber_create()

◆ st_subscriber_destroy()

◆ st_subscriber_poll()

◆ st_subscriber_unload()