broker.h File Reference

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:

Go to the source code of this file.

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

Typedefs
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 StMessageVt *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.
void *	st_subscriber_await (StSubscriber *sber)
	Wait for the messages that are wanted by the subscriber.
void *	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.

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 (StMessageVt).

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()

Function Documentation

st_broker_create()

StBroker * st_broker_create

(

const struct StMessageVt *

vp

)

Create the message broker.

Parameters

[in]

vp

The pointer to the vtable for the StMessage.

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

• st_publish(),
• st_subscriber_await(),
• st_subscriber_poll().

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_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 passed to the StMessageVt::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()

StMessage * 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 return the message immediately, if there are any messages in the subscriber's queue. If the subscriber's queue is empty, 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 message.

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()

void * 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 return the message, if there are any messages in the subscriber's queue. If the subscriber's queue is empty, it will return NULL.

Returns

The message.

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

Functions st_subscriber_await() and st_subscriber_poll() call st_subscriber_unload() automatically, there is no need to release the last received message if the subscriber attempts to receive another message.