lintel::EventBus Class Reference

#include <EventBus.h>

Public Member Functions
	EventBus (const std::string &name, const EventBusConfig &config, ShmSegmentAccessor segment)
	~EventBus ()
	EventBus (const EventBus &)=delete
EventBus &	operator= (const EventBus &)=delete
const char *	getName () const
EventBusConfig	getConfig () const
bool	isLockFree () const
bool	registerTopic (const std::string &topic)
bool	isTopicRegistered (const std::string &topic) const
std::size_t	topicCount () const
bool	subscribe (const std::string &topic, const std::string &subscriber)
bool	unsubscribe (const std::string &topic, const std::string &subscriber)
bool	isSubscribed (const std::string &topic, const std::string &subscriber) const
std::size_t	numberOfSubscribersOf (const std::string &topic) const
std::size_t	subscriberCount () const
bool	publish (const Event &event)
bool	publishToSubscribers (const Event &event)
std::optional< Event >	receive ()
std::optional< Event >	receiveOf (const std::string &subscriber)
bool	isEmpty () const
bool	isEmptyOf (const std::string &subscriber) const
std::int64_t	sequenceOf () const
std::uint64_t	droppedEventsOf () const
void	reset ()

Static Public Member Functions
static std::size_t	requiredSize (const EventBusConfig &config)

Detailed Description

Lock-free, IPC-capable event bus living inside a shared memory segment.

The bus offers two delivery modes:

• point-to-point: events are pushed into a single multi-producer / multi-consumer queue and received by calling receive(),
• publish/subscribe: events are pushed into the queue of every subscriber of the event topic (broadcast).

All queues are strictly bounded, lock-free MPMC ring buffers with fixed capacity that live inside the shared memory segment. They are IPC-safe: the node buffers are addressed relative to the bus object, so they remain valid regardless of the virtual address a process mapped the segment at. The topic/subscriber registry is guarded by a short spin lock that tolerates crashed processes.

The class is stored inside the shared memory segment and therefore must not use virtual functions (vtable pointers would point into the process that constructed the bus). The abstract IEventBus is provided for the local service layer.

Constructor & Destructor Documentation

EventBus() [1/2]

lintel::EventBus::EventBus	(	const std::string &	name,
		const EventBusConfig &	config,
		ShmSegmentAccessor	segment
	)

Construct an EventBus. The constructor is only executed when the bus is created for the first time in the segment; later processes find the already constructed object.

Parameters

name	the name of the bus
config	the runtime configuration
segment	accessor to the segment to allocate the queues from

Exceptions

std::invalid_argument

if the configuration is invalid

~EventBus()

lintel::EventBus::~EventBus

(

)

Destroys the per-subscriber queues.

Note

the object normally lives forever inside the segment

EventBus() [2/2]

lintel::EventBus::EventBus ( const EventBus &  )

delete

Member Function Documentation

droppedEventsOf()

std::uint64_t lintel::EventBus::droppedEventsOf

(

)

const

Returns

the number of events that were dropped due to full queues

getConfig()

EventBusConfig lintel::EventBus::getConfig

(

)

const

Returns

the configuration the bus was created with

getName()

const char * lintel::EventBus::getName

(

)

const

Returns

the name of the bus

isEmpty()

bool lintel::EventBus::isEmpty

(

)

const

Returns

true if the point-to-point bus queue is empty

isEmptyOf()

bool lintel::EventBus::isEmptyOf

(

const std::string &

subscriber

)

const

Parameters

subscriber

the subscriber name

Returns

true if the subscriber queue is empty or unknown

isLockFree()

bool lintel::EventBus::isLockFree

(

)

const

Returns

true if the underlying queues are lock-free

isSubscribed()

bool lintel::EventBus::isSubscribed	(	const std::string &	topic,
		const std::string &	subscriber
	)		const

Parameters

topic	the topic name
subscriber	the subscriber name

Returns

true if the subscriber is subscribed to the topic

isTopicRegistered()

bool lintel::EventBus::isTopicRegistered

(

const std::string &

topic

)

const

Parameters

topic

the topic name

Returns

true if the topic is registered

numberOfSubscribersOf()

std::size_t lintel::EventBus::numberOfSubscribersOf

(

const std::string &

topic

)

const

Parameters

topic

the topic name

Returns

the number of subscribers of the topic

operator=()

EventBus & lintel::EventBus::operator= ( const EventBus &  )

delete

publish()

bool lintel::EventBus::publish

(

const Event &

event

)

Publish an event into the point-to-point bus queue.

Parameters

event

the event to publish

Returns

false if the bus queue is full

publishToSubscribers()

bool lintel::EventBus::publishToSubscribers

(

const Event &

event

)

Publish an event to every subscriber of the event topic.

Parameters

event

the event to publish

Returns

false if no subscriber received the event

receive()

std::optional< Event > lintel::EventBus::receive

(

)

Receive the next event from the point-to-point bus queue.

Returns

the event or std::nullopt if the queue is empty

receiveOf()

std::optional< Event > lintel::EventBus::receiveOf

(

const std::string &

subscriber

)

Receive the next event of a subscriber queue.

Parameters

subscriber

the subscriber name

Returns

the event or std::nullopt if the queue is empty

registerTopic()

bool lintel::EventBus::registerTopic

(

const std::string &

topic

)

Register a topic on the bus (idempotent).

Parameters

topic

the topic name

Returns

false if the topic table is full

requiredSize()

static std::size_t lintel::EventBus::requiredSize ( const EventBusConfig &  config )

static

Compute the shared memory size needed for a given configuration.

Parameters

config

the runtime configuration

Returns

the required segment size in bytes, 0 if the config is invalid

reset()

void lintel::EventBus::reset

(

)

Drop all queued events on the bus and every subscriber queue.

sequenceOf()

std::int64_t lintel::EventBus::sequenceOf

(

)

const

Returns

the last assigned sequence number

subscribe()

bool lintel::EventBus::subscribe	(	const std::string &	topic,
		const std::string &	subscriber
	)

Subscribe a named subscriber to a topic.

Parameters

topic	the topic name
subscriber	the subscriber name

Returns

false if the topic does not exist or the table is full

subscriberCount()

std::size_t lintel::EventBus::subscriberCount

(

)

const

Returns

the number of reserved subscriber slots

topicCount()

std::size_t lintel::EventBus::topicCount

(

)

const

Returns

the number of registered topics

unsubscribe()

bool lintel::EventBus::unsubscribe	(	const std::string &	topic,
		const std::string &	subscriber
	)

Unsubscribe a named subscriber from a topic.

Parameters

topic	the topic name
subscriber	the subscriber name

Returns

true if the subscriber was removed

---

The documentation for this class was generated from the following file:

• src/include/lintel/features/base/events/EventBus.h