Docs for ActivityWorker

[sclasen]

once #24 is in

[ryanwalls]

+1. Specifically, the coordinated handlers could use some documentation. Not really clear what start, tick, and cancel functions should be responsible for and what state they should maintain (if any.)

[sclasen]

not really docs, but the tests have 3 examples of coordinated handlers here

https://github.com/sclasen/swfsm/blob/master/activity/coordinated_worker_test.go#L177-L254

the tick counting example maintains state, which is used in the test here

https://github.com/sclasen/swfsm/blob/master/activity/coordinated_worker_test.go#L172

[ryanwalls]

Yeah, I had looked through those. Tick is the main point of confusion. Seems to be called every heartbeat? Is it supposed to do work? (In one test the tick function was called "Work"). Start = used to start work. Cancel = used to cancel work. Tick= ?

[sclasen]

@ryanwalls yeah, so lets take the example of running some sort of long running job.

Start would start the job running.

Tick would monitor the job, perhaps returning updates if desired. It does have a return type that is a bit strange.

• Tick that returns false, nil, nil just expresses that the job is still running.
• Tick that returns false, &SomeStruct{}, nil will express that the job is still running and also send an 'ActivityUpdated' signal back to the FSM with SomeStruct{} as the Input.
• Tick that returns true, &SomeStruct{}, nil, expresses that the job/activity is done and send SomeStruct{} back as the result. as well as stops heartbeating.
• Tick that returns true, nil, nil, expresses that the job is done and send no result back, as well as stops heartbeating.
• Tick that returns false, nil, err expresses that the job/activity failed and sends back err as the reason. as well as stops heartbeating.

If the heartbeating goroutine recieves Canceled: true in its heartbeat response, it stops heartbeating and calls Cancel.

[sclasen]

Of course you could do slightly different things with Start and Tick too. Start could verify that you could connect to a queue or some such, and Tick could poll the queue and consume it.

[ryanwalls]

@sclasen Awesome. That was exactly what I needed. Makes sense.

[ryanwalls]

@sclasen I'm 99% sure that true/false should be switched in your comment above. https://github.com/sclasen/swfsm/issues/25#issuecomment-179543175

When tick returns false the coordinate method returns. Here's the relevant piece of code:

    cont, res, err := c.handler.Tick(activityTask, input)
            if !cont {
                return res, err
            }

Updating my PR in just a minute to reflect the corrected description.