Tutorial: A more robust door

So far, we have created the door state machine with two states (Open and Closed), but we don’t like the fact that the current implementation does not check if the door is already open or already closed when someone attempts to open/close it.

We want the implementation to report an error when such cases happen. For that, we will use custom event handlers.

We will also use this opportunity to simplify the diagnostics of the state machine by having the states themselves report when enter/leave them. For that we will use the OnEnter() method. OnEnter/OnLeave are optional, but when they are present, they get called during state transitions. For this example, we will omit the OnLeave method as we just want to report the new state.

#include <iostream>

#include <fsm/fsm.h>

using asap::fsm::ByDefault;
using asap::fsm::Continue;
using asap::fsm::DoNothing;
using asap::fsm::On;
using asap::fsm::StateMachine;
using asap::fsm::Status;
using asap::fsm::TransitionTo;
using asap::fsm::Will;

namespace {
struct OpenEvent {};
struct CloseEvent {};

struct ClosedState;
struct OpenState;

struct ClosedState
    : Will<ByDefault<DoNothing>, On<OpenEvent, TransitionTo<OpenState>>> {
  using Will::Handle;

  template <typename Event>
  static auto OnEnter(const Event & /*event*/) -> Status {
    std::cout << "   > door is closed\n";
    return Continue{};
  }

  [[nodiscard]] static auto Handle(const CloseEvent & /*event*/) -> DoNothing {
    std::cerr << "Error: the door is already closed!\n";
    return DoNothing{};
  }
};

struct OpenState
    : Will<ByDefault<DoNothing>, On<CloseEvent, TransitionTo<ClosedState>>> {
  using Will::Handle;

  template <typename Event>
  static auto OnEnter(const Event & /*event*/) -> Status {
    std::cout << "   > door is open\n";
    return Continue{};
  }

  [[nodiscard]] [[maybe_unused]] static auto Handle(const OpenEvent & /*event*/)
      -> DoNothing {
    std::cerr << "Error: the door is already open!\n";
    return DoNothing{};
  }
};
} // namespace

using Door = StateMachine<ClosedState, OpenState>;

auto main() -> int {
  try {
    Door door{ClosedState{}, OpenState{}};
    std::cout << "-- Starting\n";

    std::cout << "-- sending close event\n";
    door.Handle(CloseEvent{});

    std::cout << "-- sending open event\n";
    door.Handle(OpenEvent{});

    std::cout << "-- sending open event\n";
    door.Handle(OpenEvent{});

    std::cout << "-- sending close event\n";
    door.Handle(CloseEvent{});
  } catch (const std::exception &err) {
    std::cerr << "An exception was thrown: " << err.what() << std::endl;
  } catch (...) {
    std::cerr << "An unknown exception was thrown" << std::endl;
  }
}

Notice how we define a template method for OnEnter that gets called on any type of event. We could also write OnEnter handlers for a specific type of event. Such handlers will only get called when the event type matches the handler’s signature (templates SFINAE).

If we run that example, this is what we get:

-- Starting
-- sending close event
Error: the door is already closed!
-- sending open event
  > door is open
-- sending open event
Error: the door is already open!
-- sending close event
  > door is closed

Now, we want to make our door more secure by adding a lock pad and a code that will be required to unlock it once it is locked.

Head over to the next step to see how we can do that.