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	CnLoadVt
	Vtable for message construction. More...

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

typedef struct CnBroker	CnBroker
	The message broker.

typedef struct CnSubscriber	CnSubscriber
	The subscriber.

typedef struct CnChannel	CnChannel
	The channel for messages.

Functions
void	cn_publish (CnChannel *ch,...)
	Broadcast the message.

void	cn_subscribe (CnSubscriber sber, const char topic)
	Subscribe to a topic.

CnBroker *	cn_broker_create (const struct CnLoadVt *vp)
	Create the message broker.

void	cn_broker_destroy (CnBroker *broker)
	Destroy the message broker.

CnChannel *	cn_broker_search (CnBroker broker, const char topic)
	Find the channel that is assigned to the given topic.

const char *	cn_channel_gettopic (const CnChannel *ch)
	Get the topic for the given channel.

CnSubscriber *	cn_subscriber_create (CnBroker *broker)
	Create the subscriber.

void	cn_subscriber_destroy (CnSubscriber *sber)
	Destroy the subscriber.

CnLoad *	cn_subscriber_await (CnSubscriber sber, CnChannel *ch)
	Wait for the messages that are wanted by the subscriber.

CnLoad *	cn_subscriber_poll (CnSubscriber sber, CnChannel *ch)
	Poll for the messages that are wanted by the subscriber.

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

Detailed Description

Message broker.

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

Typedef Documentation

◆ CnBroker

typedef struct CnBroker CnBroker

The message broker.

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

◆ CnChannel

typedef struct CnChannel CnChannel

The channel for messages.

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

See also: cn_broker_search()

◆ CnLoad

typedef char CnLoad

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 CnLoadVt::ctor.

It is for the user to decide how to use those contexts by defining the message constructor (CnLoadVt::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 CnLoadVt::size callback.

See also: CnPool

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

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

Function Documentation

◆ cn_broker_create()

CnBroker * cn_broker_create ( const struct CnLoadVt * vp )

Create the message broker.

Parameters

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

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.

◆ cn_broker_destroy()

void cn_broker_destroy ( CnBroker * broker )

Destroy the message broker.

Parameters

[in] broker The pointer to the broker.

◆ cn_broker_search()

CnChannel * cn_broker_search	(	CnBroker *	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.

◆ cn_channel_gettopic()

const char * cn_channel_gettopic ( const CnChannel * ch )

Get the topic for the given channel.

Parameters

[in] ch The channel.

Returns: The topic (named channel).

◆ cn_publish()

void cn_publish	(	CnChannel *	ch,
			...
	)

Broadcast the message.

Parameters

[in,out]	ch	The channel to which the message is sent.
[in]	...	The list of arguments used by the CnLoadVt::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").

◆ cn_subscribe()

void cn_subscribe	(	CnSubscriber *	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.

◆ cn_subscriber_await()

CnLoad * cn_subscriber_await	(	CnSubscriber *	sber,
		CnChannel **	ch
	)

Wait for the messages that are wanted by the subscriber.

Parameters

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

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.

If the pointer to the channel reference is not NULL, it will be set to the message's source channel.

Returns: The load.

◆ cn_subscriber_create()

CnSubscriber * cn_subscriber_create ( CnBroker * broker )

Create the subscriber.

Parameters

[in,out] broker The message broker.

Returns: The pointer to the new subscriber.

◆ cn_subscriber_destroy()

void cn_subscriber_destroy ( CnSubscriber * sber )

Destroy the subscriber.

Parameters

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

◆ cn_subscriber_poll()

CnLoad * cn_subscriber_poll	(	CnSubscriber *	sber,
		CnChannel **	ch
	)

Poll for the messages that are wanted by the subscriber.

Parameters

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

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

If the pointer to the channel reference is not NULL, it will be set to the message's source channel.

Returns: The load.

◆ cn_subscriber_release()

void cn_subscriber_release ( CnSubscriber * 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 cn_subscriber_await() and cn_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

◆ CnBroker

◆ CnChannel

◆ CnLoad

Function Documentation

◆ cn_broker_create()

◆ cn_broker_destroy()

◆ cn_broker_search()

◆ cn_channel_gettopic()

◆ cn_publish()

◆ cn_subscribe()

◆ cn_subscriber_await()

◆ cn_subscriber_create()

◆ cn_subscriber_destroy()

◆ cn_subscriber_poll()

◆ cn_subscriber_release()