vex_rt/macros/
state_machine.rs

1#[macro_export]
2/// Creates an asynchronous state machine with the given visibility, name and
3/// state definitions.
4///
5/// # Usage
6/// The syntax consists of a state machine definition followed by one or more
7/// state definitions. The state machine definition has the syntax:
8/// ```text
9/// <visibility> <TypeName>(<generics>)? (<parenthesized_parameter_list>)? ({
10///     (<field_definition> = <initializer>),*
11/// })? = <initial_state>;
12/// ```
13///
14/// Here, `<visibility>` is one of the standard visibility modes (which may be
15/// empty for private visibility); `<TypeName>` is the identifier that will name
16/// the type for the state machine; `<generics>` is an angle-bracketed list of
17/// lifetime and generic arguments; `<parenthesized_parameter_list>` is
18/// precisely that, for the purpose of constructing instances of the state
19/// machine; `<field_definition>` is a named field definition, as in a
20/// definition of a `struct`; `<initializer>` is an expression which computes a
21/// value of the field type from the parameters (which are all in scope); and
22/// `<initial state>` is the name of a state (see below), followed by a
23/// parenthesized argument list (for which the parameters are in scope) if the
24/// state has any parameters.
25///
26/// Each state definition has the syntax:
27/// ```text
28/// <name>(<ctx> (, (<param>),*)?) ([(<field_pat>),*])? (-> <return_type>)? {
29///     <body>
30/// }
31/// ```
32///
33/// Here, `<name>` is the name of the state (which should be in `snake_case`);
34/// `<ctx>` is the name for a parameter which will be passed the
35/// [`Context`](crate::rtos::Context) for the state execution; each `<param>` is
36/// a parameter definition, as in a function signature; each `<field_pat>` is a
37/// field pattern for destructuring a `struct` containing the fields defined in
38/// the state machine definition; `<return_type>` is the return type, which is
39/// `()` if omitted, as with ordinary functions; and `<body>` is the function
40/// body which implements the state behaviour, for which the state parameters
41/// and field patterns are in scope.
42///
43/// The macro generates two types with the configured `<visibility>`: a `struct
44/// <TypeName>`, an instance of which is an actual state machine, and an `enum
45/// <TypeName>State`, a value of which is a possible state of the state machine
46/// (including arguments).
47///
48/// The state machine `struct` is given a method `new` with the parameters from
49/// the state machine definition, as well as a method for each state, taking a
50/// [`Context`](crate::rtos::Context) as well as the parameters of that state.
51/// The `new` method constructs a new state machine according to the field
52/// initializers and initial state given in the definition, while the state
53/// methods transition an existing state machine to the given state. An
54/// implementation of the [`StateMachine`](crate::machine::StateMachine) trait
55/// is also provided for the `struct`.
56macro_rules! state_machine {
57    ($($args:tt)*) => {
58        $crate::macros::make_state_machine!($crate; $($args)*);
59    };
60}
vex_rt/macros/state_machine.rs

vex_rt/macros/
state_machine.rs
