Message Bus
20.33.0
This page documents version 20.0.0 and above.
A variant of the observer pattern in that message routers and derived types are be able to subscribe to messages on a
bus. The messages can be either broadcast, to be automatically picked up by any router that has a handler, or
addressed to a particular router or router id. Message buses may be nested by setting a successor.
____________________________________________________________________________________________________
imessage_bus
Derived from imessage_router
The base for all message buses.
Message buses are therefore also a type of router.
Objects of type etl::imessage_bus cannot be directly constructed.
Member functions
bool subscribe(etl::imessage_router& router);
Subscribes an etl::imessage_router derived class to the bus.
Returns true on success.
____________________________________________________________________________________________________
void unsubscribe(etl::imessage_router& router);
Unsubscribes the specified etl::imessage_router derived class from the bus.
Does not unsubscribe from nested buses.
____________________________________________________________________________________________________
void unsubscribe(etl::message_router_id_t id)
Unsubscribes routers with the specified id from the bus.
Does not unsubscribe from nested buses.
etl::imessage::MESSAGE_BUS will unsubscribe all message buses.
etl::imessage::ALL_MESSAGE_ROUTERS will unsubscribe all routers and buses. Equivalent to calling clear().
____________________________________________________________________________________________________
void receive(const etl::imessage& message);
void receive(etl::shared_message message);
Receives a message and distributes it to all subscribers.
Forwards the message to any successor.
The routers are called first, in order of ascending router id.
Routers with the duplicate ids will be called in subscribe order.
Any nested message buses are called in subscribe order.
____________________________________________________________________________________________________
void receive(etl::message_router_id_t destination_router_id,
const etl::imessage& message);
void receive(etl::message_router_id_t destination_router_id,
etl::shared_message message);
Receives a message and distributes it to all subscribers that have the specified router id.
Forwards the message to any successor.
Routers with the duplicate ids will be called in subscribe order.
Any nested message buses are called in subscribe order.
Override this in a derived class if you wish to capture messages sent to the bus.
Call the base receive function from here to allow normal operation to continue.
____________________________________________________________________________________________________
bool accepts(etl::message_id_t id) const;
Always returns true.
____________________________________________________________________________________________________
size_t size() const;
Returns the number of subscribers.
____________________________________________________________________________________________________
void clear();
Clears the bus of all subscribers.
Message buses inherit all of the public functions of etl::imessage_router.
Errors
message_bus_exception
Base error class for etl::message_bus. Inherits from etl::exception
____________________________________________________________________________________________________
message_bus_too_many_subscribers
Emitted when the number of subscribers exceeds the capacity. Inherits from etl::message_bus_exception.
____________________________________________________________________________________________________
message_bus
Derived from imessage_bus.
template <const uint_least8_t MAX_ROUTERS>
class message_bus
MAX_ROUTERS The maximum number of routers that can be subscribed.
____________________________________________________________________________________________________
Member functions
message_bus()
Constructs a message bus.
Message buses always have a router id of etl::imessage::MESSAGE_BUS.
message_bus(etl::imessage_router& successor)
Constructs a message bus and sets the successor.
Message buses always have a router id of etl::imessage::MESSAGE_BUS.
____________________________________________________________________________________________________
Example
enum
{
ROUTER_ID_1,
ROUTER_ID_2,
ROUTER_ID_3
};
MessageA messageA;
RouterA routerA(ROUTER_ID_1);
RouterB routerB(ROUTER_ID_1);
RouterC routerC(ROUTER_ID_2);
RouterD routerD(ROUTER_ID_3);
RouterE routerE(ROUTER_ID_1);
etl::message_bus<4> bus1;
etl::message_bus<2> bus2;
etl::message_bus<1> bus3;
bus1.subscribe(bus3);
bus1.subscribe(bus2);
bus1.subscribe(routerB);
bus1.subscribe(routerA);
bus2.subscribe(routerD);
bus2.subscribe(routerC);
bus3.subscibe(routerE);
bus1.receive(messageA);
The call order will be...
routerB
routerA
routerE
routerC
routerD
bus1.receive(ROUTER_ID_1, messageA);
The call order will be...
routerB
routerA
routerE
bus1.receive(ROUTER_ID_3, messageA);
The call order will be...
routerD