Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

machine-check API ergonomics issues #63

Open
Kelerchian opened this issue Aug 21, 2023 · 1 comment
Open

machine-check API ergonomics issues #63

Kelerchian opened this issue Aug 21, 2023 · 1 comment
Labels
duplicate This issue or pull request already exists

Comments

@Kelerchian
Copy link
Contributor

Kelerchian commented Aug 21, 2023

When writing API for machine-check, there are some concerns regarding the ergonomics:

Repeated arbitrary string

Arbitrary strings in the SwarmTypeProtocol transition properties are prone to error, especially typos.
While target and source states cannot be non-arbitrary strings without any significant change, writing a role and cmd can be omitted.

sidenote: This, however, would be a non-problem if eventually machine-check codes will be autogenerated.

cmd name must match the implemented MachineProtocol

There does not seem to be any point in ensuring that cmd name matches the implemented MachineProtocol.
cmd name is neither persisted in Actyx nor used in any transition calculation.
It is used only for function naming purposes, which should be irrelevant to the well-formed ness of a machine-runner MachineProtocol,

Possible Solution

Replace role field with MachineProtocol

machine-check understands the types exposed by machine-runner.
Therefore machine-check knows how to extract createJSONForAnalysis and subsequently the subscriptions of each machines.
This solves repeated arbitrary string issue for role.

Use builder pattern to collect events and define states before defining the transitions

SwarmProtocolInteractionDesign
  .build(ProtocolEvents.All, [
    "Initial",
    "Docking",
    "DockedAndWaitingForWater",
    "WaterDrawn"
  ])
  .transition(
    "Initial", 
    pump.machine, 
    [ProtocolEvents.DockAvailable.type],
    "Docking"
  )
  .transition(
    "Docking", 
    robot.machine, 
    [ProtocolEvents.RobotIsDocked.type], 
    "DockedAndWaitingForWater"
  )
  .transition(
    "DockedAndWaitingForWater", 
    pump.machine, 
    [ProtocolEvents.WaterSupplied.type], 
    "WaterDrawn"
  )
  .transition(
    "WaterDrawn", 
    robot.machine, 
    [ProtocolEvents.RobotIsUndocked.type], 
    "Undocked"
  )
  .roleInitial(robot.machine, robot._1_WaitingForDock)
  .roleInitial(pump.machine, pump._1_Initial)
  .finish()
  .test()
  // at this point: 
  // 1. all roles have initials figured out
  // 2. test suite can figure out the subscriptions
  // 3. test suite can test each role's projections

Remove cmd checking in the rust code

This solves cmd name must match the implemented MachineProtocol

@rkuhn
Copy link
Member

rkuhn commented Sep 16, 2023

This may be valuable background for but also superseded by #74 and #66 .

@Kelerchian Kelerchian added the duplicate This issue or pull request already exists label Sep 27, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
duplicate This issue or pull request already exists
Projects
None yet
Development

No branches or pull requests

2 participants