From b8c59905858fd88e7b234642b1d404f5e736daec Mon Sep 17 00:00:00 2001 From: John Wellbelove Date: Thu, 28 May 2026 14:27:15 +0100 Subject: [PATCH] Updates to message framework documentation --- docs/Messaging/_index.md | 19 +++++++++++++++++++ docs/Messaging/images/message-framework.png | Bin 0 -> 8529 bytes docs/Messaging/message-broker.md | 1 + docs/Messaging/message-bus.md | 1 + docs/Messaging/message-router-registry.md | 1 + docs/Messaging/message-router.md | 2 +- docs/Messaging/{messages.md => message.md} | 3 ++- docs/Messaging/shared-message.md | 1 + docs/blog/graphics/dot-and-cross-products.md | 5 +++-- 9 files changed, 29 insertions(+), 4 deletions(-) create mode 100644 docs/Messaging/images/message-framework.png rename docs/Messaging/{messages.md => message.md} (98%) diff --git a/docs/Messaging/_index.md b/docs/Messaging/_index.md index 6bfb61be..5344a178 100644 --- a/docs/Messaging/_index.md +++ b/docs/Messaging/_index.md @@ -2,3 +2,22 @@ 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` 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 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 + +![message-framework](images/message-framework.png) diff --git a/docs/Messaging/images/message-framework.png b/docs/Messaging/images/message-framework.png new file mode 100644 index 0000000000000000000000000000000000000000..a4b8a42443b4f76ba717ca9a36619dd9adf731d1 GIT binary patch literal 8529 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 literal 0 HcmV?d00001 diff --git a/docs/Messaging/message-broker.md b/docs/Messaging/message-broker.md index f37a89ae..ffc5df6d 100644 --- a/docs/Messaging/message-broker.md +++ b/docs/Messaging/message-broker.md @@ -1,5 +1,6 @@ --- title: "message_broker" +weight: 6 --- {{< callout type="info">}} diff --git a/docs/Messaging/message-bus.md b/docs/Messaging/message-bus.md index ad88030d..5e63eef8 100644 --- a/docs/Messaging/message-bus.md +++ b/docs/Messaging/message-bus.md @@ -1,5 +1,6 @@ --- title: "message_bus" +weight: 5 --- {{< callout type="info">}} diff --git a/docs/Messaging/message-router-registry.md b/docs/Messaging/message-router-registry.md index 79c09fb9..cfd21d1d 100644 --- a/docs/Messaging/message-router-registry.md +++ b/docs/Messaging/message-router-registry.md @@ -1,5 +1,6 @@ --- title: "message_router_registry" +weight: 4 --- {{< callout type="info">}} diff --git a/docs/Messaging/message-router.md b/docs/Messaging/message-router.md index 89d2a91b..7b2c14a2 100644 --- a/docs/Messaging/message-router.md +++ b/docs/Messaging/message-router.md @@ -1,5 +1,6 @@ --- title: message_router +weight: 3 --- A class that will automatically route incoming messages to specific handlers based on the message types declared in the template parameter list. Messages are passed to the receive member function which will static cast it to its real type and call the matching on_receive function in the derived class. A compilation error will occur if the matching on_receive does not exist. @@ -16,7 +17,6 @@ etl::null_message_router Note: This C++03 portion of this header is a generated from `message_router_generator.h`. To handle more than the standard 16 message types then a new one must be generated. See [Generators](./generators-tutorial) - ## Message router ID Allowable router IDs run from `0` to `MAX_MESSAGE_ROUTER` (`249`) inclusive. diff --git a/docs/Messaging/messages.md b/docs/Messaging/message.md similarity index 98% rename from docs/Messaging/messages.md rename to docs/Messaging/message.md index 2a49e91e..5f6efa95 100644 --- a/docs/Messaging/messages.md +++ b/docs/Messaging/message.md @@ -1,5 +1,6 @@ --- -title: "Messages" +title: "message" +weight: 1 --- {{< callout type="info">}} diff --git a/docs/Messaging/shared-message.md b/docs/Messaging/shared-message.md index 8e190308..79ea8a74 100644 --- a/docs/Messaging/shared-message.md +++ b/docs/Messaging/shared-message.md @@ -1,5 +1,6 @@ --- title: "shared_message" +weight: 2 --- {{< callout type="info">}} diff --git a/docs/blog/graphics/dot-and-cross-products.md b/docs/blog/graphics/dot-and-cross-products.md index eaa9ad60..cafcd89d 100644 --- a/docs/blog/graphics/dot-and-cross-products.md +++ b/docs/blog/graphics/dot-and-cross-products.md @@ -11,8 +11,8 @@ If `A` & `B` are vectors, the dot product is `|A||B|cos(θ)`, where `θ` is the `|A|` is the length of the vector `A`. `|B|` is the length of the vector `B`. -Therefore, we can calculate `Cos(θ) = (A ⋅ B)/(|A||B|)`. -A dot product of `0` indicates two perpendicular lines, and that the dot product is greatest when the lines are parallel. +Therefore, we can calculate `cos(θ) = (A ⋅ B)/(|A||B|)`. +A dot product of `0` indicates two perpendicular lines, and the dot product is greatest when the lines are parallel. ## Cross Product @@ -20,3 +20,4 @@ The cross product of vectors `(x1, y1)` and `(x2, y2)` is `x1 * y2 - y1 * x2` If `A` & `B` are vectors, the cross product is `|A||B|sin(θ)`. `|θ|` is the angle between the two vectors, but `θ` can be positive or negative. +Therefore, we can calculate `sin(θ) = (A x B)/(|A||B|)`. \ No newline at end of file