Overview
Task types define the structures for task distribution, polling, and completion in Cadence. Tasks are the fundamental unit of work dispatched to workers. Source Locations:common/types/shared.go- Common task typescommon/types/matching.go- Matching service task types
Task List Types
TaskList
Identifies a task list for task distribution.Name of the task list. Must be unique within a domain.
Kind of task list (Normal or Sticky)
- Use descriptive names:
order-processing,payment-verification - Include worker capabilities:
gpu-tasks,high-memory-tasks - Avoid special characters except hyphens and underscores
TaskListKind
Type of task list.Regular task list for general task distribution
Sticky task list for routing to specific worker (decision tasks only)
- Keep workflow state cached in worker memory
- Reduce history loading overhead
- Improve decision task latency by ~90%
- Automatically fall back to normal task list if worker unavailable
TaskListType
Type of tasks in a task list.Task list for decision tasks
Task list for activity tasks
TaskListMetadata
Metadata for task list routing.Rate limit for task dispatch from this task list
TaskListStatus
Status information for a task list.Approximate number of pending tasks in backlog
Current read position in task queue
Last acknowledged task ID
Current task dispatch rate
Current task ID allocation range
TaskIDBlock
Range of task IDs allocated to a task list.Task List Partition Types
TaskListPartitionMetadata
Metadata for a task list partition.Partition identifier
Host currently owning this partition
TaskListPartitionConfig
Configuration for task list partitioning.Configuration version for optimistic concurrency
Number of partitions for task polling
Number of partitions for task addition
- Start with 1 partition (no partitioning)
- Scale to 4-8 partitions for high throughput
- Use 16+ partitions for very high scale (>1000 tasks/sec)
Decision Task Types
PollForDecisionTaskRequest
Request to poll for a decision task.Domain to poll from
Task list to poll
Worker identity (typically hostname and process ID)
Checksum of worker binary for bad binary detection
PollForDecisionTaskResponse
Response containing a decision task.Opaque token for completing/failing the task
Workflow execution this task belongs to
The workflow type
Event ID of previous decision task (for incremental history)
Event ID when this decision task started
Retry attempt number for this decision task
Approximate task backlog size
Workflow execution history (full or incremental)
Token to fetch additional history if paginated
Workflow query to answer (deprecated, use Queries)
Map of query ID to workflow query
Normal (non-sticky) task list for the workflow
Next event ID to be assigned
RespondDecisionTaskCompletedRequest
Request to complete a decision task.Task token from poll response
List of decisions to execute
Opaque execution context to persist
Worker identity
Sticky task list configuration
Return a new decision task immediately if available
Force creation of a new decision task
Worker binary checksum
Results for queries that were processed
RespondDecisionTaskCompletedResponse
Response after completing a decision task.New decision task if ReturnNewDecisionTask was true
Activities to execute locally (same worker)
RespondDecisionTaskFailedRequest
Request to fail a decision task.Task token from poll response
Reason for failure
Additional failure details
Worker identity
StickyExecutionAttributes
Attributes for sticky execution.Sticky task list for this worker
Timeout before falling back to normal task list (typically 5-10 seconds)
Activity Task Types
PollForActivityTaskRequest
Request to poll for an activity task.Domain to poll from
Task list to poll
Worker identity
Metadata for task routing
PollForActivityTaskResponse
Response containing an activity task.Opaque token for completing/failing the task
Parent workflow execution
Activity identifier within the workflow
Type of activity to execute
Serialized activity input
When activity was first scheduled (nanoseconds)
Maximum time from schedule to completion
When this attempt started
Maximum time from start to completion
Maximum time between heartbeats
Current retry attempt number (0-based)
When this retry attempt was scheduled
Details from last heartbeat (for resuming)
Parent workflow type
Parent workflow domain name
Context propagation headers from workflow
RespondActivityTaskCompletedRequest
Request to complete an activity task.Task token from poll response
Serialized activity result
Worker identity
RespondActivityTaskCompletedByIDRequest
Complete an activity by domain, workflow ID, and activity ID.Domain name
Workflow ID
Run ID (optional, uses current run if omitted)
Activity ID
Serialized result
RespondActivityTaskFailedRequest
Request to fail an activity task.Task token from poll response
Failure reason/error message
Serialized failure details
RespondActivityTaskFailedByIDRequest
Fail an activity by identifiers.RespondActivityTaskCanceledRequest
Request to cancel an activity task.Task token from poll response
Cancellation details
RecordActivityTaskHeartbeatRequest
Request to record an activity heartbeat.Task token from poll response
Progress details (can be used to resume on retry)
Worker identity
RecordActivityTaskHeartbeatResponse
Response after recording heartbeat.Whether the activity has been requested to cancel
Task Source Types
TaskSource
Source of a task.Task added directly from history service (sync match)
Task loaded from persistent backlog (async match)
Poller Information Types
PollerInfo
Information about an active poller.Last poll timestamp (nanoseconds)
Worker identity string
Poll rate from this worker
Task List Description Types
DescribeTaskListRequest
Request to describe a task list.Domain name
Task list to describe
Type (Decision or Activity)
Include detailed status information
DescribeTaskListResponse
Response with task list information.List of active pollers
Task list status if requested
Activity Dispatch Types
ActivityLocalDispatchInfo
Information for locally dispatching an activity.Activity identifier
When activity was scheduled
When activity started
When this attempt was scheduled
Task token for completing the activity
ActivityTaskDispatchInfo
Detailed dispatch information for an activity.Best Practices
Task List Design
-
Naming Strategy
- One task list per worker type
- Separate decision and activity task lists
- Use descriptive names:
order-processing-activities
-
Partitioning
- Start with no partitioning
- Add partitions when >100 tasks/sec
- Monitor backlog and adjust
-
Sticky Execution
- Always enable for decision tasks
- Use 5-10 second sticky timeout
- Monitor fallback rate
Polling Best Practices
-
Poll Timeout
- Set context timeout: 60-90 seconds
- Handle empty responses gracefully
- Implement exponential backoff on errors
-
Worker Identity
- Include hostname and process ID
- Add version information
- Use for debugging and monitoring
-
Concurrency
- Start with 10-20 pollers per worker
- Scale based on task throughput
- Monitor task latency
Task Completion
-
Idempotency
- Task tokens ensure idempotency
- Safe to retry completion
- Handle duplicate completion gracefully
-
Timeouts
- Set appropriate activity timeouts
- Use heartbeat for long tasks (>30 sec)
- Record progress in heartbeat details
-
Error Handling
- Return structured errors
- Use retry policies appropriately
- Log task failures
Heartbeat Strategy
-
Frequency
- Heartbeat at 1/3 of timeout
- Example: 30s timeout → 10s heartbeat
- Reduce frequency for stable tasks
-
Progress Tracking
- Store resumable state in details
- Use for retry recovery
- Keep details small (less than 32KB)
-
Cancellation Check
- Check
CancelRequestedin response - Cleanup and exit if canceled
- Record final state in cancellation details
- Check
Monitoring & Metrics
Key Metrics
task.poll.latency: Time to receive tasktask.execution.latency: Task processing timetask.backlog.size: Pending task counttask.sync.match.rate: Sync match success ratepoller.count: Active poller count
Health Indicators
- High sync match rate (>90%): Healthy
- Growing backlog: Need more workers
- High poll latency: Reduce poll timeout or add partitions
- Low poller count: Workers may be down
See Also
- Frontend Service API - Task polling and completion APIs
- Matching Service API - Task distribution internals
- Workflow Types - Decision and activity types