From 48ec571c9ed5a81260dbaf136ccf5f25754fe127 Mon Sep 17 00:00:00 2001 From: John Wellbelove Date: Sun, 26 Apr 2026 10:22:37 +0200 Subject: [PATCH] Added more documentation Moced some documentation files to new directories --- docs/Messaging/reference-counted-messages.md | 197 ++++++++ .../callback-service.md | 0 docs/callbacks/delegate-service.md | 93 ++++ .../signal.txt => callbacks/signal.md} | 244 ++++++---- docs/multi-tasking/_index.md | 4 + .../cooperative-scheduler.md | 0 docs/{frameworks => multi-tasking}/task.md | 0 docs/raw/frameworks/Delegate Service.txt | 58 --- .../frameworks/Reference Counted Messages.txt | 102 ----- docs/raw/frameworks/State Chart.txt | 310 ------------- docs/state machines/_index.md | 4 + .../finite-state-machine.md | 0 docs/{frameworks => state machines}/hfsm.png | Bin .../hierarchical-finite-state-machine.md | 0 docs/state machines/state-chart.md | 433 ++++++++++++++++++ docs/{frameworks => timers}/_index.md | 2 +- 16 files changed, 889 insertions(+), 558 deletions(-) create mode 100644 docs/Messaging/reference-counted-messages.md rename docs/{frameworks => callbacks}/callback-service.md (100%) create mode 100644 docs/callbacks/delegate-service.md rename docs/{raw/frameworks/signal.txt => callbacks/signal.md} (58%) create mode 100644 docs/multi-tasking/_index.md rename docs/{frameworks => multi-tasking}/cooperative-scheduler.md (100%) rename docs/{frameworks => multi-tasking}/task.md (100%) delete mode 100644 docs/raw/frameworks/Delegate Service.txt delete mode 100644 docs/raw/frameworks/Reference Counted Messages.txt delete mode 100644 docs/raw/frameworks/State Chart.txt create mode 100644 docs/state machines/_index.md rename docs/{frameworks => state machines}/finite-state-machine.md (100%) rename docs/{frameworks => state machines}/hfsm.png (100%) rename docs/{frameworks => state machines}/hierarchical-finite-state-machine.md (100%) create mode 100644 docs/state machines/state-chart.md rename docs/{frameworks => timers}/_index.md (50%) diff --git a/docs/Messaging/reference-counted-messages.md b/docs/Messaging/reference-counted-messages.md new file mode 100644 index 00000000..8e8bd728 --- /dev/null +++ b/docs/Messaging/reference-counted-messages.md @@ -0,0 +1,197 @@ +--- +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 +``` +Derived from `etl::ireference_counted_message`. + +```cpp +etl::persistent_message +``` +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 +``` +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 +``` + +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 +using atomic_counted_message = etl::reference_counted_message; +``` +Defines an alias to a reference counted message that uses an atomic. + diff --git a/docs/frameworks/callback-service.md b/docs/callbacks/callback-service.md similarity index 100% rename from docs/frameworks/callback-service.md rename to docs/callbacks/callback-service.md diff --git a/docs/callbacks/delegate-service.md b/docs/callbacks/delegate-service.md new file mode 100644 index 00000000..c7498744 --- /dev/null +++ b/docs/callbacks/delegate-service.md @@ -0,0 +1,93 @@ +--- +title: "delegate_service" +--- + +{{< callout type="info">}} + Header: `delegate_service.h` +{{< /callout >}} + +Delegate Service +This template class allows easier integration of 'C' style events (such as interrupt vectors) and C++ handlers. +It can allow abstraction between low level events such as interrupts and their application dependent handlers. +The handlers may be any combination of global, static, member functions, lambdas and functors. +It utilises the templated function wrapper. + +The delegate callbacks are identified by an id. The values of the ids must range from zero or a specified offset, up to the maximum range of specified delegates. Calling an unused delegate id will either do nothing or, if the user has specified a handler, call this with the id of the delegate. + +There are functions that use both runtime and compile time checks of the delegate id. +Compile time is preferable. + +--- + +```cpp +template * Delegates = nullptr> +delegate_service +``` +`Range` +The id range of the delegates (last - first + 1). + +`Offset` +The starting id for the range. Default `0`. + +`Delegates` +An optional pointer to an array of delegate pointers. + +If the pointer to a delegate array is supplied as a template parameter then the delegate service may be declared `constexpr`, otherwise the service is runtime only. + +## Member functions + +```cpp +delegate_service() +``` +Runtime only. +Sets all of the delegates to route to the unhandled delegate. +Sets the unhandled delegate to default (do nothing). + +--- + +```cpp +template +void register_delegate(etl::delegate& callback) +``` +Runtime only. +Registers delegate with the id specified in the template parameter. +A compile time error will occur if the id is out of range. + +--- + +```cpp +void register_delegate(size_t id, etl::delegate& callback) +``` +Runtime only. +Registers delegate with the id specified in the template parameter. +The registration will be ignored if the id is out of range. + +--- + +```cpp +void register_unhandled_delegate(etl::delegate& callback) +``` +Runtime only. +Registers the delegate to be used for unhandled ids. + +--- + +```cpp +template +void call() +``` +Calls the delegate associated with the id. +Calls the unhandled delegate if the id has not been registered. +A compile time error will occur if the id is out of range. + +--- + +```cpp +void call(const size_t id) +``` +Calls the delegate associated with the id. +Calls the unhandled delegate if the id has not been registered or if is out of range. + +## Example + +See the example project in `examples\FunctionInterruptSimulation-Delegates`. diff --git a/docs/raw/frameworks/signal.txt b/docs/callbacks/signal.md similarity index 58% rename from docs/raw/frameworks/signal.txt rename to docs/callbacks/signal.md index b9a2cb37..2046e892 100644 --- a/docs/raw/frameworks/signal.txt +++ b/docs/callbacks/signal.md @@ -1,96 +1,152 @@ -signal -20.44.0 +--- +title: "signal" +--- -A class that implements simple signal/slot framework. -Uses etl::delegate as the default slot type, though other types may be used. +{{< callout type="info">}} + Header: `signal.h` + Since: `20.44.0` +{{< /callout >}} +A class that implements simple signal/slot framework. +Uses `etl::delegate` as the default slot type, though other types may be used. + +```cpp template > class signal -TFunction The callback function signature. -Size The maximum numbr of slots for the signal. -TSlot The callback slot type. Default = etl::delegate -____________________________________________________________________________________________________ -Types +``` +`TFunction` The callback function signature. +`Size` The maximum numbr of slots for the signal. +`TSlot` The callback slot type. Default = `etl::delegate` -slot_type Defined as the slot type. -size_type The size type used internally. -span_type The span type used in the connect API. -____________________________________________________________________________________________________ -Constructors +## Types +`slot_type` Defined as the slot type. +`size_type` The size type used internally. +`span_type` The span type used in the connect API. +## Constructors +```cpp template ETL_CONSTEXPR14 explicit signal(TSlots&&... slots) ETL_NOEXCEPT -Construct the signal from a variadic list of slots. -Can be used as a constexpr constructor. -Static asserts if any of the -____________________________________________________________________________________________________ -Connect +``` +Construct the signal from a variadic list of slots. +Can be used as a `constexpr` constructor. +Static asserts if any of the slots are not `slot_type`. +Static asserts if the number of slots exceeds capacity. +## Connect +```cpp bool connect(const slot_type& slot) -Connects the slot, if not already connected and returns true. -If the signal is full, ETL_ASSERTs etl::signal_full and returns false. -____________________________________________________________________________________________________ +``` +Connects the slot, if not already connected and returns `true`. +If the signal is full, asserts `etl::signal_full` and returns `false`. + +--- + +```cpp bool connect(std::initializer_list slots) -Connects all of the slots and returns true. -If the number of slots exceeds the signal's max size, asserts an etl::signal_full and returns false. -Enabled if ETL_HAS_INITIALIZER_LIST and ETL_USING_CPP17 are defined as 1. -____________________________________________________________________________________________________ +``` +Connects all of the slots and returns `true`. +If the number of slots exceeds the signal's max size, asserts an `etl::signal_full` and returns `false`. +Enabled if `ETL_HAS_INITIALIZER_LIST` and `ETL_USING_CPP17` are defined as `1`. + +--- + +```cpp bool connect(const span_type slots) -Connects all of the slots and returns true. -If the number of slots exceeds the signal's max size, asserts an etl::signal_full and returns false. -____________________________________________________________________________________________________ -Disconnect +``` +Connects all of the slots and returns `true`. +If the number of slots exceeds the signal's max size, asserts an `etl::signal_full` and returns `false`. +## Disconnect + +```cpp void disconnect(const slot_type& slot) ETL_NOEXCEPT -Disconnects slot from the signal. -If the signal does not contain the slot. there is no error. -____________________________________________________________________________________________________ -void disconnect(std::initializer_list slots) ETL_NOEXCEPT -Disconnects all of the slots from the signal. -If the signal does not contain a particular slot, there is no error. -Enabled if ETL_HAS_INITIALIZER_LIST and ETL_USING_CPP17 are defined as 1. -____________________________________________________________________________________________________ -void disconnect(const span_type slots) ETL_NOEXCEPT -Disconnects all of the slots from the signal. -If the signal does not contain a particular slot, there is no error. -____________________________________________________________________________________________________ -void disconnect_all() ETL_NOEXCEPT -Disconnects all slots from the signal. -____________________________________________________________________________________________________ -Status - -ETL_CONSTEXPR14 bool connected(const slot_type& slot) const ETL_NOEXCEPT -Checks if a slot is connected to the signal. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 bool empty() const ETL_NOEXCEPT -Return true if the signal has no slots connected. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 bool full() const ETL_NOEXCEPT -Return true if the signal has the maximum number of slots connected. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 size_type max_size() const ETL_NOEXCEPT -Returns the total number of slots that can be connected. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 size_type size() const ETL_NOEXCEPT -Returns the total slots currently connected. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 size_type available() const ETL_NOEXCEPT -Returns the total empty slots available. -____________________________________________________________________________________________________ -Call +``` +Disconnects slot from the signal. +If the signal does not contain the slot there is no error. +--- + +```cpp +void disconnect(std::initializer_list slots) ETL_NOEXCEPT +``` +Disconnects all of the slots from the signal. +If the signal does not contain a particular slot, there is no error. +Enabled if `ETL_HAS_INITIALIZER_LIST` and `ETL_USING_CPP17` are defined as `1`. + +--- + +```cpp +void disconnect(const span_type slots) ETL_NOEXCEPT +``` +Disconnects all of the slots from the signal. +If the signal does not contain a particular slot, there is no error. + +```cpp +void disconnect_all() ETL_NOEXCEPT +``` +Disconnects all slots from the signal. + +## Status + +```cpp +ETL_CONSTEXPR14 bool connected(const slot_type& slot) const ETL_NOEXCEPT +``` +Checks if a slot is connected to the signal. + +--- + +```cpp +ETL_CONSTEXPR14 bool empty() const ETL_NOEXCEPT +``` +Return `true` if the signal has no slots connected. + +--- + +```cpp +ETL_CONSTEXPR14 bool full() const ETL_NOEXCEPT +``` +Return `true` if the signal has the maximum number of slots connected. + +--- + +```cpp +ETL_CONSTEXPR14 size_type max_size() const ETL_NOEXCEPT +``` +Returns the total number of slots that can be connected. + +--- + +```cpp +ETL_CONSTEXPR14 size_type size() const ETL_NOEXCEPT +``` +Returns the total slots currently connected. + +--- + +```cpp +ETL_CONSTEXPR14 size_type available() const ETL_NOEXCEPT +``` +Returns the total empty slots available. + +## Call +```cpp template void operator()(TArgs&&... args) const ETL_NOEXCEPT +``` Function operator that calls each slot with the supplied parameters. -____________________________________________________________________________________________________ -Errors -etl::signal_full Indicates that an attempt to add a slot to a full signal occurred. +## Errors -Inherits from etl::signal_exception -____________________________________________________________________________________________________ -Examples +```cpp +etl::signal_full +``` +Indicates that an attempt to add a slot to a full signal occurred. +Inherits from `etl::signal_exception`. +## Examples + +```cpp constexpr size_t MaxSlots = 3; using callback_type = void(int a, int b); @@ -99,9 +155,11 @@ using slot_type = signal_type::slot_type; using span_type = signal_type::span_type; using not_slot_type = etl::delegate; -____________________________________________________________________________________________________ -Defining the slot functions +``` +**Defining the slot functions** + +```cpp void Function1(int a, int b) { std::cout << "Function1: " << a << "," << b << "\n"; @@ -116,7 +174,7 @@ void Function3(int a, int b) { std::cout << "Function3: " << a << "," << b << "\n"; } - +0 void Function4(int a, int b) { std::cout << "Function4: " << a << "," << b << "\n"; @@ -126,9 +184,11 @@ void Function5(int a) { std::cout << "Function5: " << a << "\n"; } -____________________________________________________________________________________________________ -Creating the slots +``` +**Creating the slots** + +```cpp constexpr slot_type MakeSlot1() noexcept { return slot_type::create(); @@ -153,9 +213,11 @@ constexpr not_slot_type MakeSlot5() noexcept { return not_slot_type::create(); } -____________________________________________________________________________________________________ -Defining the signal as constexpr +``` +**Define the signals as `constexpr`** + +```cpp // Define the signal and connect as constexpr constexpr signal_type({ MakeSlot1(), MakeSlot2(), MakeSlot3() }); @@ -166,9 +228,11 @@ constexpr signal_type({ MakeSlot1(), MakeSlot2(), MakeSlot3(), MakeSlot4() }); // Define the signal and connect as constexpr. // Static assert "All slots must be slot_type" constexpr signal_type({ MakeSlot1(), MakeSlot2(), MakeSlot5() }); -____________________________________________________________________________________________________ -Defining the signal at runtime +``` +**Defining the signal at runtime** + +```cpp // Define the signal. signal_type signal; @@ -183,9 +247,11 @@ signal.connect({ MakeSlot1(), MakeSlot2(), MakeSlot3() }); // Connect using span. const slot_type slot_list[] = { MakeSlot1(), MakeSlot2(), MakeSlot3() }; signal.connect(slot_list); -____________________________________________________________________________________________________ -Checking the status +``` +**Checking the status** + +```cpp // Define the signal. signal_type signal; @@ -243,15 +309,19 @@ signal.connected(MakeSlot2()) // Returns true signal.connected(MakeSlot3()) // Returns true signal.connect(MakeSlot4()); // ETL_ASSERT etl::signal_full. Returns false -____________________________________________________________________________________________________ -Calling the signal +``` +**Calling the signal** + +```cpp signal_type signal({ MakeSlot1(), MakeSlot2(), MakeSlot3() }); signal(1, 2); // Call all of the slots with the parameters 1 & 2 +``` -Output +**Output** +``` Function1: 1,2 Function2: 1,2 Function3: 1,2 - +``` diff --git a/docs/multi-tasking/_index.md b/docs/multi-tasking/_index.md new file mode 100644 index 00000000..7eadbd6f --- /dev/null +++ b/docs/multi-tasking/_index.md @@ -0,0 +1,4 @@ +--- +title: "Multi-Tasking" +weight: 100 +--- diff --git a/docs/frameworks/cooperative-scheduler.md b/docs/multi-tasking/cooperative-scheduler.md similarity index 100% rename from docs/frameworks/cooperative-scheduler.md rename to docs/multi-tasking/cooperative-scheduler.md diff --git a/docs/frameworks/task.md b/docs/multi-tasking/task.md similarity index 100% rename from docs/frameworks/task.md rename to docs/multi-tasking/task.md diff --git a/docs/raw/frameworks/Delegate Service.txt b/docs/raw/frameworks/Delegate Service.txt deleted file mode 100644 index 25b53106..00000000 --- a/docs/raw/frameworks/Delegate Service.txt +++ /dev/null @@ -1,58 +0,0 @@ -Delegate Service -This template class allows easier integration of 'C' style events (such as interrupt vectors) and C++ handlers. -It can allow abstraction between low level events such as interrupts and their application dependent handlers. -The handlers may be any combination of global, static, member functions, lambdas and functors. -It utilises the templated function wrapper. See here. - -The delegate callbacks are identified by an id. The values of the ids must range from zero or a specified offset, up to the maximum range of specified delegates. Calling an unused delegate id will either do nothing or, if the user has specified a handler, call this with the id of the delegate. - -There are functions that use both runtime and compile time checks of the delegate id. -Compile time is preferable. - -template * Delegates = nullptr> -etl::delegate_service - -Range The id range of the delegates (last - first + 1). -Offset The starting id for the range. Default 0. -Delegates An optional pointer to an array of delegate pointers. - -If the pointer to a delegate array is supplied as a template parameter then the delegate service may be declared constexpr, otherwise the service is runtime only. -____________________________________________________________________________________________________ -Member functions -____________________________________________________________________________________________________ -delegate_service() -Runtime only -Sets all of the delegates to route to the unhandled delegate. -Sets the unhandled delegate to default (do nothing). -____________________________________________________________________________________________________ -template -void register_delegate(etl::delegate& callback) -Runtime only -Registers delegate with the id specified in the template parameter. -A compile time error will occur if the id is out of range. -____________________________________________________________________________________________________ -void register_delegate(size_t id, etl::delegate& callback) -Runtime only -Registers delegate with the id specified in the template parameter. -The registration will be ignored if the id is out of range. -____________________________________________________________________________________________________ -void register_unhandled_delegate(etl::delegate& callback) -Runtime only -Registers the delegate to be used for unhandled ids. -____________________________________________________________________________________________________ -template -void call() -Calls the delegate associated with the id. -Calls the unhandled delegate if the id has not been registered. -A compile time error will occur if the id is out of range. -____________________________________________________________________________________________________ -void call(const size_t id) -Calls the delegate associated with the id. -Calls the unhandled delegate if the id has not been registered or if is out of range. -____________________________________________________________________________________________________ -Example - -Tutorial - -See the example project in etl\examples\FunctionInterruptSimulation-Delegates - diff --git a/docs/raw/frameworks/Reference Counted Messages.txt b/docs/raw/frameworks/Reference Counted Messages.txt deleted file mode 100644 index af9822ec..00000000 --- a/docs/raw/frameworks/Reference Counted Messages.txt +++ /dev/null @@ -1,102 +0,0 @@ -Reference Counted Messages - -Reference counted message types that are used by etl::shared_message. - -Defines the following classes. - -etl::ireference_counted_message -The interface of all reference counted message types. - -etl::reference_counted_message -Derived from etl::ireference_counted_message - -etl::persistent_message -Derived from etl::ireference_counted_message -____________________________________________________________________________________________________ -ireference_counted_message - -etl::ireference_counted_message -The interface of all reference counted message types. -____________________________________________________________________________________________________ -virtual ~ireference_counted_message() -____________________________________________________________________________________________________ -ETL_NODISCARD virtual etl::imessage& get_message() = 0; -Get a reference to the message. -____________________________________________________________________________________________________ -ETL_NODISCARD virtual const etl::imessage& get_message() const = 0; -Get a const reference to the message. -____________________________________________________________________________________________________ -ETL_NODISCARD virtual etl::ireference_counter& get_reference_counter() = 0; -Get a reference to the reference counter. -____________________________________________________________________________________________________ -ETL_NODISCARD virtual const etl::ireference_counter& get_reference_counter() const = 0; -Get a const reference to the reference counter. -____________________________________________________________________________________________________ -virtual void release() = 0; -Release back to the owner. -____________________________________________________________________________________________________ -reference_counted_message - -etl::reference_counted_message - -The implementation of reference counted messages owned by a pool. - -Will static assert if TMessage is no derived from etl::imessage. -____________________________________________________________________________________________________ -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. -____________________________________________________________________________________________________ -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. -____________________________________________________________________________________________________ -ETL_NODISCARD TMessage& get_message() ETL_OVERRIDE -Get a reference to the message. -____________________________________________________________________________________________________ -ETL_NODISCARD const TMessage& get_message() const ETL_OVERRIDE -Get a const reference to the message. -____________________________________________________________________________________________________ -ETL_NODISCARD etl::ireference_counter& get_reference_counter() ETL_OVERRIDE -Get a reference to the reference counter. -____________________________________________________________________________________________________ -ETL_NODISCARD const etl::ireference_counter& get_reference_counter() const ETL_OVERRIDE -Get a const reference to the reference counter. -____________________________________________________________________________________________________ -void release() ETL_OVERRIDE -Release back to the owner pool. -____________________________________________________________________________________________________ -persistent_message - -etl::persistent_message - -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. -____________________________________________________________________________________________________ -persistent_message(const TMessage& message) -Constructs from a message. -The message is copied. -____________________________________________________________________________________________________ -ETL_NODISCARD TMessage& get_message() ETL_OVERRIDE -Get a reference to the message. -____________________________________________________________________________________________________ -ETL_NODISCARD const TMessage& get_message() const ETL_OVERRIDE -Get a const reference to the message. -____________________________________________________________________________________________________ -ETL_NODISCARD etl::ireference_counter& get_reference_counter() ETL_OVERRIDE -Get a reference to the reference counter. -____________________________________________________________________________________________________ -ETL_NODISCARD const etl::ireference_counter& get_reference_counter() const ETL_OVERRIDE -Get a const reference to the reference counter. -____________________________________________________________________________________________________ -void release() ETL_OVERRIDE -Does nothing for a persistent message. -____________________________________________________________________________________________________ -For C++11, with atomic support. - -template -using atomic_counted_message = etl::reference_counted_message; -Defines an alias to a reference counted message that uses an atomic. - diff --git a/docs/raw/frameworks/State Chart.txt b/docs/raw/frameworks/State Chart.txt deleted file mode 100644 index 24727f18..00000000 --- a/docs/raw/frameworks/State Chart.txt +++ /dev/null @@ -1,310 +0,0 @@ -State Chart -A finite state machine driven by the reception of events. The incoming event will call the optional action based on a transition table. Optional on_entry and on_exit handlers can be declared in a state table. -An optional parameter may be sent to event handlers. - -This FSM is simpler, both in implementation and use, than the message based FSM class defined elsewhere in the ETL. See etl::fsm. - -Defines the following classes:- -etl::istate_chart -etl::state_chart -etl::state_chart - -TParameter defines how a data parameter will be passed to event handlers. -This may be by value, pointer, reference or const reference. -For C++11 or above, you may pass an rvalue reference. -____________________________________________________________________________________________________ -istate_chart 20.23.0 -The base for all state charts. - -Types -event_id_t -The type for event ids. - -state_id_t -The type for state ids. - -Member Functions -event_it_t get_state_id() const -Returns the id of the state. -____________________________________________________________________________________________________ -virtual void process_event(event_id_t event_id, TParameter data) = 0 -etl::state_chart will override this. -Processes the event message. -If a data parameter has been configured for etl::state_chart, then one will be default constructed. -____________________________________________________________________________________________________ -virtual void start(bool on_entry_initial = true) -Starts the state chart. -____________________________________________________________________________________________________ -istate_chart 20.23.0 -The base for all state charts. - -Types -event_id_t -The type for event ids. - -state_id_t -The type for state ids. - -Member Functions -event_it_t get_state_id() const -Returns the id of the state. -____________________________________________________________________________________________________ -virtual void process_event(event_id_t event_id) = 0 -etl::state_chart will override this. -Processes the event message. -If a data parameter has been configured for etl::state_chart, then one will be default constructed. -____________________________________________________________________________________________________ -virtual void start(bool on_entry_initial = true) -Starts the state chart. -____________________________________________________________________________________________________ -state_chart -For run-time defined transition and state tables. -A templated class. Inherits from etl::istate_chart or etl::istate_chart. - -Template parameters -TObject The object type that supplies actions, guards, on entry and on exit functionality. -TParameter The type that will be passed as a parameter (optional). -____________________________________________________________________________________________________ -Types - -TParameter parameter_t -____________________________________________________________________________________________________ -Constructor - -state_chart(TObject& object, - const transition* transition_table_begin, - const transition* transition_table_end, - const state* state_table_begin, - const state* state_table_end, - const state_id_t state_id) - -object -The instance of the that supplies actions, guards, on entry and on exit functionality. - -transition_table_begin -transition_table_end -The table of transitions, defining the relationship between events and state changes; defines option actions and guards. -Note: The transition table must have the same lifetime as the state chart. i.e. It must exist while the state chart exists. - -state_table_begin -state_table_end -Sets the optional state table defining any 'on entry' and 'on exit' for states. -Not all states have to have entries in the table. States with no 'on entry' and 'on_exit' functionality may be omitted. -Note: The state table must have the same lifetime as the state chart. i.e. It must exist while the state chart exists. - -state_id -The initial state id. -Note: The constructors do not call the 'on entry' function for the initial state -____________________________________________________________________________________________________ -state_chart_ct void parameter -state_chart_ctp non-void parameter -For compile-time defined transition and state tables. -A templated class. Inherits from etl::istate_chart or etl::istate_chart. - -Template parameters -TObject The object type that supplies actions, guards, on entry and on exit functionality. -TParameter The type that will be passed as a parameter (state_chart_ctp). -TObject_Ref A reference to the TObject instance. -Transition_Table_Begin A pointer to the start of the transition table. -Transition_Table_Size The number of elements in the transition table. -State_Table_Begin A pointer to the start of the state table. -State_Table_Size The number of elements in the transition table. -Initial_State The initial state. -____________________________________________________________________________________________________ -Types -TParameter parameter_t -____________________________________________________________________________________________________ -Constructor - -state_chart() -____________________________________________________________________________________________________ -Member Functions - -void start(bool on_entry_initial = true) -Starts the state chart. -if on_entry_initial is true and the initial state has an on_entry method, then this will be called. -The function does nothing after the first call. -____________________________________________________________________________________________________ -void process_event(event_id_t event_id) For void parameter. -Triggers the state chart with the event. -____________________________________________________________________________________________________ -void process_event(event_id_t event_id, parameter_t data) For non-void parameter. -Triggers the state chart with the event. -Passes the parameter to the event handler. -____________________________________________________________________________________________________ -TObject& get_object() -const TObject& get_object() const -Gets the implementation object instance. -____________________________________________________________________________________________________ -void set_transition_table(const transition* transition_table_begin, - const transition* transition_table_end) -Not defined for state_chart_ct or state_chart_ctp. -The table of transitions, defining the relationship between events and state changes; defines option actions and guards. -Note: The transition table must have the same scope as the state chart. i.e. It must exist while the state chart exists. -____________________________________________________________________________________________________ -void set_state_table(const state* state_table_begin, - const state* state_table_end) -Not defined for state_chart_ct or state_chart_ctp. -Sets the optional state table defining any on_entry and on_exit for states. -Not all states have to have entries in the table. States with no on_entry and on_exit functionality may be omitted. -Note: The state table must have the same scope as the state chart. i.e. It must exist while the state chart exists. -____________________________________________________________________________________________________ -Member Types - -transition -____________________________________________________________________________________________________ -For etl::state_chart -transition(const state_id_t current_state_id, - const event_id_t event_id, - const state_id_t next_state_id, - void (TObject::* const action)() = nullptr, - bool (TObject::* const guard)() = nullptr) - -transition(const event_id_t event_id, - const state_id_t next_state_id, - void (TObject::* const action)() = nullptr, - bool (TObject::* const guard)() = nullptr) -____________________________________________________________________________________________________ -For etl::state_chart -transition(const state_id_t current_state_id, - const event_id_t event_id, - const state_id_t next_state_id, - void (TObject::* const action)(data_parameter_type) = nullptr, - bool (TObject::* const guard)() = nullptr) - -transition(const event_id_t event_id, - const state_id_t next_state_id, - void (TObject::* const action)(data_parameter_type) = nullptr, - bool (TObject::* const guard)() = nullptr) - -current_state_id -The state id that the state chart must be in for the event to be processed. -If the second constructor form is used then the 'current state' is considered to be don't care. - -event_id -The event id for this transition. - -next_state_id -The state id that the state chart will be in after the event. - -action -An optional pointer to the action that will be called when the transition occurs. - -guard -An optional pointer to the guard for this transition. The transition will only occur if the guard returns true. -If the guard returns false then the scan of the transition table continues from the next position. -____________________________________________________________________________________________________ -state - -ETL_CONSTEXPR state(const state_id_t state_id_, - void (TObject::* const on_entry)() = ETL_NULLPTR, - void (TObject::* const on_exit)() = ETL_NULLPTR) - -state_id -The ID of the state. - -on_entry -An optional pointer to the function that will be called when a state is entered. - -on_exit -An optional pointer to the function that will be called when a state is entered. -___________________________________________________________________________________________________ -Example - -class MotorControl : public etl::state_chart -{ - void OnStart(); - void OnStop(); - void OnSetSpeed(); - bool StartGuard(); - - static const etl::array transitionTable; -}; - -const etl::array MotorControl::transitionTable = -{ - MotorControl::transition(IDLE, - START, - RUNNING, - &MotorControl::OnStart, - &MotorControl::StartGuard), - - MotorControl::transition(RUNNING, - STOP, - WINDING_DOWN, - &MotorControl::OnStop), - - MotorControl::transition(WINDING_DOWN, - STOPPED, - IDLE), - - MotorControl::transition(RUNNING, - EMERGENCY_STOP, - IDLE, - &MotorControl::OnStop), - - MotorControl::transition(RUNNING, - SET_SPEED, - RUNNING, - &MotorControl::OnSetSpeed) -}; -____________________________________________________________________________________________________ -state - -state(const state_id_t state_id, - void (TObject::* const on_entry)() = nullptr, - void (TObject::* const on_exit)() = nullptr) - -state_id -The id for this state. - -on_entry -An optional pointer to the function that will be called when the state chart enters the state. - -on_exit -An optional pointer to the function that will be called when the state chart exits the state. - -____________________________________________________________________________________________________ -Example - -class MotorControl : public etl::state_chart -{ - void OnExitIdle(); - void OnEnterStopped(); - void OnEnterRunning); - void OnExitRunning(); - - static const etl::array stateTable; -}; - -const etl::array MotorControl::stateTable = -{ - MotorControl::state(IDLE, nullptr, &MotorControl::OnExitIdle), - MotorControl::state(STOPPED, &MotorControl::OnEnterStopped, nullptr), - MotorControl::state(RUNNING, &MotorControl::OnEnterRunning, &MotorControl::OnExitRunning) -}; -____________________________________________________________________________________________________ -Notes -____________________________________________________________________________________________________ -Order of execution -When an event is processed, the execution occurs in the following order. -(Assuming all functions have been declared in the transition and state tables) - -A call to the guard function. -A call to the action function. -A call to the current state's exit function (if the transition changes the state). -A call to the next state's entry function (if the transition changes the state). -____________________________________________________________________________________________________ -Usage -The state chart may either used with inheritance or composition. - -class Implementation : public etl::state_chart - -class Implementation -{ - etl::state_chart stateChart; -}; - -Use inheritance when the implementation is a state machine. -Use composition if the implementation contains a state machine. - diff --git a/docs/state machines/_index.md b/docs/state machines/_index.md new file mode 100644 index 00000000..7a21283a --- /dev/null +++ b/docs/state machines/_index.md @@ -0,0 +1,4 @@ +--- +title: "State Machines" +weight: 100 +--- diff --git a/docs/frameworks/finite-state-machine.md b/docs/state machines/finite-state-machine.md similarity index 100% rename from docs/frameworks/finite-state-machine.md rename to docs/state machines/finite-state-machine.md diff --git a/docs/frameworks/hfsm.png b/docs/state machines/hfsm.png similarity index 100% rename from docs/frameworks/hfsm.png rename to docs/state machines/hfsm.png diff --git a/docs/frameworks/hierarchical-finite-state-machine.md b/docs/state machines/hierarchical-finite-state-machine.md similarity index 100% rename from docs/frameworks/hierarchical-finite-state-machine.md rename to docs/state machines/hierarchical-finite-state-machine.md diff --git a/docs/state machines/state-chart.md b/docs/state machines/state-chart.md new file mode 100644 index 00000000..afaf3f94 --- /dev/null +++ b/docs/state machines/state-chart.md @@ -0,0 +1,433 @@ +--- +title: "state_chart" +--- + +{{< callout type="info">}} + Header: `state_chart.h` +{{< /callout >}} + +State Chart +A finite state machine driven by the reception of events. The incoming event will call the optional action based on a transition table. Optional on_entry and on_exit handlers can be declared in a state table. +An optional parameter may be sent to event handlers. + +This FSM is simpler, both in implementation and use, than the message based FSM class defined elsewhere in the ETL. `See etl::fsm`. + +**Defines the following classes** +```cpp +etl::istate_chart +etl::state_chart +etl::state_chart +``` + +`TParameter` defines how a data parameter will be passed to event handlers. +This may be by value, pointer, reference or const reference. +For C++11 or above, you may pass an rvalue reference. + +--- + +```cpp +istate_chart +``` +The base for all state charts. +Since: `20.23.0` + +## Types +```cpp +event_id_t +``` +The type for event ids. + +--- + +```cpp +state_id_t +``` +The type for state ids. + +## Member Functions + +```cpp +event_it_t get_state_id() const +``` +Returns the id of the state. + +--- + +```cpp +virtual void process_event(event_id_t event_id, TParameter data) = 0 +``` +`etl::state_chart` will override this. +Processes the event message. +If a data parameter has been configured for `etl::state_chart`, then one will be default constructed. + +--- + +```cpp +virtual void start(bool on_entry_initial = true) +``` +Starts the state chart. + +--- + +```cpp +istate_chart +``` +The base for all state charts. +Since: `20.23.0` + +## Types +```cpp +event_id_t +``` +The type for event ids. + +--- + +```cpp +state_id_t +``` +The type for state ids. + +## Member Functions +```cpp +event_it_t get_state_id() const +``` +Returns the id of the state. + +--- + +```cpp +virtual void process_event(event_id_t event_id) = 0 +``` +`etl::state_chart` will override this. +Processes the event message. +If a data parameter has been configured for `etl::state_chart`, then one will be default constructed. + +--- + +```cpp +virtual void start(bool on_entry_initial = true) +``` +Starts the state chart. + +--- + +```cpp +state_chart +``` +For run-time defined transition and state tables. +Inherits from `etl::istate_chart` or `etl::istate_chart`. + +## Template parameters +`TObject` The object type that supplies actions, guards, on entry and on exit functionality. +`TParameter` The type that will be passed as a parameter (optional). + +## Types + +`TParameter` parameter_t + +## Constructor +```cpp +state_chart(TObject& object, + const transition* transition_table_begin, + const transition* transition_table_end, + const state* state_table_begin, + const state* state_table_end, + const state_id_t state_id) +``` +`object` +The instance of the that supplies actions, guards, on entry and on exit functionality. + +`transition_table_begin` +`transition_table_end` +The table of transitions, defining the relationship between events and state changes; defines option actions and guards. +Note: The transition table must have the same lifetime as the state chart. i.e. It must exist while the state chart exists. + +`state_table_begin` +`state_table_end` +Sets the optional state table defining any `on entry` and `on exit` for states. +Not all states have to have entries in the table. States with no 'on entry' and 'on_exit' functionality may be omitted. +Note: The state table must have the same lifetime as the state chart. i.e. It must exist while the state chart exists. + +`state_id` +The initial state id. +Note: The constructors do not call the `on entry` function for the initial state. + +`state_chart_ct` void parameter. +`state_chart_ctp` non-void parameter. + +--- + +**For compile-time defined transition and state tables.** +```cpp +A templated class. Inherits from `etl::istate_chart` or `etl::istate_chart`. +``` +`TObject` +The object type that supplies actions, guards, on entry and on exit functionality. + +`TParameter` +The type that will be passed as a parameter (state_chart_ctp). + +`TObject_Ref` +A reference to the TObject instance. + +`Transition_Table_Begin` +A pointer to the start of the transition table. + +`Transition_Table_Size` +The number of elements in the transition table. + +`State_Table_Begin` +A pointer to the start of the state table. + +`State_Table_Size` +The number of elements in the transition table. + +`Initial_State` +The initial state. + +## Types +```cpp +TParameter parameter_t +``` + +## Constructor + +```cpp +state_chart() +``` + +## Member Functions + +```cpp +void start(bool on_entry_initial = true) +``` +Starts the state chart. +if on_entry_initial is `true` and the initial state has an on_entry method, then this will be called. +The function does nothing after the first call. + +--- + +```cpp +void process_event(event_id_t event_id) +``` +Triggers the state chart with the event. +For `void` parameter. + +--- + +```cpp +void process_event(event_id_t event_id, parameter_t data) +``` +Triggers the state chart with the event. +Passes the parameter to the event handler. +For non-void parameter. + +--- + +```cpp +TObject& get_object() +const TObject& get_object() const +``` +Gets the implementation object instance. + +--- + +```cpp +void set_transition_table(const transition* transition_table_begin, + const transition* transition_table_end) +``` +Not defined for `state_chart_ct` or `state_chart_ctp`. +The table of transitions, defining the relationship between events and state changes; defines option actions and guards. +Note: The transition table must have the same scope as the state chart. i.e. It must exist while the state chart exists. + +--- + +```cpp +void set_state_table(const state* state_table_begin, + const state* state_table_end) +``` +Not defined for `state_chart_ct` or `state_chart_ctp`. +Sets the optional state table defining any on_entry and on_exit for states. +Not all states have to have entries in the table. States with no on_entry and on_exit functionality may be omitted. +Note: The state table must have the same scope as the state chart. i.e. It must exist while the state chart exists. + +## Member Types + +`transition` + +--- + +**For `etl::state_chart`** + +```cpp +transition(const state_id_t current_state_id, + const event_id_t event_id, + const state_id_t next_state_id, + void (TObject::* const action)() = nullptr, + bool (TObject::* const guard)() = nullptr) +``` + +```cpp +transition(const event_id_t event_id, + const state_id_t next_state_id, + void (TObject::* const action)() = nullptr, + bool (TObject::* const guard)() = nullptr) +``` + +--- + +**For etl::state_chart** +```cpp +transition(const state_id_t current_state_id, + const event_id_t event_id, + const state_id_t next_state_id, + void (TObject::* const action)(data_parameter_type) = nullptr, + bool (TObject::* const guard)() = nullptr) +``` + +--- + +```cpp +transition(const event_id_t event_id, + const state_id_t next_state_id, + void (TObject::* const action)(data_parameter_type) = nullptr, + bool (TObject::* const guard)() = nullptr) +``` +`current_state_id` +The state id that the state chart must be in for the event to be processed. +If the second constructor form is used then the 'current state' is considered to be don't care. + +`event_id` +The event id for this transition. + +`next_state_id` +The state id that the state chart will be in after the event. + +`action` +An optional pointer to the action that will be called when the transition occurs. + +`guard` +An optional pointer to the guard for this transition. The transition will only occur if the guard returns `true`. +If the guard returns `false` then the scan of the transition table continues from the next position. + +## state + +```cpp +ETL_CONSTEXPR state(const state_id_t state_id_, + void (TObject::* const on_entry)() = ETL_NULLPTR, + void (TObject::* const on_exit)() = ETL_NULLPTR) +``` +`state_id` +The ID of the state. + +`on_entry` +An optional pointer to the function that will be called when a state is entered. + +`on_exit` +An optional pointer to the function that will be called when a state is entered. + +## Example + +```cpp +class MotorControl : public etl::state_chart +{ + void OnStart(); + void OnStop(); + void OnSetSpeed(); + bool StartGuard(); + + static const etl::array transitionTable; +}; + +const etl::array MotorControl::transitionTable = +{ + MotorControl::transition(IDLE, + START, + RUNNING, + &MotorControl::OnStart, + &MotorControl::StartGuard), + + MotorControl::transition(RUNNING, + STOP, + WINDING_DOWN, + &MotorControl::OnStop), + + MotorControl::transition(WINDING_DOWN, + STOPPED, + IDLE), + + MotorControl::transition(RUNNING, + EMERGENCY_STOP, + IDLE, + &MotorControl::OnStop), + + MotorControl::transition(RUNNING, + SET_SPEED, + RUNNING, + &MotorControl::OnSetSpeed) +}; +``` + +## state + +```cpp +state(const state_id_t state_id, + void (TObject::* const on_entry)() = nullptr, + void (TObject::* const on_exit)() = nullptr) +``` +`state_id` +The id for this state. + +`on_entry` +An optional pointer to the function that will be called when the state chart enters the state. + +`on_exit` +An optional pointer to the function that will be called when the state chart exits the state. + +## Example + +```cpp +class MotorControl : public etl::state_chart +{ + void OnExitIdle(); + void OnEnterStopped(); + void OnEnterRunning); + void OnExitRunning(); + + static const etl::array stateTable; +}; + +const etl::array MotorControl::stateTable = +{ + MotorControl::state(IDLE, nullptr, &MotorControl::OnExitIdle), + MotorControl::state(STOPPED, &MotorControl::OnEnterStopped, nullptr), + MotorControl::state(RUNNING, &MotorControl::OnEnterRunning, &MotorControl::OnExitRunning) +}; +``` + +### Notes + +**Order of execution** +When an event is processed, the execution occurs in the following order. +(Assuming all functions have been declared in the transition and state tables) + +A call to the guard function. +A call to the action function. +A call to the current state's exit function (if the transition changes the state). +A call to the next state's entry function (if the transition changes the state). + +**Usage** +The state chart may either used with inheritance or composition. + +```cpp +class Implementation : public etl::state_chart + +class Implementation +{ + etl::state_chart stateChart; +}; +``` + +Use inheritance when the implementation is a state machine. +Use composition if the implementation contains a state machine. diff --git a/docs/frameworks/_index.md b/docs/timers/_index.md similarity index 50% rename from docs/frameworks/_index.md rename to docs/timers/_index.md index 5a85aae8..a386f58b 100644 --- a/docs/frameworks/_index.md +++ b/docs/timers/_index.md @@ -1,4 +1,4 @@ --- -title: "Frameworks" +title: "Timers" weight: 100 ---