mirror of
https://github.com/ETLCPP/etl.git
synced 2026-06-15 08:26:04 +08:00
Merge branch 'development' into chru-atomic-constexpr
This commit is contained in:
Roland Reichwein
GitHub
commit
73b2906e04
@ -1,23 +0,0 @@
|
||||
---
|
||||
title: "Messaging"
|
||||
weight: 100
|
||||
---
|
||||
|
||||
## Headers
|
||||
|
||||
- `message.h`
|
||||
Defines the core message model. etl::imessage is the base interface (virtual or non-virtual, depending on `ETL_HAS_VIRTUAL_MESSAGES`). `etl::message<ID>` provides typed messages with static IDs. Type traits (`is_message`, `is_message_type`, etc.) and ID comparison utilities support compile-time validation.
|
||||
- `message_router.h`
|
||||
Defines `etl::imessage_router`, the central routing interface with receive, accepts, and router identity. Provides message_router<TDerived, ...> that statically dispatches by message ID (contiguous IDs optimized). Includes null_message_router and message_producer helpers, plus send_message utilities.
|
||||
- `message_bus.h`
|
||||
Implements `etl::imessage_bus`, a router that manages a sorted list of subscribed routers and forwards messages based on destination ID (broadcast or addressed). Supports subscription limits and forwards to successors.
|
||||
- `message_broker.h`
|
||||
Implements etl::message_broker, a router with explicit subscription objects mapping routers to message ID lists (span). It routes only to subscribers that match both message ID and destination ID, then forwards to any successor.
|
||||
- `message_packet.h`
|
||||
A type-erased, in-place container for a fixed set of message types. Validates message ID acceptance, supports copy/move, and exposes `get()` as `etl::imessage&`. Uses aligned storage sized to the largest message type.
|
||||
- `shared_message.h`
|
||||
Reference-counted wrapper around pooled messages (`ireference_counted_message_pool`). Supports copy/move semantics with automatic release when the last reference drops.
|
||||
|
||||
## Basic architecture
|
||||
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 8.3 KiB |
@ -1,217 +0,0 @@
|
||||
---
|
||||
title: "message_broker"
|
||||
weight: 6
|
||||
---
|
||||
|
||||
{{< callout type="info">}}
|
||||
Header: `message_broker.h`
|
||||
{{< /callout >}}
|
||||
|
||||
Message Broker
|
||||
|
||||
A variant of the observer pattern in that message routers and derived types are be able to subscribe to selected sets of messages. The message_broker is similar to the message_bus, but it provides more control over the routing of messages. While the message_bus simply broadcasts every message to all subscribers, the message_broker allows you to specify which subscribers should receive each message.
|
||||
|
||||
Derived from `imessage_router`.
|
||||
|
||||
## Types
|
||||
|
||||
```cpp
|
||||
message_id_span_t etl::span<const etl::message_id_t>
|
||||
```
|
||||
|
||||
## subscription
|
||||
A nested class of `etl::message_broker`.
|
||||
The base for broker subscription information.
|
||||
Derive from this to define your subscription class.
|
||||
See Example.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
subscription(etl::imessage_router& router)
|
||||
```
|
||||
Constructor.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
virtual message_id_span_t message_id_list() const = 0;
|
||||
```
|
||||
Override this to return a span of message ids.
|
||||
|
||||
## message_broker
|
||||
|
||||
```cpp
|
||||
message_broker()
|
||||
```
|
||||
The broker is constructed with an id of `etl::imessage_router::MESSAGE_BROKER`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_broker(etl::imessage_router& successor)
|
||||
```
|
||||
The broker is constructed with an id of `etl::imessage_router::MESSAGE_BROKER`.
|
||||
Sets the successor.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_broker(etl::message_router_id_t id)
|
||||
```
|
||||
The broker is constructed with the specified id.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_broker(etl::message_router_id_t id, etl::imessage_router& successor)
|
||||
```
|
||||
The broker is constructed with the specified id.
|
||||
Sets the successor.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void subscribe(etl::imessage_router& router)
|
||||
```
|
||||
Subscribes an `etl::imessage_router` derived class to the broker.
|
||||
A subscription object must have a lifetime of at least the same as the broker.
|
||||
A subscription cannot be shared with another broker.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void unsubscribe(etl::imessage_router& router)
|
||||
```
|
||||
Unsubscribes the specified `etl::imessage_router` derived class from the bus.
|
||||
Does not unsubscribe from nested buses.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void receive(const etl::imessage& message)
|
||||
void receive(etl::shared_message message)
|
||||
```
|
||||
Receives a message and distributes it to all subscribers that have registered to receive the message type.
|
||||
Forwards the message to any successor.
|
||||
|
||||
Override this in a derived class if you wish to capture messages sent to the broker.
|
||||
Call the base receive function from here to allow normal operation to continue.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
bool accepts(etl::message_id_t id) const
|
||||
```
|
||||
Always returns `true`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void clear()
|
||||
```
|
||||
Clears the broker of all subscribers.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_DEPRECATED bool is_null_router() const ETL_OVERRIDE
|
||||
```
|
||||
Always returns `false`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
bool is_producer() const ETL_OVERRIDE
|
||||
```
|
||||
Always returns `true`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
bool is_consumer() const ETL_OVERRIDE
|
||||
```
|
||||
Always returns `true`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
bool empty() const
|
||||
```
|
||||
Returns `true` is the are are no subscribers.
|
||||
|
||||
## Example
|
||||
```cpp
|
||||
// Some router ids.
|
||||
enum
|
||||
{
|
||||
ROUTER_ID_1,
|
||||
ROUTER_ID_2,
|
||||
};
|
||||
|
||||
// Custom subscription type.
|
||||
class Subscription : public etl::message_broker::subscription
|
||||
{
|
||||
public:
|
||||
|
||||
Subscription(etl::imessage_router& router, std::initializer_list<etl::message_id_t> id_list_)
|
||||
: etl::message_broker::subscription(router)
|
||||
, id_list(id_list_)
|
||||
{
|
||||
}
|
||||
|
||||
etl::message_broker::message_id_span_t message_id_list() const override
|
||||
{
|
||||
return etl::message_broker::message_id_span_t(id_list.begin(), id_list.end());
|
||||
}
|
||||
|
||||
std::vector<etl::message_id_t> id_list;
|
||||
};
|
||||
|
||||
// Instances of messages.
|
||||
Message1 message1;
|
||||
Message2 message2;
|
||||
Message3 message3;
|
||||
Message4 message4;
|
||||
|
||||
// Custom broker.
|
||||
class Broker : public etl::message_broker
|
||||
{
|
||||
public:
|
||||
|
||||
using etl::message_broker::receive;
|
||||
|
||||
// Hook incoming messages and translate Message4 to Message3.
|
||||
void receive(const etl::imessage& msg) override
|
||||
{
|
||||
if (msg.get_message_id() == Message4::ID)
|
||||
{
|
||||
etl::message_broker::receive(Message3());
|
||||
}
|
||||
else
|
||||
{
|
||||
etl::message_broker::receive(msg);
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// Instances of message routers.
|
||||
Router1 router1;
|
||||
Router2 router2;
|
||||
|
||||
// The subscriptions.
|
||||
Subscription subscription1{ router1, { Message1::ID, Message2::ID } };
|
||||
Subscription subscription2{ router2, { Message2::ID, Message3::ID } };
|
||||
|
||||
// Instance of message broker.
|
||||
etl::message_broker broker;
|
||||
|
||||
// Subscribe router1 and router1 to the broker.
|
||||
broker.subscribe(subscription1);
|
||||
broker.subscribe(subscription2);
|
||||
|
||||
broker.receive(message1); // Received by router1
|
||||
broker.receive(message2); // Received by router1 and router2
|
||||
broker.receive(message3); // Received by router2
|
||||
broker.receive(message4); // Received by router2 as a Message3
|
||||
```
|
||||
@ -1,207 +0,0 @@
|
||||
---
|
||||
title: "message_bus"
|
||||
weight: 5
|
||||
---
|
||||
|
||||
{{< callout type="info">}}
|
||||
Header: `message_broker.h`
|
||||
From: `20.33.0`
|
||||
{{< /callout >}}
|
||||
|
||||
Message Bus
|
||||
|
||||
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.
|
||||
Inherits publicly from `etl::imessage_router`.
|
||||
Message buses are therefore also a type of router.
|
||||
Objects of type `etl::imessage_bus` cannot be directly constructed.
|
||||
|
||||
## Member functions
|
||||
|
||||
```cpp
|
||||
bool subscribe(etl::imessage_router& router)
|
||||
```
|
||||
Subscribes an `etl::imessage_router` derived class to the bus.
|
||||
Returns `true` on success.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void unsubscribe(etl::imessage_router& router)
|
||||
```
|
||||
Unsubscribes the specified `etl::imessage_router` derived class from the bus.
|
||||
Does not unsubscribe from nested buses.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
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()`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
bool accepts(etl::message_id_t id) const
|
||||
```
|
||||
Always returns `true`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
size_t size() const
|
||||
```
|
||||
Returns the number of subscribers.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void clear()
|
||||
```
|
||||
Clears the bus of all subscribers.
|
||||
|
||||
Message buses inherit all of the public functions of `etl::imessage_router`.
|
||||
|
||||
## Errors
|
||||
|
||||
```cpp
|
||||
message_bus_exception
|
||||
```
|
||||
Base error class for `etl::message_bus`. Inherits from `etl::exception`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
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`.
|
||||
|
||||
```cpp
|
||||
template <const uint_least8_t MAX_ROUTERS>
|
||||
class message_bus
|
||||
```
|
||||
`MAX_ROUTERS` The maximum number of routers that can be subscribed.
|
||||
|
||||
## Member functions
|
||||
|
||||
```cpp
|
||||
message_bus()
|
||||
```
|
||||
Constructs a message bus.
|
||||
Message buses always have a router id of `etl::imessage::MESSAGE_BUS`.
|
||||
|
||||
```cpp
|
||||
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
|
||||
```cpp
|
||||
// Some router ids.
|
||||
enum
|
||||
{
|
||||
ROUTER_ID_1,
|
||||
ROUTER_ID_2,
|
||||
ROUTER_ID_3
|
||||
};
|
||||
|
||||
// Instances of messages.
|
||||
MessageA messageA;
|
||||
|
||||
// Instances of message routers.
|
||||
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);
|
||||
|
||||
// Instances of message buses.
|
||||
etl::message_bus<4> bus1;
|
||||
etl::message_bus<2> bus2;
|
||||
etl::message_bus<1> bus3;
|
||||
|
||||
// Subscribe bus2 & bus3 to bus1.
|
||||
bus1.subscribe(bus3);
|
||||
bus1.subscribe(bus2);
|
||||
|
||||
// Subscribe routerB & routerA to bus1.
|
||||
bus1.subscribe(routerB);
|
||||
bus1.subscribe(routerA);
|
||||
|
||||
// Subscribe routerD & routerC to bus2.
|
||||
bus2.subscribe(routerD);
|
||||
bus2.subscribe(routerC);
|
||||
|
||||
// Subscribe routerE to bus3.
|
||||
bus3.subscibe(routerE);
|
||||
|
||||
// Assume all routers accept the same messages.
|
||||
|
||||
// Broadcast messageA to everyone.
|
||||
bus1.receive(messageA);
|
||||
|
||||
// The call order will be...
|
||||
// routerB
|
||||
// routerA
|
||||
// routerE
|
||||
// routerC
|
||||
// routerD
|
||||
|
||||
// Address messageA to routers with id ROUTER_ID_1.
|
||||
bus1.receive(ROUTER_ID_1, messageA);
|
||||
|
||||
// The call order will be...
|
||||
// routerB
|
||||
// routerA
|
||||
// routerE
|
||||
|
||||
// Address messageA to routers with id ROUTER_ID_3.
|
||||
bus1.receive(ROUTER_ID_3, messageA);
|
||||
|
||||
// The call order will be...
|
||||
// routerD
|
||||
```
|
||||
@ -1,155 +0,0 @@
|
||||
---
|
||||
title: "message_packet"
|
||||
---
|
||||
|
||||
{{< callout type="info">}}
|
||||
Header: `message_packet.h`
|
||||
{{< /callout >}}
|
||||
|
||||
A container for more than one type of message.
|
||||
The messages must have been derived from `etl::imessage`.
|
||||
|
||||
The messages types that the packet may contain are listed as template parameters.
|
||||
e.g. `etl::message_packet<Message1, Message2, Message3>`
|
||||
|
||||
From `20.40.0` message types are not required to have a virtual destructor.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_packet()
|
||||
```
|
||||
Default constructs a message packet.
|
||||
`is_valid()` returns `false`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
explicit message_packet(const etl::imessage&)
|
||||
```
|
||||
Constructs a message packet from an `etl::imessage` reference.
|
||||
Asserts an `etl::unhandled_message_exception` error if the parameter is not one listed in the template parameter list.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
explicit message_packet(etl::imessage&&) C++11
|
||||
```
|
||||
Move constructs a message packet from an `etl::imessage` rvalue reference.
|
||||
Emits an `etl::unhandled_message_exception` error if the parameter is not one listed in the template parameter list.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
template <typename TMessage>
|
||||
explicit message_packet(const TMessage&)
|
||||
```
|
||||
Constructs a message packet from a `TMessage` reference.
|
||||
Emits a compile time static assert if the parameter is not one listed in the template parameter list.
|
||||
From: `20.22.0`
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
template <typename TMessage>
|
||||
explicit message_packet(TMessage&&)
|
||||
```
|
||||
Move constructs a message packet from a `TMessage` rvalue reference.
|
||||
Emits a compile time static assert if the parameter is not one listed in the template parameter list.
|
||||
From: `20.22.0`
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_packet(const message_packet&)
|
||||
```
|
||||
Constructs a message packet from an `message_packet` reference.
|
||||
Emits an `etl::unhandled_message_exception` error if the parameter is not one listed in the template parameter list.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_packet(message_packet&&)
|
||||
```
|
||||
Move constructs a message packet from an `message_packet` rvalue reference.
|
||||
Emits an `etl::unhandled_message_exception` if the parameter is not one listed in the template parameter list.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_packet& operator =(const message_packet&)
|
||||
```
|
||||
Assigns a message packet from an `message_packet` reference.
|
||||
Emits an `etl::unhandled_message_exception` error if the parameter is not one listed in the template parameter list.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_packet& operator =(message_packet&&)
|
||||
```
|
||||
Move assigns a message packet from an `message_packet` rvalue reference.
|
||||
Emits an `etl::unhandled_message_exception` error if the parameter is not one listed in the template parameter list.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
etl::imessage& get()
|
||||
const etl::imessage& get() const
|
||||
```
|
||||
Returns a reference to an `etl::imessage`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
bool is_valid() const
|
||||
```
|
||||
Returns `true` if the packet contains a valid message, otherwise `false`.
|
||||
|
||||
---
|
||||
|
||||
## Constants
|
||||
|
||||
`SIZE` The size of the largest message.
|
||||
`ALIGNMENT` The largest message alignment.
|
||||
|
||||
---
|
||||
|
||||
## Example
|
||||
```cpp
|
||||
enum
|
||||
{
|
||||
MESSAGE1,
|
||||
MESSAGE2,
|
||||
MESSAGE3
|
||||
};
|
||||
|
||||
struct Message1 : public etl::message<MESSAGE1>
|
||||
{
|
||||
};
|
||||
|
||||
struct Message2 : public etl::message<MESSAGE2>
|
||||
{
|
||||
};
|
||||
|
||||
struct Message3 : public etl::message<MESSAGE3>
|
||||
{
|
||||
};
|
||||
|
||||
using Packet = etl::message_packet<Message1, Message2>
|
||||
|
||||
Message1 message1;
|
||||
Message2 message2;
|
||||
Message3 message3;
|
||||
|
||||
Packet packet1(message1);
|
||||
Packet packet2(message2);
|
||||
Packet packet3(message3); // Runtime time error! Packet does not support Message3 type.
|
||||
|
||||
etl::imessage& m1 = message1;
|
||||
Packet packet4(m1); // Construct from an etl::imessage reference.
|
||||
|
||||
etl::imessage& m3 = message3;
|
||||
Packet packet4(m3); // Asserts etl::unhandled_message_exception! Packet does not support Message3 type.
|
||||
|
||||
etl::imessage& m = packet2.get(); // Get a reference to an etl::imessage from the packet.
|
||||
```
|
||||
@ -1,180 +0,0 @@
|
||||
---
|
||||
title: "message_router_registry"
|
||||
weight: 4
|
||||
---
|
||||
|
||||
{{< callout type="info">}}
|
||||
Header: `message_router_registry`
|
||||
From: `20.6.0`
|
||||
{{< /callout >}}
|
||||
|
||||
A class that will act as a registry for all message router types.
|
||||
When iterating through the registry, routers with identical IDs are ordered by insertion.
|
||||
|
||||
**Defines the following classes**
|
||||
```cpp
|
||||
etl::imessage_router_registry
|
||||
etl::message_router_registry
|
||||
```
|
||||
|
||||
## imessage_router_registry
|
||||
|
||||
The base class for all router registries.
|
||||
|
||||
### Iterators
|
||||
```cpp
|
||||
iterator
|
||||
const_iterator
|
||||
```
|
||||
|
||||
### Member functions
|
||||
|
||||
```cpp
|
||||
iterator begin()
|
||||
const_iterator begin() const
|
||||
const_iterator cbegin() const
|
||||
```
|
||||
Get the beginning of the registry.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
iterator end()
|
||||
const_iterator end() const
|
||||
const_iterator cend() const
|
||||
```
|
||||
Get the end of the registry.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
iterator lower_bound(etl::message_router_id_t id)
|
||||
const_iterator lower_bound(etl::message_router_id_t id) const
|
||||
```
|
||||
Get the lower bound in the registry of the router with the specified ID.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
iterator upper_bound(etl::message_router_id_t id)
|
||||
const_iterator upper_bound(etl::message_router_id_t id) const
|
||||
```
|
||||
Get the upper bound in the registry of the router with the specified ID.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
etl::imessage_router* find(etl::message_router_id_t id)
|
||||
const etl::imessage_router* find(etl::message_router_id_t id) const
|
||||
```
|
||||
Returns a pointer to the first router with the specified ID, or `ETL_NULLPTR` if it cannot be found.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void add(etl::imessage_router& router)
|
||||
void add(etl::imessage_router* p_router)
|
||||
```
|
||||
Registers a router.
|
||||
If the registry is full then an ETL assert is emitted (`etl::message_router_registry_full`).
|
||||
Duplicate routers will be ignored.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
template <typename TIterator>
|
||||
void add(TIterator first, const TIterator& last)
|
||||
```
|
||||
Registers a collection of routers.
|
||||
If the registry becomes full then an ETL assert is emitted (`etl::message_router_registry_full`).
|
||||
Duplicate routers will be ignored.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void remove(etl::message_router_id_t id)
|
||||
```
|
||||
Unregisters a router.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
bool contains(const etl::message_router_id_t id) const
|
||||
bool contains(const etl::imessage_router* const p_router) const
|
||||
bool contains(const etl::imessage_router& router) const
|
||||
```
|
||||
Returns `true` if the registry contains a router that has the specified ID or object.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
bool empty() const
|
||||
```
|
||||
Returns `true` if the registry is empty, otherwise `false`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
bool full() const
|
||||
```
|
||||
Returns `true` if the registry is full, otherwise `false`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
size_t size() const
|
||||
```
|
||||
Returns the size of the registry.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
size_t available() const
|
||||
```
|
||||
Returns the available size of the registry.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
size_t max_size() const
|
||||
```
|
||||
Returns the maximum size of the registry.
|
||||
|
||||
---
|
||||
|
||||
## message_router_registry
|
||||
|
||||
```cpp
|
||||
message_router_registry()
|
||||
```
|
||||
Default constructor.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
template <typename TIterator>
|
||||
message_router_registry(TIterator first, const TIterator& last)
|
||||
```
|
||||
Constructs from an iterator range.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_router_registry(std::initializer_list<etl::imessage_router*> init)
|
||||
```
|
||||
Initializer_list constructor.
|
||||
Enabled for C++11 or above.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_router_registry(const message_router_registry& rhs)
|
||||
```
|
||||
Copy constructor.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
message_router_registry& operator =(const message_router_registry& rhs)
|
||||
```
|
||||
Assignment operator.
|
||||
@ -1,112 +0,0 @@
|
||||
---
|
||||
title: "message"
|
||||
weight: 1
|
||||
---
|
||||
|
||||
{{< callout type="info">}}
|
||||
Header: `message.h`
|
||||
{{< /callout >}}
|
||||
|
||||
Message types used for many of the framework classes.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
etl::message_id_t
|
||||
```
|
||||
The type used for message ids.
|
||||
By default can hold a value between 0 and 255.
|
||||
If `ETL_MESSAGE_ID_TYPE` is defined then this type will be used instead.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
etl::message_router_id_t
|
||||
```
|
||||
The type used for message router ids.
|
||||
Can hold a value between 0 and 255.
|
||||
|
||||
---
|
||||
|
||||
The message classes are the common communication method across all of the message capable frameworks.
|
||||
They are identified by a unique id number that specialises the base class.
|
||||
|
||||
## imessage
|
||||
|
||||
The base class for messages.
|
||||
It is this class that is passed around, usually by const reference.
|
||||
The class is abstract.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
etl::message_id_t get_message_id() const ETL_NOEXCEPT = 0;
|
||||
```
|
||||
Returns the id of the message.
|
||||
|
||||
---
|
||||
|
||||
## message
|
||||
|
||||
```cpp
|
||||
message<size_t ID, typename TParent = etl::imessage>
|
||||
```
|
||||
Requires an integral id as the template parameter.
|
||||
Inherits from `TParent`, which defaults to `etl::imessage`.
|
||||
`TParent` allows additional base interfaces or functionality to be included.
|
||||
static asserts if `TParent` is not a base of `etl::imessage`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ID
|
||||
```
|
||||
The id of the message as an enum.
|
||||
Can be accessed by `etl::message` instances.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
TParent
|
||||
```
|
||||
The class that it inherits from. It must ultimately derive from `etl::imessage`.
|
||||
The default is `etl::imessage`.
|
||||
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
```cpp
|
||||
enum
|
||||
{
|
||||
START,
|
||||
STOP,
|
||||
SET_SPEED
|
||||
};
|
||||
|
||||
struct MyInterface : public etl::imessage
|
||||
{
|
||||
virtual void DoStuff() = 0;
|
||||
};
|
||||
|
||||
// Start implements MyIterface
|
||||
struct Start : public etl::message<START, MyInterface>
|
||||
{
|
||||
void DoStuff() override
|
||||
{
|
||||
// Do stuff here.
|
||||
}
|
||||
};
|
||||
|
||||
struct Stop : public etl::message<STOP>
|
||||
{
|
||||
bool isEmergencyStop;
|
||||
};
|
||||
|
||||
struct SetSpeed : public etl::message<SET_SPEED>
|
||||
{
|
||||
uint32_t speed;
|
||||
};
|
||||
|
||||
void Receive(const etl::imessage& msg);
|
||||
```
|
||||
@ -1,139 +0,0 @@
|
||||
---
|
||||
title: "reference_counted_message_pool"
|
||||
---
|
||||
|
||||
{{< callout type="info">}}
|
||||
Header: `reference_counted_message_pool.h`
|
||||
Header: `ireference_counted_message_pool.h`
|
||||
{{< /callout >}}
|
||||
|
||||
Allocates `etl::ireference_counted_message` types that are used by `etl::shared_message`.
|
||||
Uses a supplied `memory_block allocator` derived from `etl::imemory_block_allocator`.
|
||||
|
||||
## ireference_counted_message_pool.h
|
||||
Defines the following class.
|
||||
`etl::ireference_counted_message_pool`
|
||||
|
||||
## reference_counted_message_pool.h
|
||||
Defines the following classes.
|
||||
`etl::reference_counted_message_pool_exception`
|
||||
`etl::reference_counted_message_pool_allocation_failure`
|
||||
`etl::reference_counted_message_pool_release_failure`
|
||||
|
||||
|
||||
## ireference_counted_message_pool
|
||||
|
||||
```cpp
|
||||
etl::ireference_counted_message_pool
|
||||
```
|
||||
|
||||
The interface for reference counted message pools.
|
||||
```cpp
|
||||
virtual ~ireference_counted_message_pool() {}
|
||||
```
|
||||
```cpp
|
||||
virtual void release(const etl::ipool_message& msg) = 0;
|
||||
```
|
||||
|
||||
Virtual `lock()` and `unlock()` functions are defined. The default action is to do nothing.
|
||||
A derived class may override these functions to provide a thread or interrupt safe pool.
|
||||
`virtual void lock()`
|
||||
`virtual void unlock()`
|
||||
|
||||
## reference_counted_message_pool
|
||||
|
||||
```cpp
|
||||
etl::reference_counted_message_pool<TCounter>
|
||||
```
|
||||
The concrete reference counted message pool.
|
||||
|
||||
```cpp
|
||||
reference_counted_message_pool(imemory_block_allocator& memory_block_allocator)
|
||||
```
|
||||
Constructs the pool and assigns the memory block allocator to it.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
template <typename TMessage>
|
||||
etl::reference_counted_message<TMessage, TCounter>* allocate()
|
||||
```
|
||||
Returns a pointer to a pool message that holds a `TMessage`.
|
||||
The message is default constructed.
|
||||
ETL_ASSERT if one cannot be allocated and returns `ETL_NULLPTR`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
template <typename TMessage>
|
||||
etl::reference_counted_message<TMessage, TCounter>* allocate(const TMessage& message)
|
||||
```
|
||||
Returns a pointer to a pool message that holds a `TMessage`.
|
||||
ETL_ASSERT if one cannot be allocated and returns `ETL_NULLPTR`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void release(const etl::ireference_counted_message& rcmessage)
|
||||
```
|
||||
Returns the reference counted to a pool message that holds a `TMessage`.
|
||||
`ETL_ASSERT` if it cannot be released. Reasons can include the message not belonging to the pool.
|
||||
|
||||
## pool_message_parameters
|
||||
|
||||
**C++03**
|
||||
The C++03 version defines the largest size and alignment of up to 8 types at a time.
|
||||
|
||||
```cpp
|
||||
template <typename TMessage1, typename TMessage2 = TMessage1,
|
||||
typename TMessage3 = TMessage1, typename TMessage4 = TMessage1,
|
||||
typename TMessage5 = TMessage1, typename TMessage6 = TMessage1,
|
||||
typename TMessage7 = TMessage1, typename TMessage8 = TMessage1>
|
||||
struct pool_message_parameters
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
static const size_t max_size;
|
||||
```
|
||||
The maximum size.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
static const size_t max_alignment;
|
||||
```
|
||||
The maximum alignment.
|
||||
|
||||
**C++11 or above**
|
||||
The C++11 version defines the largest size and alignment of a set of message types.
|
||||
|
||||
```cpp
|
||||
template <typename TMessage1, typename... TMessages>
|
||||
struct pool_message_parameters
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
static constexpr size_t max_size
|
||||
```
|
||||
The maximum size.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
static constexpr size_t max_alignment;
|
||||
```
|
||||
The maximum alignment.
|
||||
|
||||
---
|
||||
|
||||
**For C++11, with atomic support.**
|
||||
|
||||
```cpp
|
||||
template <typename TObject>
|
||||
using atomic_counted_message_pool = etl::reference_counted_message_pool<etl::atomic_int32_t>;
|
||||
```
|
||||
Defines an alias to a reference counted message pool that uses an atomic.
|
||||
@ -1,197 +0,0 @@
|
||||
---
|
||||
title: "reference_counted_message"
|
||||
---
|
||||
|
||||
{{< callout type="info">}}
|
||||
Header: `reference_counted_message.h`
|
||||
{{< /callout >}}
|
||||
|
||||
Reference counted message types that are used by `etl::shared_message`.
|
||||
|
||||
**Defines the following classes**
|
||||
|
||||
```cpp
|
||||
etl::ireference_counted_message
|
||||
```
|
||||
The interface of all reference counted message types.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
etl::reference_counted_message<typename TMessage, typename TCounter>
|
||||
```
|
||||
Derived from `etl::ireference_counted_message`.
|
||||
|
||||
```cpp
|
||||
etl::persistent_message<typename TMessage>
|
||||
```
|
||||
Derived from `etl::ireference_counted_message`.
|
||||
|
||||
## ireference_counted_message
|
||||
|
||||
```cpp
|
||||
etl::ireference_counted_message
|
||||
```
|
||||
The interface of all reference counted message types.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
virtual ~ireference_counted_message()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD virtual etl::imessage& get_message() = 0;
|
||||
```
|
||||
Get a reference to the message.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD virtual const etl::imessage& get_message() const = 0;
|
||||
```
|
||||
Get a const reference to the message.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD virtual etl::ireference_counter& get_reference_counter() = 0;
|
||||
```
|
||||
Get a reference to the reference counter.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD virtual const etl::ireference_counter& get_reference_counter() const = 0;
|
||||
```
|
||||
Get a const reference to the reference counter.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
virtual void release() = 0;
|
||||
```
|
||||
Release back to the owner.
|
||||
|
||||
## reference_counted_message
|
||||
|
||||
```cpp
|
||||
etl::reference_counted_message<typename TMessage, typename TCounter>
|
||||
```
|
||||
The implementation of reference counted messages owned by a pool.
|
||||
Will static assert if TMessage is no derived from etl::imessage.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
reference_counted_message(const TMessage& message, etl::ireference_counted_message_pool& owner)
|
||||
```
|
||||
Constructs from a message and the pool from which the reference counted message is allocated.
|
||||
The message is copied.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
reference_counted_message(etl::ireference_counted_message_pool& owner)
|
||||
```
|
||||
Constructs from a message and the pool from which the reference counted message is allocated.
|
||||
The message is default constructed.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD TMessage& get_message() ETL_OVERRIDE
|
||||
```
|
||||
Get a reference to the message.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD const TMessage& get_message() const ETL_OVERRIDE
|
||||
```
|
||||
Get a const reference to the message.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD etl::ireference_counter& get_reference_counter() ETL_OVERRIDE
|
||||
```
|
||||
Get a reference to the reference counter.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD const etl::ireference_counter& get_reference_counter() const ETL_OVERRIDE
|
||||
```
|
||||
Get a const reference to the reference counter.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void release() ETL_OVERRIDE
|
||||
```
|
||||
Release back to the owner pool.
|
||||
|
||||
## persistent_message
|
||||
|
||||
```cpp
|
||||
etl::persistent_message<typename TMessage>
|
||||
```
|
||||
|
||||
The implementation of reference counted messages not owned by a pool.
|
||||
It's counter type is `void`.
|
||||
Will static assert if `TMessage` is not derived from `etl::imessage`.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
persistent_message(const TMessage& message)
|
||||
```
|
||||
Constructs from a message.
|
||||
The message is copied.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD TMessage& get_message() ETL_OVERRIDE
|
||||
```
|
||||
Get a reference to the message.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD const TMessage& get_message() const ETL_OVERRIDE
|
||||
```
|
||||
Get a const reference to the message.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD etl::ireference_counter& get_reference_counter() ETL_OVERRIDE
|
||||
```
|
||||
Get a reference to the reference counter.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD const etl::ireference_counter& get_reference_counter() const ETL_OVERRIDE
|
||||
```
|
||||
Get a const reference to the reference counter.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
void release() ETL_OVERRIDE
|
||||
```
|
||||
Does nothing for a persistent message.
|
||||
|
||||
## For C++11, with atomic support.
|
||||
|
||||
```cpp
|
||||
template <typename TMessage>
|
||||
using atomic_counted_message = etl::reference_counted_message<TMessage, etl::atomic_int32_t>;
|
||||
```
|
||||
Defines an alias to a reference counted message that uses an atomic.
|
||||
|
||||
@ -1,79 +0,0 @@
|
||||
---
|
||||
title: "shared_message"
|
||||
weight: 2
|
||||
---
|
||||
|
||||
{{< callout type="info">}}
|
||||
Header: `shared_message.h`
|
||||
{{< /callout >}}
|
||||
|
||||
Shared Messages
|
||||
|
||||
The type used to encapsulate reference counted messages.
|
||||
Shared messages are usually passed by value.
|
||||
|
||||
See the Shared Message Tutorial
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
template <typename TPool, typename TMessage>
|
||||
shared_message(TPool& owner, const TMessage& message)
|
||||
```
|
||||
Static asserts if `TPool` is not derived from `etl::ireference_counted_message_pool`
|
||||
Static asserts if `TMessage` not derived from `etl::imessage`.
|
||||
|
||||
Requires that `TPool` implements the following member function to allocate from the pool.
|
||||
|
||||
```cpp
|
||||
template <typename TMessage>
|
||||
etl::ireference_counted_message* allocate(const TMessage& message)
|
||||
```
|
||||
---
|
||||
|
||||
```cpp
|
||||
explicit shared_message(etl::ireference_coutnted_message& message)
|
||||
```
|
||||
Construct from a reference counted message.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
shared_message(const etl::shared_message& other)
|
||||
```
|
||||
Copy constructor.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
shared_message& operator =(const etl::shared_message& other)
|
||||
```
|
||||
Assignment operator.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
~shared_message()
|
||||
```
|
||||
Destructor.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD etl::imessage& get_message()
|
||||
```
|
||||
Gets a reference to the contained message.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD const etl::imessage& get_message() const
|
||||
```
|
||||
Gets a const reference to the contained message.
|
||||
|
||||
---
|
||||
|
||||
```cpp
|
||||
ETL_NODISCARD uint32_t get_reference_count() const
|
||||
```
|
||||
Gets the current reference count for this shared message.
|
||||
Loading…
x
Reference in New Issue
Block a user