Terminology clarifications

[gmkado]

Hi @tinkerspy, very interesting library, I'm just sorting through it now to see if it'll work for my application.

One random question that I can't seem to find an answer to, what do the callback arguments idx, v and up refer to? Are they arbitrarily named? Do they stand for something in the world of automata?

The most I could find was this moderately unsatisfying blurb here:

Callbacks used in a Push Connector always have the three idx, v and up integer arguments. Their function may vary from component to component, check the documentation for details.

[tinkerspy]

• idx is a means of re-using a single callback function for multiple machine objects
• v contains the value of the object (if relevant) For a button that would be pressed (0 or 1)
• up contains the direction of the value (did it go up or down)

For examples of the use of idx and v check:

https://github.com/tinkerspy/Automaton/wiki/The-button-machine

For an example of the use of 'up' check:

https://github.com/tinkerspy/Automaton/wiki/The-encoder-machine

[gmkado]

Thanks!

[gmkado]

Reopening this as I think there are a few other places where terminology could use some clarifications. I can put in a PR for this but just want to make sure I'm understanding things.

• idx is a way for a single callback to be used by multiple connectors. In the button example, its a way of grouping all the relevent "onPress" logic in a single place.
• sub specifies which "slot" to use in a multi-slotted connector. It is a way of having the same connector serve multiple machines and/or callbacks
  • if you use the editor-generated overload that does not specify sub, it will fill all the slots by using onPush(..., fill = 1, ...). The comments also call this multi
  • if sub has value -1 (aka "auto store") It automatically finds the next available slot for each call to onPush. In the online editor the generated code no longer exposes the sub field.

broadcast - this is where I'm getting a little lost. I get the intent is to be able to push to all slots, but playing around with the editor it doesn't seem to do anything besides update the comments with e.g.:

// Available connectors:
//    push( connectors, ON_FINISHED | ATM_BROADCAST, 5, <v>, <up> );

Is that correct that any multi-slot connector could be or'd with ATM_BROADCAST to broadcast to all its slots?

Also, looking at the implementation:

Automaton/src/Machine.cpp

Lines 163 to 165 in a5b8d5a

	for ( int i = id; i < sub; i++ ) {
	connectors[id + i].push( v, up );
	}

Seems like this might be a bug? should i be initialized to 0 here?