backmp11: Make enqueuing events explicit

[chandryan]

Problem statement

In process_event events are enqueued automatically, if the machine is already processing events.

This condition has to be evaluated at runtime, which forces the compiler to instantiate an enqueue_event method for every event the state machine receives via process_event. In practice this method is usually only needed for a small subset of events, when a state machine posts an event to itself within an action. Thus most template instantiations are redundant and will never get called.

Change

Removing the automatic enqueuing eliminates the redundant template instantiations. If process_event is called while the state machine is processing an event, let it reject it and return HANDLED_FALSE. The template instance for enqueuing an event is then only instantiated if enqueue_event is called explicitly.

Impact

Branch with code changes to evaluate the impact: https://github.com/chandryan/msm/tree/feat/backmp11-strict-process_event-api

Pros:

• The API of process_event behaves identically with and without an event pool
• Lower executable size: A hierarchical SM benchmark shows a reduction of ~24% (from 145kB to 110kB)
• Faster compile time: A hierarchical SM benchmark shows a reduction of ~22% (9s to 7s)

Cons:

This imposes a breaking change that requires adaptations in the user code. Calls to process_event in actions have to be replaced with enqueue_event.

The benefits are sufficient to apply this change. Replacing calls to process_event with enqueue_event is simple and straightforward.
Also, if wanted, the automatic enqueuing can be implemented in user code by inheriting from state_machine and implementing a custom version of process_event (like the state machine adapter in the evaluation branch does).

Especially while backmp11 is still experimental breaking changes are acceptable.
However, this change should still come with a deprecation notice and a grace period of one release to give users time to adjust.

[chandryan]

New improvement potential after the optimization witih the flat_fold dispatch strategy (#180), again measured with the hierarchical SM benchmark:

• Lower executable size: ~39% (from 85kB to 52kB)
• Faster compile time: ~13% (from 8s to 6.6s)

[auzn88]

This imposes a breaking change that requires adaptations in the user code. Calls to process_event in actions have to be replaced with enqueue_event.

The benefits are sufficient to apply this change. Replacing calls to process_event with enqueue_event is simple and straightforward.

I am a bit lost as to replacing process_event() with enqueue_event() inside actions. I suppose it is not just a simple replacement, but I have to call execute_enqueued_events() somewhere, maybe right after enqueue_event(), right?

[chandryan]

I am a bit lost as to replacing process_event() with enqueue_event() inside actions. I suppose it is not just a simple replacement, but I have to call execute_enqueued_events() somewhere, maybe right after enqueue_event(), right?

It should just be a simple replacement, and there should be no impact on the behavior.
The current implementation (in all back-ends) is as follows:
If you call process_event() while the state machine is processing (which is always the case if you call it in an action), MSM enqueues the event internally for later processing. It automatically processes it from the queue as soon as the current processing step, from which your action has been called, is finished.
Thus the behavior of calling process_event() within an action is the same as calling enqueue_event().

Calling execute_queued_events() (or the new API name process_event_pool() in backmp11) is not required in this case. It would be required, for example, if you called enqueue_event() while the state machine is not processing, and you want to explicitly trigger your state machine to process the queued event(s) at a later point in time.

When queued events get processed:
The event queue in the older back-ends, or event pool in backmp11, always gets processed immediately after a call to process_event(). This means even if you never called execute_queued_events(), your queued events would still be processed - shortly after the next time you call process_event().