Documentation ¶
Overview ¶
Package workflow contains functions and types used to implement Cadence workflows.
A workflow is an implementation of coordination logic. The Cadence programming framework (aka client library) allows you to write the workflow coordination logic as simple procedural code that uses standard Go data modeling. The client library takes care of the communication between the worker service and the Cadence service, and ensures state persistence between events even in case of worker failures. Any particular execution is not tied to a particular worker machine. Different steps of the coordination logic can end up executing on different worker instances, with the framework ensuring that necessary state is recreated on the worker executing the step.
In order to facilitate this operational model both the Cadence programming framework and the managed service impose some requirements and restrictions on the implementation of the coordination logic. The details of these requirements and restrictions are described in the "Implementation" section below.
Overview ¶
The sample code below shows a simple implementation of a workflow that executes one activity. The workflow also passes the sole parameter it receives as part of its initialization as a parameter to the activity.
package sample import ( "time" "go.uber.org/cadence/workflow" ) func init() { workflow.Register(SimpleWorkflow) } func SimpleWorkflow(ctx workflow.Context, value string) error { ao := workflow.ActivityOptions{ TaskList: "sampleTaskList", ScheduleToCloseTimeout: time.Second * 60, ScheduleToStartTimeout: time.Second * 60, StartToCloseTimeout: time.Second * 60, HeartbeatTimeout: time.Second * 10, WaitForCancellation: false, } ctx = workflow.WithActivityOptions(ctx, ao) future := workflow.ExecuteActivity(ctx, SimpleActivity, value) var result string if err := future.Get(ctx, &result); err != nil { return err } workflow.GetLogger(ctx).Info(“Done”, zap.String(“result”, result)) return nil }
The following sections describe what is going on in the above code.
Declaration ¶
In the Cadence programing model a workflow is implemented with a function. The function declaration specifies the parameters the workflow accepts as well as any values it might return.
func SimpleWorkflow(ctx workflow.Context, value string) error
The first parameter to the function is ctx workflow.Context. This is a required parameter for all workflow functions and is used by the Cadence client library to pass execution context. Virtually all the client library functions that are callable from the workflow functions require this ctx parameter. This **context** parameter is the same concept as the standard context.Context provided by Go. The only difference between workflow.Context and context.Context is that the Done() function in workflow.Context returns workflow.Channel instead of the standard go chan.
The second string parameter is a custom workflow parameter that can be used to pass in data into the workflow on start. A workflow can have one or more such parameters. All parameters to an workflow function must be serializable, which essentially means that params can’t be channels, functions, variadic, or unsafe pointer.
Since it only declares error as the return value it means that the workflow does not return a value. The error return value is used to indicate an error was encountered during execution and the workflow should be terminated.
Implementation ¶
In order to support the synchronous and sequential programming model for the workflow implementation there are certain restrictions and requirements on how the workflow implementation must behave in order to guarantee correctness. The requirements are that:
- Execution must be deterministic
- Execution must be idempotent
A simplistic way to think about these requirements is that the workflow code:
- Can only read and manipulate local state or state received as return values from Cadence client library functions
- Should really not affect changes in external systems other than through invocation of activities
- Should interact with time only through the functions provided by the Cadence client library (i.e. workflow.Now(), workflow.Sleep())
- Should not create and interact with goroutines directly, it should instead use the functions provided by the Cadence client library. (i.e. workflow.Go() instead of go, workflow.Channel instead of chan, workflow.Selector instead of select)
- Should do all logging via the logger provided by the Cadence client library (i.e. workflow.GetLogger())
- Should not iterate over maps using range as order of map iteration is randomized
Now that we laid out the ground rules we can take a look at how to implement some common patterns inside workflows.
Special Cadence client library functions and types ¶
The Cadence client library provides a number of functions and types as alternatives to some native Go functions and types. Usage of these replacement functions/types is necessary in order to ensure that the workflow code execution is deterministic and repeatable within an execution context.
Coroutine related constructs:
- workflow.Go : This is a replacement for the the go statement
- workflow.Channel : This is a replacement for the native chan type. Cadence provides support for both buffered and unbuffered channels
- workflow.Selector : This is a replacement for the select statement
Time related functions:
- workflow.Now() : This is a replacement for time.Now()
- workflow.Sleep() : This is a replacement for time.Sleep()
Failing a Workflow ¶
To mark a workflow as failed, return an error from your workflow function via the err return value. Note that failed workflows do not record the non-error return's value: you cannot usefully return both a value and an error, only the error will be recorded.
Ending a Workflow externally ¶
Inside a workflow, to end you must finish your function by returning a result or error.
Externally, two tools exist to stop workflows from outside the workflow itself, by using the CLI or RPC client: cancellation and termination. Termination is forceful, cancellation allows a workflow to exit gracefully.
Workflows can also time out, based on their ExecutionStartToClose duration. A timeout behaves the same as termination (it is a hard deadline on the workflow), but a different close status and final event will be reported.
Terminating a Workflow ¶
Terminating is roughly equivalent to using `kill -9` on a process - the workflow will be ended immediately, and no further decisions will be made. It cannot be prevented or delayed by the workflow, or by any configuration. Any in-progress decisions or activities will fail whenever they next communicate with Cadence's servers, i.e. when they complete or when they next heartbeat.
Because termination does not allow for any further code to be run, this also means your workflow has no chance to clean up after itself (e.g. running a cleanup Activity to adjust a database record). If you need to run additional logic when your workflow, use cancellation instead.
Canceling a Workflow ¶
Canceling marks a workflow as canceled (this is a one-time, one-way operation), and immediately wakes the workflow up to process the cancellation (schedules a new decision task). When the workflow resumes after being canceled, the context that was passed into the workflow (and thus all derived contexts) will be canceled, which changes the behavior of many workflow.* functions.
Canceled workflow.Context behavior ¶
A workflow's context can be canceled by either canceling the workflow, or calling the cancel-func returned from a worfklow.WithCancel(ctx) call. Both behave identically.
At any time, you can convert a canceled (or could-be-canceled) context into a non-canceled context by using workflow.NewDisconnectedContext. The resulting context will ignore cancellation from the context it is derived from. Disconnected contexts like this can be created before or after a context has been canceled, and it does not matter how the cancellation occurred. Because this context will not be canceled, this can be useful for using context cancellation as a way to request that some behavior be shut down, while allowing you to run cleanup logic in activities or elsewhere.
As a general guideline, doing anything with I/O with a canceled context (e.g. executing an activity, starting a child workflow, sleeping) will fail rather than cause external changes. Detailed descriptions are available in documentation on functions that change their behavior with a canceled context; if it does not mention canceled-context behavior, its behavior does not change. For exact behavior, make sure to read the documentation on functions that you are calling.
As an incomplete summary, these actions will all fail immediately, and the associated error returns (possibly within a Future) will be a workflow.CanceledError:
- workflow.Await
- workflow.Sleep
- workflow.Timer
Child workflows will:
- ExecuteChildWorkflow will synchronously fail with a CanceledError if canceled before it is called (in v0.18.4 and newer. See https://github.com/uber-go/cadence-client/pull/1138 for details.)
- be canceled if the child workflow is running
- wait to complete their future.Get until the child returns, and the future will contain the final result (which may be anything that was returned, not necessarily a CanceledError)
Activities have configurable cancellation behavior. For workflow.ExecuteActivity and workflow.ExecuteLocalActivity, see the activity package's documentation for details. In summary though:
- ExecuteActivity will synchronously fail with a CanceledError if canceled before it is called
- the activity's future.Get will by default return a CanceledError immediately when canceled, unless activityoptions.WaitForCancellation is true
- the activity's context will be canceled at the next heartbeat event, or not at all if that does not occur
And actions like this will be completely unaffected:
- future.Get (futures derived from the calls above may return a CanceledError, but this is not guaranteed for all futures)
- selector.Select (Select is completely unaffected, similar to a native select statement. if you wish to unblock when your context is canceled, consider using an AddReceive with the context's Done() channel, as with a native select)
- channel.Send, channel.Receive, and channel.ReceiveAsync (similar to native chan read/write operations, use a selector to wait for send/receive or some other action)
- workflow.Go (the context argument in the callback is derived and may be canceled, but this does not stop the goroutine, nor stop new ones from being started)
- workflow.GetVersion, workflow.GetLogger, workflow.GetMetricsScope, workflow.Now, many others
Execute Activity ¶
The primary responsibility of the workflow implementation is to schedule activities for execution. The most straightforward way to do that is via the library method workflow.ExecuteActivity:
ao := workflow.ActivityOptions{ TaskList: "sampleTaskList", ScheduleToCloseTimeout: time.Second * 60, ScheduleToStartTimeout: time.Second * 60, StartToCloseTimeout: time.Second * 60, HeartbeatTimeout: time.Second * 10, WaitForCancellation: false, } ctx = workflow.WithActivityOptions(ctx, ao) future := workflow.ExecuteActivity(ctx, SimpleActivity, value) var result string if err := future.Get(ctx, &result); err != nil { return err }
Before calling workflow.ExecuteActivity(), ActivityOptions must be configured for the invocation. These are for the most part options to customize various execution timeouts. These options are passed in by creating a child context from the initial context and overwriting the desired values. The child context is then passed into the workflow.ExecuteActivity() call. If multiple activities are sharing the same exact option values then the same context instance can be used when calling workflow.ExecuteActivity().
The first parameter to the call is the required workflow.Context object. This type is an exact copy of context.Context with the Done() method returning workflow.Channel instead of native go chan.
The second parameter is the function that we registered as an activity function. This parameter can also be the a string representing the fully qualified name of the activity function. The benefit of passing in the actual function object is that in that case the framework can validate activity parameters.
The remaining parameters are the parameters to pass to the activity as part of the call. In our example we have a single parameter: **value**. This list of parameters must match the list of parameters declared by the activity function. Like mentioned above the Cadence client library will validate that this is indeed the case.
The method call returns immediately and returns a workflow.Future. This allows for more code to be executed without having to wait for the scheduled activity to complete.
When we are ready to process the results of the activity we call the Get() method on the future object returned. The parameters to this method are the ctx object we passed to the workflow.ExecuteActivity() call and an output parameter that will receive the output of the activity. The type of the output parameter must match the type of the return value declared by the activity function. The Get() method will block until the activity completes and results are available.
The result value returned by workflow.ExecuteActivity() can be retrieved from the future and used like any normal result from a synchronous function call. If the result above is a string value we could use it as follows:
var result string if err := future.Get(ctx1, &result); err != nil { return err } switch result { case “apple”: // do something case “bannana”: // do something default: return err }
In the example above we called the Get() method on the returned future immediately after workflow.ExecuteActivity(). However, this is not necessary. If we wish to execute multiple activities in parallel we can repeatedly call workflow.ExecuteActivity() store the futures returned and then wait for all activities to complete by calling the Get() methods of the future at a later time.
To implement more complex wait conditions on the returned future objects, use the workflow.Selector class. Take a look at our Pickfirst sample for an example of how to use of workflow.Selector.
Child Workflow ¶
workflow.ExecuteChildWorkflow enables the scheduling of other workflows from within a workflow's implementation. The parent workflow has the ability to "monitor" and impact the life-cycle of the child workflow in a similar way it can do for an activity it invoked.
cwo := workflow.ChildWorkflowOptions{ // Do not specify WorkflowID if you want cadence to generate a unique ID for child execution WorkflowID: "BID-SIMPLE-CHILD-WORKFLOW", ExecutionStartToCloseTimeout: time.Minute * 30, } childCtx = workflow.WithChildOptions(ctx, cwo) var result string future := workflow.ExecuteChildWorkflow(childCtx, SimpleChildWorkflow, value) if err := future.Get(ctx, &result); err != nil { workflow.GetLogger(ctx).Error("SimpleChildWorkflow failed.", zap.Error(err)) return err }
Before calling workflow.ExecuteChildWorkflow(), ChildWorkflowOptions must be configured for the invocation. These are for the most part options to customize various execution timeouts. These options are passed in by creating a child context from the initial context and overwriting the desired values. The child context is then passed into the workflow.ExecuteChildWorkflow() call. If multiple activities are sharing the same exact option values then the same context instance can be used when calling workflow.ExecuteChildWorkflow().
The first parameter to the call is the required workflow.Context object. This type is an exact copy of context.Context with the Done() method returning workflow.Channel instead of the native go chan.
The second parameter is the function that we registered as a workflow function. This parameter can also be a string representing the fully qualified name of the workflow function. What's the benefit? When you pass in the actual function object, the framework can validate workflow parameters.
The remaining parameters are the parameters to pass to the workflow as part of the call. In our example we have a single parameter: value. This list of parameters must match the list of parameters declared by the workflow function.
The method call returns immediately and returns a workflow.Future. This allows for more code to be executed without having to wait for the scheduled workflow to complete.
When we are ready to process the results of the workflow we call the Get() method on the future object returned. The parameters to this method are the ctx object we passed to the workflow.ExecuteChildWorkflow() call and an output parameter that will receive the output of the workflow. The type of the output parameter must match the type of the return value declared by the workflow function. The Get() method will block until the workflow completes and results are available.
The workflow.ExecuteChildWorkflow() function is very similar to the workflow.ExecuteActivity() function. All the patterns described for using the workflow.ExecuteActivity() apply to the workflow.ExecuteChildWorkflow() function as well.
Child workflows can also be configured to continue to exist once their parent workflow is closed. When using this pattern, extra care needs to be taken to ensure the child workflow is started before the parent workflow finishes.
cwo := workflow.ChildWorkflowOptions{ // Do not specify WorkflowID if you want cadence to generate a unique ID for child execution WorkflowID: "BID-SIMPLE-CHILD-WORKFLOW", ExecutionStartToCloseTimeout: time.Minute * 30, // Do not terminate when parent closes. ParentClosePolicy: client.ParentClosePolicyAbandon, } childCtx = workflow.WithChildOptions(ctx, cwo) future := workflow.ExecuteChildWorkflow(childCtx, SimpleChildWorkflow, value) // Wait for the child workflow to start if err := future.GetChildWorkflowExecution().Get(ctx, nil); err != nil { // Problem starting workflow. return err }
Error Handling ¶
Activities and child workflows can fail. You could handle errors differently based on different error cases. If the activity returns an error as errors.New() or fmt.Errorf(), those errors will be converted to workflow.GenericError. If the activity returns an error as workflow.NewCustomError("err-reason", details), that error will be converted to *workflow.CustomError. There are other types of errors like workflow.TimeoutError, workflow.CanceledError and workflow.PanicError. So the error handling code would look like:
err := workflow.ExecuteActivity(ctx, YourActivityFunc).Get(ctx, nil) switch err := err.(type) { case *workflow.CustomError: switch err.Reason() { case "err-reason-a": // handle error-reason-a var details YourErrorDetailsType err.Details(&details) // deal with details case "err-reason-b": // handle error-reason-b default: // handle all other error reasons } case *workflow.GenericError: switch err.Error() { case "err-msg-1": // handle error with message "err-msg-1" case "err-msg-2": // handle error with message "err-msg-2" default: // handle all other generic errors } case *workflow.TimeoutError: switch err.TimeoutType() { case shared.TimeoutTypeScheduleToStart: // handle ScheduleToStart timeout case shared.TimeoutTypeStartToClose: // handle StartToClose timeout case shared.TimeoutTypeHeartbeat: // handle heartbeat timeout default: } case *workflow.PanicError: // handle panic error case *workflow.CanceledError: // handle canceled error default: // all other cases (ideally, this should not happen) }
Signals ¶
Signals provide a mechanism to send data directly to a running workflow. Previously, you had two options for passing data to the workflow implementation:
- Via start parameters
- As return values from activities
With start parameters, we could only pass in values before workflow execution begins.
Return values from activities allowed us to pass information to a running workflow, but this approach comes with its own complications. One major drawback is reliance on polling. This means that the data needs to be stored in a third-party location until it's ready to be picked up by the activity. Further, the lifecycle of this activity requires management, and the activity requires manual restart if it fails before acquiring the data.
Signals, on the other hand, provides a fully asynch and durable mechanism for providing data to a running workflow. When a signal is received for a running workflow, Cadence persists the event and the payload in the workflow history. The workflow can then process the signal at any time afterwards without the risk of losing the information. The workflow also has the option to stop execution by blocking on a signal channel.
var signalVal string signalChan := workflow.GetSignalChannel(ctx, signalName) s := workflow.NewSelector(ctx) s.AddReceive(signalChan, func(c workflow.Channel, more bool) { c.Receive(ctx, &signalVal) workflow.GetLogger(ctx).Info("Received signal!", zap.String("signal", signalName), zap.String("value", signalVal)) }) s.Select(ctx) if len(signalVal) > 0 && signalVal != "SOME_VALUE" { return errors.New("signalVal") }
In the example above, the workflow code uses workflow.GetSignalChannel to open a workflow.Channel for the named signal. We then use a workflow.Selector to wait on this channel and process the payload received with the signal.
ContinueAsNew Workflow Completion ¶
Workflows that need to rerun periodically could naively be implemented as a big for loop with a sleep where the entire logic of the workflow is inside the body of the for loop. The problem with this approach is that the history for that workflow will keep growing to a point where it reaches the maximum size enforced by the service.
ContinueAsNew is the low level construct that enables implementing such workflows without the risk of failures down the road. The operation atomically completes the current execution and starts a new execution of the workflow with the same workflow ID. The new execution will not carry over any history from the old execution. To trigger this behavior, the workflow function should terminate by returning the special ContinueAsNewError error:
func SimpleWorkflow(workflow.Context ctx, value string) error { ... return workflow.NewContinueAsNewError(ctx, SimpleWorkflow, value) }
For a complete example implementing this pattern please refer to the Cron example.
SideEffect API ¶
workflow.SideEffect executes the provided function once, records its result into the workflow history, and doesn't re-execute upon replay. Instead, it returns the recorded result. Use it only for short, nondeterministic code snippets, like getting a random value or generating a UUID. It can be seen as an "inline" activity. However, one thing to note about workflow.SideEffect is that whereas for activities Cadence guarantees "at-most-once" execution, no such guarantee exists for workflow.SideEffect. Under certain failure conditions, workflow.SideEffect can end up executing the function more than once.
The only way to fail SideEffect is to panic, which causes decision task failure. The decision task after timeout is rescheduled and re-executed giving SideEffect another chance to succeed. Be careful to not return any data from the SideEffect function any other way than through its recorded return value.
encodedRandom := SideEffect(func(ctx workflow.Context) interface{} { return rand.Intn(100) }) var random int encodedRandom.Get(&random) if random < 50 { .... } else { .... }
Query API ¶
A workflow execution could be stuck at some state for longer than expected period. Cadence provide facilities to query the current call stack of a workflow execution. You can use cadence-cli to do the query, for example:
cadence-cli --domain samples-domain workflow query -w my_workflow_id -r my_run_id -qt __stack_trace
The above cli command uses __stack_trace as the query type. The __stack_trace is a built-in query type that is supported by cadence client library. You can also add your own custom query types to support thing like query current state of the workflow, or query how many activities the workflow has completed. To do so, you need to setup your own query handler using workflow.SetQueryHandler in your workflow code:
func MyWorkflow(ctx workflow.Context, input string) error { currentState := "started" // this could be any serializable struct err := workflow.SetQueryHandler(ctx, "state", func() (string, error) { return currentState, nil }) if err != nil { return err } // your normal workflow code begins here, and you update the currentState as the code makes progress. currentState = "waiting timer" err = NewTimer(ctx, time.Hour).Get(ctx, nil) if err != nil { currentState = "timer failed" return err } currentState = "waiting activity" ctx = WithActivityOptions(ctx, myActivityOptions) err = ExecuteActivity(ctx, MyActivity, "my_input").Get(ctx, nil) if err != nil { currentState = "activity failed" return err } currentState = "done" return nil }
The above sample code sets up a query handler to handle query type "state". With that, you should be able to query with cli:
cadence-cli --domain samples-domain workflow query -w my_workflow_id -r my_run_id -qt state
Besides using cadence-cli, you can also issue query from code using QueryWorkflow() API on cadence Client object.
Registration ¶
For some client code to be able to invoke a workflow type, the worker process needs to be aware of all the implementations it has access to. A workflow is registered with the following call:
workflow.Register(SimpleWorkflow)
This call essentially creates an in memory mapping inside the worker process between the fully qualified function name and the implementation. It is safe to call this registration method from an **init()** function. If the worker receives tasks for a workflow type it does not know it will fail that task. However, the failure of the task will not cause the entire workflow to fail.
Testing ¶
The Cadence client library provides a test framework to facilitate testing workflow implementations. The framework is suited for implementing unit tests as well as functional tests of the workflow logic.
The code below implements the unit tests for the SimpleWorkflow sample.
package sample import ( "errors" "testing" "code.uber.internal/devexp/cadence-worker/activity" "github.com/stretchr/testify/mock" "github.com/stretchr/testify/suite" "go.uber.org/cadence/testsuite" ) type UnitTestSuite struct { suite.Suite testsuite.WorkflowTestSuite env *testsuite.TestWorkflowEnvironment } func (s *UnitTestSuite) SetupTest() { s.env = s.NewTestWorkflowEnvironment() } func (s *UnitTestSuite) AfterTest(suiteName, testName string) { s.env.AssertExpectations(s.T()) } func (s *UnitTestSuite) Test_SimpleWorkflow_Success() { s.env.ExecuteWorkflow(SimpleWorkflow, "test_success") s.True(s.env.IsWorkflowCompleted()) s.NoError(s.env.GetWorkflowError()) } func (s *UnitTestSuite) Test_SimpleWorkflow_ActivityParamCorrect() { s.env.OnActivity(SimpleActivity, mock.Anything, mock.Anything).Return(func(ctx context.Context, value string) (string, error) { s.Equal("test_success", value) return value, nil }) s.env.ExecuteWorkflow(SimpleWorkflow, "test_success") s.True(s.env.IsWorkflowCompleted()) s.NoError(s.env.GetWorkflowError()) } func (s *UnitTestSuite) Test_SimpleWorkflow_ActivityFails() { s.env.OnActivity(SimpleActivity, mock.Anything, mock.Anything).Return("", errors.New("SimpleActivityFailure")) s.env.ExecuteWorkflow(SimpleWorkflow, "test_failure") s.True(s.env.IsWorkflowCompleted()) s.NotNil(s.env.GetWorkflowError()) _, ok := s.env.GetWorkflowError().(*workflow.GenericError) s.True(ok) s.Equal("SimpleActivityFailure", s.env.GetWorkflowError().Error()) } func TestUnitTestSuite(t *testing.T) { suite.Run(t, new(UnitTestSuite)) }
Setup ¶
First, we define a "test suite" struct that absorbs both the basic suite functionality from testify http://godoc.org/github.com/stretchr/testify/suite via suite.Suite and the suite functionality from the Cadence test framework via testsuite.WorkflowTestSuite. Since every test in this suite will test our workflow we add a property to our struct to hold an instance of the test environment. This will allow us to initialize the test environment in a setup method. For testing workflows we use a testsuite.TestWorkflowEnvironment.
We then implement a SetupTest method to setup a new test environment before each test. Doing so ensure that each test runs in it's own isolated sandbox. We also implement an AfterTest function where we assert that all mocks we setup were indeed called by invoking s.env.AssertExpectations(s.T()).
Finally, we create a regular test function recognized by "go test" and pass the struct to suite.Run.
A Simple Test ¶
The simplest test case we can write is to have the test environment execute the workflow and then evaluate the results.
func (s *UnitTestSuite) Test_SimpleWorkflow_Success() { s.env.ExecuteWorkflow(SimpleWorkflow, "test_success") s.True(s.env.IsWorkflowCompleted()) s.NoError(s.env.GetWorkflowError()) }
Calling s.env.ExecuteWorkflow(...) will execute the workflow logic and any invoked activities inside the test process. The first parameter to s.env.ExecuteWorkflow(...) is the workflow functions and any subsequent parameters are values for custom input parameters declared by the workflow function. An important thing to note is that unless the activity invocations are mocked or activity implementation replaced (see next section), the test environment will execute the actual activity code including any calls to outside services.
In the example above, after executing the workflow we assert that the workflow ran through to completion via the call to s.env.IsWorkflowComplete(). We also assert that no errors where returned by asserting on the return value of s.env.GetWorkflowError(). If our workflow returned a value, we we can retrieve that value via a call to s.env.GetWorkflowResult(&value) and add asserts on that value.
Activity Mocking and Overriding ¶
When testing workflows, especially unit testing workflows, we want to test the workflow logic in isolation. Additionally, we want to inject activity errors during our tests runs. The test framework provides two mechanisms that support these scenarios: activity mocking and activity overriding. Both these mechanisms allow you to change the behavior of activities invoked by your workflow without having to modify the actual workflow code.
Lets first take a look at a test that simulates a test failing via the "activity mocking" mechanism.
func (s *UnitTestSuite) Test_SimpleWorkflow_ActivityFails() { s.env.OnActivity(SimpleActivity, mock.Anything, mock.Anything).Return("", errors.New("SimpleActivityFailure")) s.env.ExecuteWorkflow(SimpleWorkflow, "test_failure") s.True(s.env.IsWorkflowCompleted()) s.NotNil(s.env.GetWorkflowError()) _, ok := s.env.GetWorkflowError().(*workflow.GenericError) s.True(ok) s.Equal("SimpleActivityFailure", s.env.GetWorkflowError().Error()) }
In this test we want to simulate the execution of the activity SimpleActivity invoked by our workflow SimpleWorkflow returning an error. We do that by setting up a mock on the test environment for the SimpleActivity that returns an error.
s.env.OnActivity(SimpleActivity, mock.Anything, mock.Anything).Return("", errors.New("SimpleActivityFailure"))
With the mock set up we can now execute the workflow via the s.env.ExecuteWorkflow(...) method and assert that the workflow completed successfully and returned the expected error.
Simply mocking the execution to return a desired value or error is a pretty powerful mechanism to isolate workflow logic. However, sometimes we want to replace the activity with an alternate implementation to support a more complex test scenario. For our simple workflow lets assume we wanted to validate that the activity gets called with the correct parameters.
func (s *UnitTestSuite) Test_SimpleWorkflow_ActivityParamCorrect() { s.env.OnActivity(SimpleActivity, mock.Anything, mock.Anything).Return(func(ctx context.Context, value string) (string, error) { s.Equal("test_success", value) return value, nil }) s.env.ExecuteWorkflow(SimpleWorkflow, "test_success") s.True(s.env.IsWorkflowCompleted()) s.NoError(s.env.GetWorkflowError()) }
In this example, we provide a function implementation as the parameter to Return. This allows us to provide an alternate implementation for the activity SimpleActivity. The framework will execute this function whenever the activity is invoked and pass on the return value from the function as the result of the activity invocation. Additionally, the framework will validate that the signature of the "mock" function matches the signature of the original activity function.
Since this can be an entire function, there really is no limitation as to what we can do in here. In this example, to assert that the "value" param has the same content to the value param we passed to the workflow.
Index ¶
- Variables
- func Await(ctx Context, condition func() bool) error
- func CompleteSession(ctx Context)
- func GetLastCompletionResult(ctx Context, d ...interface{}) error
- func GetLogger(ctx Context) *zap.Logger
- func GetMetricsScope(ctx Context) tally.Scope
- func Go(ctx Context, f func(ctx Context))
- func GoNamed(ctx Context, name string, f func(ctx Context))
- func HasLastCompletionResult(ctx Context) bool
- func IsReplaying(ctx Context) bool
- func MutableSideEffect(ctx Context, id string, f func(ctx Context) interface{}, ...) encoded.Value
- func NewDisconnectedContext(parent Context) (ctx Context, cancel CancelFunc)
- func NewFuture(ctx Context) (Future, Settable)
- func Now(ctx Context) time.Time
- func Register(workflowFunc interface{})
- func RegisterWithOptions(workflowFunc interface{}, opts RegisterOptions)
- func SetQueryHandler(ctx Context, queryType string, handler interface{}) error
- func SideEffect(ctx Context, f func(ctx Context) interface{}) encoded.Value
- func Sleep(ctx Context, d time.Duration) (err error)
- func UpsertSearchAttributes(ctx Context, attributes map[string]interface{}) error
- func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
- type ActivityOptions
- type Bugports
- type CancelFunc
- type Channel
- type ChildWorkflowFuture
- type ChildWorkflowOptions
- type Context
- func CreateSession(ctx Context, sessionOptions *SessionOptions) (Context, error)
- func RecreateSession(ctx Context, recreateToken []byte, sessionOptions *SessionOptions) (Context, error)
- func WithActivityOptions(ctx Context, options ActivityOptions) Context
- func WithChildOptions(ctx Context, cwo ChildWorkflowOptions) Context
- func WithDataConverter(ctx Context, dc encoded.DataConverter) Context
- func WithExecutionStartToCloseTimeout(ctx Context, d time.Duration) Context
- func WithHeartbeatTimeout(ctx Context, d time.Duration) Context
- func WithLocalActivityOptions(ctx Context, options LocalActivityOptions) Context
- func WithRetryPolicy(ctx Context, retryPolicy RetryPolicy) Context
- func WithScheduleToCloseTimeout(ctx Context, d time.Duration) Context
- func WithScheduleToStartTimeout(ctx Context, d time.Duration) Context
- func WithStartToCloseTimeout(ctx Context, d time.Duration) Context
- func WithTaskList(ctx Context, name string) Context
- func WithValue(parent Context, key interface{}, val interface{}) Context
- func WithWaitForCancellation(ctx Context, wait bool) Context
- func WithWorkflowDomain(ctx Context, name string) Context
- func WithWorkflowID(ctx Context, workflowID string) Context
- func WithWorkflowTaskList(ctx Context, name string) Context
- func WithWorkflowTaskStartToCloseTimeout(ctx Context, d time.Duration) Context
- type ContextPropagator
- type ContinueAsNewError
- type Execution
- type Future
- func ExecuteActivity(ctx Context, activity interface{}, args ...interface{}) Future
- func ExecuteLocalActivity(ctx Context, activity interface{}, args ...interface{}) Future
- func NewTimer(ctx Context, d time.Duration) Future
- func RequestCancelExternalWorkflow(ctx Context, workflowID, runID string) Future
- func SignalExternalWorkflow(ctx Context, workflowID, runID, signalName string, arg interface{}) Future
- type GenericError
- type HeaderReader
- type HeaderWriter
- type Info
- type LocalActivityOptions
- type PanicError
- type RegisterOptions
- type RetryPolicy
- type Selector
- type SessionInfo
- type SessionOptions
- type Settable
- type TerminatedError
- type TimeoutError
- type Type
- type UnknownExternalWorkflowExecutionError
- type Version
- type WaitGroup
Constants ¶
This section is empty.
Variables ¶
var ErrCanceled = internal.ErrCanceled
ErrCanceled is the error returned by Context.Err when the context is canceled.
var ErrDeadlineExceeded = internal.ErrDeadlineExceeded
ErrDeadlineExceeded is the error returned by Context.Err when the context's deadline passes.
var ErrSessionFailed = internal.ErrSessionFailed
ErrSessionFailed is the error returned when user tries to execute an activity but the session it belongs to has already failed
Functions ¶
func Await ¶ added in v0.12.0
Await blocks the calling thread until condition() returns true. Do not mutate values or trigger side effects inside condition. Returns CanceledError if the ctx is canceled. The following code is going to block until the captured count variable is set to 5.
workflow.Await(ctx, func() bool { return count == 5 })
func CompleteSession ¶ added in v0.8.4
func CompleteSession(ctx Context)
CompleteSession completes a session. It releases worker resources, so other sessions can be created. CompleteSession won't do anything if the context passed in doesn't contain any session information or the session has already completed or failed.
After a session has completed, user can continue to use the context, but the activities will be scheduled on the normal taskList (as user specified in ActivityOptions) and may be picked up by another worker since it's not in a session.
func GetLastCompletionResult ¶ added in v0.8.0
GetLastCompletionResult extract last completion result from previous run for this cron workflow. This is used in combination with cron schedule. A workflow can be started with an optional cron schedule. If a cron workflow wants to pass some data to next schedule, it can return any data and that data will become available when next run starts. This GetLastCompletionResult() extract the data into expected data structure. See TestWorkflowEnvironment.SetLastCompletionResult() for unit test support.
func GetMetricsScope ¶
GetMetricsScope returns a metrics scope to be used in workflow's context
func Go ¶
Go creates a new coroutine. It has similar semantic to goroutine in a context of the workflow.
func GoNamed ¶
GoNamed creates a new coroutine with a given human readable name. It has similar semantic to goroutine in a context of the workflow. Name appears in stack traces that include this coroutine.
func HasLastCompletionResult ¶ added in v0.8.0
HasLastCompletionResult checks if there is completion result from previous runs. This is used in combination with cron schedule. A workflow can be started with an optional cron schedule. If a cron workflow wants to pass some data to next schedule, it can return any data and that data will become available when next run starts. This HasLastCompletionResult() checks if there is such data available passing down from previous successful run.
func IsReplaying ¶ added in v0.5.1
IsReplaying returns whether the current workflow code is replaying.
Warning! Never make decisions, like schedule activity/childWorkflow/timer or send/wait on future/channel, based on this flag as it is going to break workflow determinism requirement. The only reasonable use case for this flag is to avoid some external actions during replay, like custom logging or metric reporting. Please note that Cadence already provide standard logging/metric via workflow.GetLogger(ctx) and workflow.GetMetricsScope(ctx), and those standard mechanism are replay-aware and it will automatically suppress during replay. Only use this flag if you need custom logging/metrics reporting, for example if you want to log to kafka.
Warning! Any action protected by this flag should not fail or if it does fail should ignore that failure or panic on the failure. If workflow don't want to be blocked on those failure, it should ignore those failure; if workflow do want to make sure it proceed only when that action succeed then it should panic on that failure. Panic raised from a workflow causes decision task to fail and cadence server will rescheduled later to retry.
func MutableSideEffect ¶ added in v0.6.1
func MutableSideEffect(ctx Context, id string, f func(ctx Context) interface{}, equals func(a, b interface{}) bool) encoded.Value
MutableSideEffect executes the provided function once, then it looks up the history for the value with the given id. If there is no existing value, then it records the function result as a value with the given id on history; otherwise, it compares whether the existing value from history has changed from the new function result by calling the provided equals function. If they are equal, it returns the value without recording a new one in history;
otherwise, it records the new value with the same id on history.
Caution: do not use MutableSideEffect to modify closures. Always retrieve result from MutableSideEffect's encoded return value.
The difference between MutableSideEffect() and SideEffect() is that every new SideEffect() call in non-replay will result in a new marker being recorded on history. However, MutableSideEffect() only records a new marker if the value changed. During replay, MutableSideEffect() will not execute the function again, but it will return the exact same value as it was returning during the non-replay run.
One good use case of MutableSideEffect() is to access dynamically changing config without breaking determinism.
func NewDisconnectedContext ¶ added in v0.5.1
func NewDisconnectedContext(parent Context) (ctx Context, cancel CancelFunc)
NewDisconnectedContext returns a new context that won't propagate parent's cancellation to the new child context. One common use case is to do cleanup work after workflow is cancelled.
err := workflow.ExecuteActivity(ctx, ActivityFoo).Get(ctx, &activityFooResult) if err != nil && cadence.IsCanceledError(ctx.Err()) { // activity failed, and workflow context is canceled disconnectedCtx, _ := workflow.newDisconnectedContext(ctx); workflow.ExecuteActivity(disconnectedCtx, handleCancellationActivity).Get(disconnectedCtx, nil) return err // workflow return CanceledError }
func NewFuture ¶
NewFuture creates a new future as well as associated Settable that is used to set its value.
func Now ¶
Now returns the current time when the decision is started or replayed. The workflow needs to use this Now() to get the wall clock time instead of the Go lang library one.
func Register ¶
func Register(workflowFunc interface{})
Register - registers a workflow function with the framework. A workflow takes a workflow context and input and returns a (result, error) or just error. Examples:
func sampleWorkflow(ctx workflow.Context, input []byte) (result []byte, err error) func sampleWorkflow(ctx workflow.Context, arg1 int, arg2 string) (result []byte, err error) func sampleWorkflow(ctx workflow.Context) (result []byte, err error) func sampleWorkflow(ctx workflow.Context, arg1 int) (result string, err error)
Serialization of all primitive types, structures is supported ... except channels, functions, variadic, unsafe pointer. This method calls panic if workflowFunc doesn't comply with the expected format. Deprecated: Global workflow registration methods are replaced by equivalent Worker instance methods. This method is kept to maintain backward compatibility and should not be used.
func RegisterWithOptions ¶
func RegisterWithOptions(workflowFunc interface{}, opts RegisterOptions)
RegisterWithOptions registers the workflow function with options The user can use options to provide an external name for the workflow or leave it empty if no external name is required. This can be used as
client.RegisterWorkflow(sampleWorkflow, RegisterOptions{}) client.RegisterWorkflow(sampleWorkflow, RegisterOptions{Name: "foo"})
A workflow takes a workflow context and input and returns a (result, error) or just error. Examples:
func sampleWorkflow(ctx workflow.Context, input []byte) (result []byte, err error) func sampleWorkflow(ctx workflow.Context, arg1 int, arg2 string) (result []byte, err error) func sampleWorkflow(ctx workflow.Context) (result []byte, err error) func sampleWorkflow(ctx workflow.Context, arg1 int) (result string, err error)
Serialization of all primitive types, structures is supported ... except channels, functions, variadic, unsafe pointer. This method calls panic if workflowFunc doesn't comply with the expected format. Deprecated: Global workflow registration methods are replaced by equivalent Worker instance methods. This method is kept to maintain backward compatibility and should not be used.
func SetQueryHandler ¶
SetQueryHandler sets the query handler to handle workflow query. The queryType specify which query type this handler should handle. The handler must be a function that returns 2 values. The first return value must be a serializable result. The second return value must be an error. The handler function could receive any number of input parameters. All the input parameter must be serializable. You should call workflow.SetQueryHandler() at the beginning of the workflow code. When client calls Client.QueryWorkflow() to cadence server, a task will be generated on server that will be dispatched to a workflow worker, which will replay the history events and then execute a query handler based on the query type. The query handler will be invoked out of the context of the workflow, meaning that the handler code must not use workflow context to do things like workflow.NewChannel(), workflow.Go() or to call any workflow blocking functions like Channel.Get() or Future.Get(). Trying to do so in query handler code will fail the query and client will receive QueryFailedError. Example of workflow code that support query type "current_state":
func MyWorkflow(ctx workflow.Context, input string) error { currentState := "started" // this could be any serializable struct err := workflow.SetQueryHandler(ctx, "current_state", func() (string, error) { return currentState, nil }) if err != nil { currentState = "failed to register query handler" return err } // your normal workflow code begins here, and you update the currentState as the code makes progress. currentState = "waiting timer" err = NewTimer(ctx, time.Hour).Get(ctx, nil) if err != nil { currentState = "timer failed" return err } currentState = "waiting activity" ctx = WithActivityOptions(ctx, myActivityOptions) err = ExecuteActivity(ctx, MyActivity, "my_input").Get(ctx, nil) if err != nil { currentState = "activity failed" return err } currentState = "done" return nil }
func SideEffect ¶
SideEffect executes the provided function once, records its result into the workflow history. The recorded result on history will be returned without executing the provided function during replay. This guarantees the deterministic requirement for workflow as the exact same result will be returned in replay. Common use case is to run some short non-deterministic code in workflow, like getting random number or new UUID. The only way to fail SideEffect is to panic which causes decision task failure. The decision task after timeout is rescheduled and re-executed giving SideEffect another chance to succeed.
Caution: do not use SideEffect to modify closures. Always retrieve result from SideEffect's encoded return value. For example this code is BROKEN:
// Bad example: var random int workflow.SideEffect(func(ctx workflow.Context) interface{} { random = rand.Intn(100) return nil }) // random will always be 0 in replay, thus this code is non-deterministic if random < 50 { .... } else { .... }
On replay the provided function is not executed, the random will always be 0, and the workflow could takes a different path breaking the determinism.
Here is the correct way to use SideEffect:
// Good example: encodedRandom := SideEffect(func(ctx workflow.Context) interface{} { return rand.Intn(100) }) var random int encodedRandom.Get(&random) if random < 50 { .... } else { .... }
func Sleep ¶
Sleep pauses the current workflow for at least the duration d. A negative or zero duration causes Sleep to return immediately. Workflow code needs to use this Sleep() to sleep instead of the Go lang library one(timer.Sleep()). You can cancel the pending sleep by cancel the Context (using context from workflow.WithCancel(ctx)). Sleep() returns nil if the duration d is passed, or it returns *CanceledError if the ctx is canceled. There are 2 reasons the ctx could be canceled: 1) your workflow code cancel the ctx (with workflow.WithCancel(ctx)); 2) your workflow itself is canceled by external request. The current timer resolution implementation is in seconds and uses math.Ceil(d.Seconds()) as the duration. But is subjected to change in the future.
func UpsertSearchAttributes ¶ added in v0.9.0
UpsertSearchAttributes is used to add or update workflow search attributes. The search attributes can be used in query of List/Scan/Count workflow APIs. The key and value type must be registered on cadence server side; The value has to deterministic when replay; The value has to be Json serializable. UpsertSearchAttributes will merge attributes to existing map in workflow, for example workflow code:
func MyWorkflow(ctx workflow.Context, input string) error { attr1 := map[string]interface{}{ "CustomIntField": 1, "CustomBoolField": true, } workflow.UpsertSearchAttributes(ctx, attr1) attr2 := map[string]interface{}{ "CustomIntField": 2, "CustomKeywordField": "seattle", } workflow.UpsertSearchAttributes(ctx, attr2) }
will eventually have search attributes:
map[string]interface{}{ "CustomIntField": 2, "CustomBoolField": true, "CustomKeywordField": "seattle", }
This is only supported when using ElasticSearch.
func WithCancel ¶
func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
WithCancel returns a copy of parent with a new Done channel. The returned context's Done channel is closed when the returned cancel function is called or when the parent context's Done channel is closed, whichever happens first.
Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this Context complete.
Types ¶
type ActivityOptions ¶
type ActivityOptions = internal.ActivityOptions
ActivityOptions stores all activity-specific invocation parameters that will be stored inside of a context.
type Bugports ¶ added in v0.18.4
Bugports contains opt-in flags for backports of old, buggy behavior that has been fixed. See the internal docs for details.
type CancelFunc ¶
type CancelFunc = internal.CancelFunc
A CancelFunc tells an operation to abandon its work. A CancelFunc does not wait for the work to stop. After the first call, subsequent calls to a CancelFunc do nothing.
type Channel ¶
Channel must be used instead of native go channel by workflow code. Use workflow.NewChannel(ctx) method to create Channel instance.
func GetSignalChannel ¶
GetSignalChannel returns channel corresponding to the signal name.
func NewBufferedChannel ¶
NewBufferedChannel create new buffered Channel instance
func NewNamedBufferedChannel ¶
NewNamedBufferedChannel create new BufferedChannel instance with a given human readable name. Name appears in stack traces that are blocked on this Channel.
func NewNamedChannel ¶
NewNamedChannel create new Channel instance with a given human readable name. Name appears in stack traces that are blocked on this channel.
type ChildWorkflowFuture ¶
type ChildWorkflowFuture = internal.ChildWorkflowFuture
ChildWorkflowFuture represents the result of a child workflow execution
func ExecuteChildWorkflow ¶
func ExecuteChildWorkflow(ctx Context, childWorkflow interface{}, args ...interface{}) ChildWorkflowFuture
ExecuteChildWorkflow requests child workflow execution in the context of a workflow. Context can be used to pass the settings for the child workflow. For example: task list that this child workflow should be routed, timeouts that need to be configured. Use ChildWorkflowOptions to pass down the options.
cwo := ChildWorkflowOptions{ ExecutionStartToCloseTimeout: 10 * time.Minute, TaskStartToCloseTimeout: time.Minute, } ctx := WithChildOptions(ctx, cwo)
Input childWorkflow is either a workflow name or a workflow function that is getting scheduled. Input args are the arguments that need to be passed to the child workflow function represented by childWorkflow. If the child workflow failed to complete then the future get error would indicate the failure and it can be one of CustomError, TimeoutError, CanceledError, GenericError. You can cancel the pending child workflow using context(workflow.WithCancel(ctx)) and that will fail the workflow with error CanceledError. ExecuteChildWorkflow returns ChildWorkflowFuture.
type ChildWorkflowOptions ¶
type ChildWorkflowOptions = internal.ChildWorkflowOptions
ChildWorkflowOptions stores all child workflow specific parameters that will be stored inside of a Context.
type Context ¶
Context is a clone of context.Context with Done() returning Channel instead of native channel. A Context carries a deadline, a cancellation signal, and other values across API boundaries.
Context's methods may be called by multiple goroutines simultaneously.
func CreateSession ¶ added in v0.8.4
func CreateSession(ctx Context, sessionOptions *SessionOptions) (Context, error)
CreateSession creates a session and returns a new context which contains information of the created session. The session will be created on the tasklist user specified in ActivityOptions. If none is specified, the default one will be used.
CreationSession will fail in the following situations:
- The context passed in already contains a session which is still open (not closed and failed).
- All the workers are busy (number of sessions currently running on all the workers have reached MaxConcurrentSessionExecutionSize, which is specified when starting the workers) and session cannot be created within a specified timeout.
If an activity is executed using the returned context, it's regarded as part of the session. All activities within the same session will be executed by the same worker. User still needs to handle the error returned when executing an activity. Session will not be marked as failed if an activity within it returns an error. Only when the worker executing the session is down, that session will be marked as failed. Executing an activity within a failed session will return ErrSessionFailed immediately without scheduling that activity.
The returned session Context will be cancelled if the session fails (worker died) or CompleteSession() is called. This means that in these two cases, all user activities scheduled using the returned session Context will also be cancelled.
If user wants to end a session since activity returns some error, use CompleteSession API below. New session can be created if necessary to retry the whole session.
Example:
so := &SessionOptions{ ExecutionTimeout: time.Minute, CreationTimeout: time.Minute, } sessionCtx, err := CreateSession(ctx, so) if err != nil { // Creation failed. Wrong ctx or too many outstanding sessions. } defer CompleteSession(sessionCtx) err = ExecuteActivity(sessionCtx, someActivityFunc, activityInput).Get(sessionCtx, nil) if err == ErrSessionFailed { // Session has failed } else { // Handle activity error } ... // execute more activities using sessionCtx
func RecreateSession ¶ added in v0.8.4
func RecreateSession(ctx Context, recreateToken []byte, sessionOptions *SessionOptions) (Context, error)
RecreateSession recreate a session based on the sessionInfo passed in. Activities executed within the recreated session will be executed by the same worker as the previous session. RecreateSession() returns an error under the same situation as CreateSession() or the token passed in is invalid. It also has the same usage as CreateSession().
The main usage of RecreateSession is for long sessions that are splited into multiple runs. At the end of one run, complete the current session, get recreateToken from sessionInfo by calling SessionInfo.GetRecreateToken() and pass the token to the next run. In the new run, session can be recreated using that token.
func WithActivityOptions ¶
func WithActivityOptions(ctx Context, options ActivityOptions) Context
WithActivityOptions makes a copy of the context and adds the passed in options to the context. If an activity options exists, it will be overwritten by the passed in value as a whole. So specify all the values in the options as necessary, as values in the existing context options will not be carried over.
func WithChildOptions ¶
func WithChildOptions(ctx Context, cwo ChildWorkflowOptions) Context
WithChildOptions adds all workflow options to the context.
func WithDataConverter ¶ added in v0.7.0
func WithDataConverter(ctx Context, dc encoded.DataConverter) Context
WithDataConverter adds DataConverter to the context.
func WithExecutionStartToCloseTimeout ¶
WithExecutionStartToCloseTimeout adds a workflow execution timeout to the context.
func WithHeartbeatTimeout ¶
WithHeartbeatTimeout makes a copy of the current context and update the HeartbeatTimeout field in its activity options. An empty activity options will be created if it does not exist in the original context.
Cadence time resolution is in seconds and the library uses math.Ceil(d.Seconds()) to calculate the final value. This is subject to change in the future.
func WithLocalActivityOptions ¶ added in v0.5.1
func WithLocalActivityOptions(ctx Context, options LocalActivityOptions) Context
WithLocalActivityOptions makes a copy of the context and adds the passed in options to the context. If a local activity options exists, it will be overwritten by the passed in value.
func WithRetryPolicy ¶ added in v0.12.1
func WithRetryPolicy(ctx Context, retryPolicy RetryPolicy) Context
WithRetryPolicy makes a copy of the current context and update the RetryPolicy field in its activity options. An empty activity options will be created if it does not exist in the original context.
func WithScheduleToCloseTimeout ¶
WithScheduleToCloseTimeout makes a copy of the current context and update the ScheduleToCloseTimeout field in its activity options. An empty activity options will be created if it does not exist in the original context.
Cadence time resolution is in seconds and the library uses math.Ceil(d.Seconds()) to calculate the final value. This is subject to change in the future.
func WithScheduleToStartTimeout ¶
WithScheduleToStartTimeout makes a copy of the current context and update the ScheduleToStartTimeout field in its activity options. An empty activity options will be created if it does not exist in the original context.
Cadence time resolution is in seconds and the library uses math.Ceil(d.Seconds()) to calculate the final value. This is subject to change in the future.
func WithStartToCloseTimeout ¶
WithStartToCloseTimeout makes a copy of the current context and update the StartToCloseTimeout field in its activity options. An empty activity options will be created if it does not exist in the original context.
Cadence time resolution is in seconds and the library uses math.Ceil(d.Seconds()) to calculate the final value. This is subject to change in the future.
func WithTaskList ¶
WithTaskList makes a copy of the current context and update the taskList field in its activity options. An empty activity options will be created if it does not exist in the original context.
func WithValue ¶
WithValue returns a copy of parent in which the value associated with key is val.
Use context Values only for request-scoped data that transits processes and APIs, not for passing optional parameters to functions.
func WithWaitForCancellation ¶
WithWaitForCancellation makes a copy of the current context and update the WaitForCancellation field in its activity options. An empty activity options will be created if it does not exist in the original context.
func WithWorkflowDomain ¶
WithWorkflowDomain adds a domain to the context.
func WithWorkflowID ¶
WithWorkflowID adds a workflowID to the context.
func WithWorkflowTaskList ¶
WithWorkflowTaskList adds a task list to the context.
type ContextPropagator ¶ added in v0.8.4
type ContextPropagator = internal.ContextPropagator
ContextPropagator is an interface that determines what information from context to pass along
type ContinueAsNewError ¶
type ContinueAsNewError = internal.ContinueAsNewError
ContinueAsNewError can be returned by a workflow implementation function and indicates that the workflow should continue as new with the same WorkflowID, but new RunID and new history.
func NewContinueAsNewError ¶
func NewContinueAsNewError(ctx Context, wfn interface{}, args ...interface{}) *ContinueAsNewError
NewContinueAsNewError creates ContinueAsNewError instance If the workflow main function returns this error then the current execution is ended and the new execution with same workflow ID is started automatically with options provided to this function.
ctx - use context to override any options for the new workflow like execution timeout, decision task timeout, task list. if not mentioned it would use the defaults that the current workflow is using. ctx := WithExecutionStartToCloseTimeout(ctx, 30 * time.Minute) ctx := WithWorkflowTaskStartToCloseTimeout(ctx, time.Minute) ctx := WithWorkflowTaskList(ctx, "example-group") wfn - workflow function. for new execution it can be different from the currently running. args - arguments for the new workflow.
type Future ¶
Future represents the result of an asynchronous computation.
func ExecuteActivity ¶
ExecuteActivity requests activity execution in the context of a workflow. Context can be used to pass the settings for this activity. For example: task list that this need to be routed, timeouts that need to be configured. Use ActivityOptions to pass down the options.
ao := ActivityOptions{ TaskList: "exampleTaskList", ScheduleToStartTimeout: 10 * time.Second, StartToCloseTimeout: 5 * time.Second, ScheduleToCloseTimeout: 10 * time.Second, HeartbeatTimeout: 0, } ctx := WithActivityOptions(ctx, ao)
Or to override a single option
ctx := WithTaskList(ctx, "exampleTaskList")
Input activity is either an activity name (string) or a function representing an activity that is getting scheduled. Input args are the arguments that need to be passed to the scheduled activity.
If the activity failed to complete then the future get error would indicate the failure, and it can be one of CustomError, TimeoutError, CanceledError, PanicError, GenericError. You can cancel the pending activity using context(workflow.WithCancel(ctx)) and that will fail the activity with error CanceledError.
ExecuteActivity returns Future with activity result or failure.
func ExecuteLocalActivity ¶ added in v0.5.1
ExecuteLocalActivity requests to run a local activity. A local activity is like a regular activity with some key differences:
• Local activity is scheduled and run by the workflow worker locally.
• Local activity does not need Cadence server to schedule activity task and does not rely on activity worker.
• No need to register local activity.
• The parameter activity to ExecuteLocalActivity() must be a function.
• Local activity is for short living activities (usually finishes within seconds).
• Local activity cannot heartbeat.
Context can be used to pass the settings for this local activity. For now there is only one setting for timeout to be set:
lao := LocalActivityOptions{ ScheduleToCloseTimeout: 5 * time.Second, } ctx := WithLocalActivityOptions(ctx, lao)
The timeout here should be relative shorter than the DecisionTaskStartToCloseTimeout of the workflow. If you need a longer timeout, you probably should not use local activity and instead should use regular activity. Local activity is designed to be used for short living activities (usually finishes within seconds).
Input args are the arguments that will to be passed to the local activity. The input args will be hand over directly to local activity function without serialization/deserialization because we don't need to pass the input across process boundary. However, the result will still go through serialization/deserialization because we need to record the result as history to cadence server so if the workflow crashes, a different worker can replay the history without running the local activity again.
If the activity failed to complete then the future get error would indicate the failure, and it can be one of CustomError, TimeoutError, CanceledError, PanicError, GenericError. You can cancel the pending activity by cancel the context(workflow.WithCancel(ctx)) and that will fail the activity with error CanceledError.
ExecuteLocalActivity returns Future with local activity result or failure.
func NewTimer ¶
NewTimer returns immediately and the future becomes ready after the specified duration d. The workflow needs to use this NewTimer() to get the timer instead of the Go lang library one(timer.NewTimer()). You can cancel the pending timer by cancel the Context (using context from workflow.WithCancel(ctx)) and that will cancel the timer. After timer is canceled, the returned Future become ready, and Future.Get() will return *CanceledError. The current timer resolution implementation is in seconds and uses math.Ceil(d.Seconds()) as the duration. But is subjected to change in the future.
func RequestCancelExternalWorkflow ¶ added in v0.5.1
RequestCancelExternalWorkflow can be used to request cancellation of an external workflow. Input workflowID is the workflow ID of target workflow. Input runID indicates the instance of a workflow. Input runID is optional (default is ""). When runID is not specified, then the currently running instance of that workflowID will be used. By default, the current workflow's domain will be used as target domain. However, you can specify a different domain of the target workflow using the context like:
ctx := WithWorkflowDomain(ctx, "domain-name")
RequestCancelExternalWorkflow return Future with failure or empty success result.
func SignalExternalWorkflow ¶ added in v0.5.1
func SignalExternalWorkflow(ctx Context, workflowID, runID, signalName string, arg interface{}) Future
SignalExternalWorkflow can be used to send signal info to an external workflow. Input workflowID is the workflow ID of target workflow. Input runID indicates the instance of a workflow. Input runID is optional (default is ""). When runID is not specified, then the currently running instance of that workflowID will be used. By default, the current workflow's domain will be used as target domain. However, you can specify a different domain of the target workflow using the context like:
ctx := WithWorkflowDomain(ctx, "domain-name")
SignalExternalWorkflow return Future with failure or empty success result.
type GenericError ¶
type GenericError = internal.GenericError
GenericError is returned from activity or child workflow when an implementations return error other than from workflow.NewCustomError() API.
type HeaderReader ¶ added in v0.8.4
type HeaderReader = internal.HeaderReader
HeaderReader is an interface to read information from cadence headers
type HeaderWriter ¶ added in v0.8.4
type HeaderWriter = internal.HeaderWriter
HeaderWriter is an interface to write information to cadence headers
type LocalActivityOptions ¶ added in v0.5.1
type LocalActivityOptions = internal.LocalActivityOptions
LocalActivityOptions doc
type PanicError ¶
type PanicError = internal.PanicError
PanicError contains information about panicked workflow/activity.
type RegisterOptions ¶
type RegisterOptions = internal.RegisterWorkflowOptions
RegisterOptions consists of options for registering a workflow
type RetryPolicy ¶ added in v0.12.1
type RetryPolicy = internal.RetryPolicy
RetryPolicy specify how to retry activity if error happens.
type Selector ¶
Selector must be used instead of native go select by workflow code. Use workflow.NewSelector(ctx) method to create a Selector instance.
func NewNamedSelector ¶
NewNamedSelector creates a new Selector instance with a given human readable name. Name appears in stack traces that are blocked on this Selector.
func NewSelector ¶
NewSelector creates a new Selector instance.
type SessionInfo ¶ added in v0.8.4
type SessionInfo = internal.SessionInfo
SessionInfo contains information of a created session. For now, exported fields are SessionID and HostName. SessionID is a uuid generated when CreateSession() or RecreateSession() is called and can be used to uniquely identify a session. HostName specifies which host is executing the session
func GetSessionInfo ¶ added in v0.8.4
func GetSessionInfo(ctx Context) *SessionInfo
GetSessionInfo returns the sessionInfo stored in the context. If there are multiple sessions in the context, (for example, the same context is used to create, complete, create another session. Then user found that the session has failed, and created a new one on it), the most recent sessionInfo will be returned.
This API will return nil if there's no sessionInfo in the context.
type SessionOptions ¶ added in v0.8.4
type SessionOptions = internal.SessionOptions
SessionOptions specifies metadata for a session. ExecutionTimeout: required, no default
Specifies the maximum amount of time the session can run
CreationTimeout: required, no default
Specifies how long session creation can take before returning an error
HeartbeatTimeout: optional, default 20s
Specifies the heartbeat timeout. If heartbeat is not received by server within the timeout, the session will be declared as failed
type Settable ¶
Settable is used to set value or error on a future. See more: workflow.NewFuture(ctx).
type TerminatedError ¶
type TerminatedError = internal.TerminatedError
TerminatedError returned when workflow was terminated.
type TimeoutError ¶
type TimeoutError = internal.TimeoutError
TimeoutError returned when activity or child workflow timed out.
func NewHeartbeatTimeoutError ¶
func NewHeartbeatTimeoutError(details ...interface{}) *TimeoutError
NewHeartbeatTimeoutError creates TimeoutError instance WARNING: This function is public only to support unit testing of workflows. It shouldn't be used by application level code.
func NewTimeoutError ¶
func NewTimeoutError(timeoutType shared.TimeoutType, details ...interface{}) *TimeoutError
NewTimeoutError creates TimeoutError instance. Use NewHeartbeatTimeoutError to create heartbeat TimeoutError WARNING: This function is public only to support unit testing of workflows. It shouldn't be used by application level code.
type UnknownExternalWorkflowExecutionError ¶ added in v0.8.1
type UnknownExternalWorkflowExecutionError = internal.UnknownExternalWorkflowExecutionError
UnknownExternalWorkflowExecutionError can be returned when external workflow doesn't exist
type Version ¶
Version represents a change version. See GetVersion call.
const DefaultVersion Version = internal.DefaultVersion
DefaultVersion is a version returned by GetVersion for code that wasn't versioned before
func GetVersion ¶
GetVersion is used to safely perform backwards incompatible changes to workflow definitions. It is not allowed to update workflow code while there are workflows running as it is going to break determinism. The solution is to have both old code that is used to replay existing workflows as well as the new one that is used when it is executed for the first time. GetVersion returns maxSupported version when is executed for the first time. This version is recorded into the workflow history as a marker event. Even if maxSupported version is changed the version that was recorded is returned on replay. DefaultVersion constant contains version of code that wasn't versioned before. For example initially workflow has the following code:
err = workflow.ExecuteActivity(ctx, foo).Get(ctx, nil)
it should be updated to
err = workflow.ExecuteActivity(ctx, bar).Get(ctx, nil)
The backwards compatible way to execute the update is
v := GetVersion(ctx, "fooChange", DefaultVersion, 1) if v == DefaultVersion { err = workflow.ExecuteActivity(ctx, foo).Get(ctx, nil) } else { err = workflow.ExecuteActivity(ctx, bar).Get(ctx, nil) }
Then bar has to be changed to baz:
v := GetVersion(ctx, "fooChange", DefaultVersion, 2) if v == DefaultVersion { err = workflow.ExecuteActivity(ctx, foo).Get(ctx, nil) } else if v == 1 { err = workflow.ExecuteActivity(ctx, bar).Get(ctx, nil) } else { err = workflow.ExecuteActivity(ctx, baz).Get(ctx, nil) }
Later when there are no workflow executions running DefaultVersion the correspondent branch can be removed:
v := GetVersion(ctx, "fooChange", 1, 2) if v == 1 { err = workflow.ExecuteActivity(ctx, bar).Get(ctx, nil) } else { err = workflow.ExecuteActivity(ctx, baz).Get(ctx, nil) }
It is recommended to keep the GetVersion() call even if single branch is left:
GetVersion(ctx, "fooChange", 2, 2) err = workflow.ExecuteActivity(ctx, baz).Get(ctx, nil)
The reason to keep it is: 1) it ensures that if there is older version execution still running, it will fail here and not proceed; 2) if you ever need to make more changes for “fooChange”, for example change activity from baz to qux, you just need to update the maxVersion from 2 to 3.
Note that, you only need to preserve the first call to GetVersion() for each changeID. All subsequent call to GetVersion() with same changeID are safe to remove. However, if you really want to get rid of the first GetVersion() call as well, you can do so, but you need to make sure: 1) all older version executions are completed; 2) you can no longer use “fooChange” as changeID. If you ever need to make changes to that same part like change from baz to qux, you would need to use a different changeID like “fooChange-fix2”, and start minVersion from DefaultVersion again. The code would looks like:
v := workflow.GetVersion(ctx, "fooChange-fix2", workflow.DefaultVersion, 1) if v == workflow.DefaultVersion { err = workflow.ExecuteActivity(ctx, baz, data).Get(ctx, nil) } else { err = workflow.ExecuteActivity(ctx, qux, data).Get(ctx, nil) }