Documentation
¶
Index ¶
- Variables
- func GetLogger(ctx Context) *zap.Logger
- func GetMetricsScope(ctx Context) interface{}
- func Go(ctx Context, f func(ctx Context))
- func IsCanceledError(ctx Context, err error) bool
- func NewFuture(ctx Context) (Future, Settable)
- func Now(ctx Context) time.Time
- 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) error
- type ActivityOptions
- type BatchFuture
- type CanceledError
- type ChildWorkflowFuture
- type ChildWorkflowOptions
- type Context
- func NewDisconnectedContext(parent Context) (Context, func())
- func WithActivityOptions(ctx Context, options ActivityOptions) Context
- func WithBackend(parent Context, w Workflow) Context
- func WithChildOptions(ctx Context, cwo ChildWorkflowOptions) Context
- func WithRetryPolicy(ctx Context, retryPolicy RetryPolicy) Context
- func WithTaskList(ctx Context, name string) Context
- func WithValue(parent Context, key interface{}, val interface{}) Context
- func WithWorkflowDomain(ctx Context, name string) Context
- func WithWorkflowTaskList(ctx Context, name string) Context
- type CustomError
- type Future
- type IInfo
- type RetryPolicy
- type Selector
- type Settable
- type Workflow
Constants ¶
This section is empty.
Variables ¶
var BackendContextKey = "BackendContextKey"
Functions ¶
func GetMetricsScope ¶
func GetMetricsScope(ctx Context) interface{}
func IsCanceledError ¶
func SetQueryHandler ¶
Types ¶
type ActivityOptions ¶
type ActivityOptions = internal.ActivityOptions
ActivityOptions specifies how activities are scheduled and executed. Fields include: - StartToCloseTimeout - ScheduleToStartTimeout - RetryPolicy - TaskQueue (optional)
Attached to context via:
ctx = workflow.WithActivityOptions(ctx, ActivityOptions{...})
Enables customizing timeouts and retries on a per-call basis.
type BatchFuture ¶ added in v1.0.13
type BatchFuture = internal.BatchFuture
BatchFuture is an abstraction over multiple futures in workflows. Returned from: - NewBatchFuture
Provides methods: - IsReady() – non-blocking completion check - Get(ctx, &result) – blocks until complete - GetFutures() – returns all wrapped futures
func NewBatchFuture ¶ added in v1.0.13
type CanceledError ¶
type CanceledError = internal.CanceledError
CanceledError indicates that a workflow or activity was canceled, usually due to context cancellation.
Should be checked in activities to exit early:
select {
case <-ctx.Done():
return workflow.CanceledError{}
case val := <-input:
return val
}
Used extensively in graceful shutdowns, parent-child propagation, and timed operations.
type ChildWorkflowFuture ¶
type ChildWorkflowFuture = internal.ChildWorkflowFuture
ChildWorkflowFuture is a specialization of Future with additional context for child workflows. Might provide: - Execution metadata (WorkflowID, RunID) - Cancellation or signal APIs
Useful when tracking the lifecycle of child workflows or reacting to failures.
Returned from ExecuteChildWorkflow() in backends.
func ExecuteChildWorkflow ¶
func ExecuteChildWorkflow(ctx Context, childWorkflow interface{}, args ...interface{}) ChildWorkflowFuture
type ChildWorkflowOptions ¶
type ChildWorkflowOptions = internal.ChildWorkflowOptions
ChildWorkflowOptions configures execution of a child workflow. Includes options like: - TaskQueue - RetryPolicy - ExecutionTimeout - WorkflowIDReusePolicy
Set with:
ctx = workflow.WithChildOptions(ctx, options)
These mirror ActivityOptions but are tailored for workflow-to-workflow calls.
type Context ¶
Context is the core execution context used across all workflow and activity logic. It allows passing metadata, cancellation, and timeout control across workflow and activity boundaries. It abstracts over Temporal/Cadence's context propagation and supports attaching backend-specific values.
Key capabilities: - Provides scoped values via `WithValue`. - Propagates cancellation (e.g., parent-child workflow relationships). - Used to access execution-specific APIs (logger, metrics, backend, etc.).
This is the primary handle passed into most framework functions such as:
ExecuteActivity(ctx, activityFn, args...) GetInfo(ctx) WithActivityOptions(ctx, options) WithBackend(ctx, w) GetLogger(ctx)
Example Usage:
func MyWorkflow(ctx workflow.Context) error {
logger := workflow.GetLogger(ctx)
logger.Info("starting my workflow")
options := workflow.ActivityOptions{
StartToCloseTimeout: time.Minute,
}
ctx = workflow.WithActivityOptions(ctx, options)
return workflow.ExecuteActivity(ctx, MyActivity, "input").Get(ctx, nil)
}
Note: Context is interface-based and backend-aware — calling GetBackend(ctx) lets you retrieve the registered workflow runtime implementation (Temporal/Cadence), enabling pluggable backends under the same abstraction.
func NewDisconnectedContext ¶
func WithActivityOptions ¶
func WithActivityOptions(ctx Context, options ActivityOptions) Context
func WithBackend ¶
func WithChildOptions ¶
func WithChildOptions(ctx Context, cwo ChildWorkflowOptions) Context
func WithRetryPolicy ¶
func WithRetryPolicy(ctx Context, retryPolicy RetryPolicy) Context
func WithTaskList ¶
func WithWorkflowDomain ¶
func WithWorkflowTaskList ¶
type CustomError ¶
type CustomError = internal.CustomError
CustomError represents a domain-specific error that can be passed across activity/workflow boundaries. Encodes a string "reason" and optional structured "details".
Example:
return workflow.NewCustomError("validation_failed", map[string]interface{}{"field": "name"})
Use workflow errors.As() to unwrap and inspect the details in the caller. Useful for safe, structured cross-boundary error handling.
func NewCustomError ¶
func NewCustomError(ctx Context, reason string, details ...interface{}) CustomError
type Future ¶
Future is an abstraction over asynchronous results in workflows. Returned from: - ExecuteActivity - ExecuteChildWorkflow
Provides methods: - Get(ctx, &result) – blocks until complete - IsReady() – non-blocking completion check
Enables concurrency patterns and chaining:
future := workflow.ExecuteActivity(ctx, MyActivity) var result string err := future.Get(ctx, &result)
func ExecuteActivity ¶
type IInfo ¶
IInfo provides execution metadata about the current workflow instance. Includes fields such as: - WorkflowType - WorkflowID - RunID - TaskQueue - Namespace
Accessed via:
info := workflow.GetInfo(ctx)
Useful for diagnostics, routing logic, or emitting contextual logs and metrics.
type RetryPolicy ¶
type RetryPolicy = internal.RetryPolicy
RetryPolicy defines retry behavior for workflows or activities. Fields include: - InitialInterval - BackoffCoefficient - MaximumAttempts - NonRetryableErrorTypes
Example:
workflow.WithActivityOptions(ctx, ActivityOptions{
RetryPolicy: RetryPolicy{
InitialInterval: 1 * time.Second,
MaximumAttempts: 5,
BackoffCoefficient: 2.0,
},
})
Helps enforce robustness in distributed calls.
type Selector ¶ added in v1.0.11
Selector provides a deterministic alternative to Go's select statement in workflows. It allows waiting on multiple futures in a deterministic way.
Usage:
selector := workflow.NewSelector(ctx)
selector.AddFuture(future1, func(f workflow.Future) { ... })
selector.AddFuture(future2, func(f workflow.Future) { ... })
selector.Select(ctx) // blocks until one future is ready
func NewSelector ¶ added in v1.0.11
type Settable ¶
Settable represents a writable Future — allows manual fulfillment of a result or error. Primarily used for internal mocking, stubbing, or combining multiple futures.
Example (mocked implementation):
f, s := workflow.NewFuture()
s.Set("value", nil)
Used internally by plugins or the future helper package.
type Workflow ¶
Workflow represents the core interface for a workflow engine backend (e.g., Temporal or Cadence). It defines methods to: - Execute activities and child workflows - Manage context and metadata propagation - Access logging, metrics, and custom behavior
This interface is implemented differently for each backend (e.g., `internal_temporal.go`, `internal_cadence.go`). It is attached to a workflow.Context using `WithBackend(ctx, workflowImpl)` and later retrieved using `GetBackend(ctx)`.
Example:
backend, ok := workflow.GetBackend(ctx)
if ok {
backend.ExecuteActivity(ctx, SomeActivity, args...)
}
Source Files