Chilkat.TaskChain Class Overview

Chilkat.TaskChain manages a sequence of Chilkat.Task objects and runs them one after another. It is useful when multiple asynchronous Chilkat operations must execute in a defined order, while still allowing the entire chain to be queued, monitored, waited on, canceled, or run synchronously.

What the Class Is Used For

Use Chilkat.TaskChain when an application has multiple Chilkat asynchronous tasks that should run sequentially. Tasks are appended to the chain, then the chain is started with Run or RunSynchronously. Each task runs only after the previous task in the chain has finished.

Run Tasks Sequentially Append multiple Task objects and execute them one after another.
Queue the Chain Use Run to queue the full chain on Chilkat's internal thread pool.
Stop on Failure Use StopOnFailedTask to control whether the chain stops when a task fails.
Monitor Lifecycle Check Status, Live, Inert, and Finished.

Typical Workflow

  1. Create or obtain one or more Chilkat.Task objects, typically from methods whose names end in Async.
  2. Create a TaskChain object.
  3. Append each task in the desired order with Append.
  4. Optionally set StopOnFailedTask to control whether later tasks should run after a failed task.
  5. Start the chain with Run, or use RunSynchronously to execute the full chain synchronously.
  6. Monitor the chain with Status, Live, and Finished.
  7. Use Wait to wait for completion, with an optional timeout.
  8. After completion, inspect individual tasks with GetTask to retrieve task-specific results or diagnostics.
Sequential execution: A task chain does not run tasks in parallel. Each task in the chain runs one after the other, in the order it was appended.

Task Chain Lifecycle

Status StatusInt Meaning State Group
empty 1 No tasks have been appended to the chain. Inert
loaded 2 One or more tasks have been appended, but the chain has not yet been queued or started. Inert
queued 3 The chain is waiting in the internal thread pool queue. Live
running 4 The chain is currently running tasks sequentially. Live
canceled 5 The chain was canceled before it entered the running state. Finished
aborted 6 The chain was canceled while it was already running. Finished
completed 7 The chain completed. Finished
State helpers: Inert is true for empty or loaded. Live is true for queued or running. Finished is true for canceled, aborted, or completed.

Core Concepts

Concept Meaning Important Members
Task Chain A sequence of Task objects that run in order. Append, NumTasks, GetTask
Single-Chain Ownership A task can be part of only one task chain. Append
Thread Pool Execution The entire chain is queued to Chilkat's internal thread pool, then tasks run one after another. Run, Status
Synchronous Chain Execution The full chain can be run synchronously, returning only after all tasks have run. RunSynchronously
Stop on Failed Task Controls whether the chain stops if an individual task fails. StopOnFailedTask
Chain Cancellation Cancels a queued or running task chain. Cancel

Properties

Property Purpose Guidance
NumTasks Number of tasks contained in the task chain. Use before indexing with GetTask.
StopOnFailedTask Controls whether execution stops when an individual task fails. Default is true. If false, all tasks in the chain run even if some fail.
Status Text status of the chain. Use for readable lifecycle checks and logging.
StatusInt Numeric status of the chain. Use when integer comparisons are preferred.
Inert True if status is empty or loaded. Indicates the chain has not yet been queued or started.
Live True if status is queued or running. Indicates the chain is waiting to run or currently running.
Finished True if status is canceled, aborted, or completed. Use to determine when the chain is no longer active.
HeartbeatMs Milliseconds between AbortCheck callbacks for the Wait method. Default is 0, meaning no AbortCheck callbacks. The background task chain itself does not fire events.
LastErrorText Diagnostic information for the last method or property access. Check after failures or unexpected behavior.

Building a Chain

Method Purpose Important Details
Append Appends a Task to the chain. Can fail if the task is already part of another chain. A task can belong to only one chain.
GetTask Returns the Nth task in the chain. Indexing begins at 0. Use after completion to inspect each task's result, status, or diagnostic information.
NumTasks Returns the number of tasks in the chain. Use for iteration and to verify that the chain contains the expected number of tasks.
Append order matters: Tasks run in the same order they are appended to the chain.

Running and Waiting

Method Behavior Use When
Run Queues the task chain on Chilkat's internal thread pool. Each task runs one after the other. Use for normal asynchronous chain execution.
RunSynchronously Runs the task chain synchronously and returns after all tasks in the chain have run. Use when sequential execution is desired, but background execution is not.
Wait Waits until the chain completes, is canceled, is aborted, or the timeout expires. Pass 0 to wait indefinitely. Returns false if the chain has not been started with Run or if the timeout expires.
SleepMs Sleeps the calling thread for a specified number of milliseconds. Useful when polling Status or Finished in a loop.
Wait callback note: HeartbeatMs controls AbortCheck callbacks for Wait. An asynchronous task chain running in a background thread does not fire task-chain events; the event callbacks pertain only to the Wait method.

Failure Handling

StopOnFailedTask controls what happens when one task in the chain fails. Task failure is defined by the standard LastMethodSuccess property of the underlying task object.

StopOnFailedTask Behavior Use When
true The chain stops execution if any individual task fails. Use when later tasks depend on earlier tasks succeeding. This is the default.
false The chain continues and runs all tasks even if some tasks fail. Use when tasks are independent and each should be attempted regardless of previous failures.
Inspect individual tasks: The task chain reports the lifecycle of the chain. To understand which task failed and why, retrieve tasks with GetTask and inspect each task's result and diagnostic information.

Cancellation Behavior

Method Behavior Guidance
Cancel Cancels execution of the asynchronous task chain. Use after Run when a queued or running chain should be canceled. A queued chain may become canceled; a running chain may become aborted.
Wait Can be used after cancellation to wait until the chain reaches a finished state. Useful because cancellation of running work is not necessarily instantaneous.
Finished states: After cancellation, check Status or Finished to determine when the chain is no longer active.

Method Summary by Category

Category Methods / Properties Purpose
Build chain Append, NumTasks, GetTask Add tasks, count tasks, and retrieve individual tasks by index.
Run and wait Run, RunSynchronously, Wait, SleepMs Start the chain asynchronously, run it synchronously, wait for completion, or sleep while polling.
Cancel Cancel Cancel a queued or running task chain.
Status Status, StatusInt, Inert, Live, Finished Determine where the chain is in its lifecycle.
Failure policy StopOnFailedTask Choose whether the chain stops on the first failed task or continues through all tasks.
Wait callbacks HeartbeatMs Control AbortCheck callback frequency for the Wait method.
Diagnostics LastErrorText Read diagnostic information after failed or unexpected task-chain operations.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Chain remains empty Append, NumTasks Confirm tasks were appended successfully. Check the return value of Append.
Append fails Append, LastErrorText A task can be part of only one chain. Verify the task was not already added to another chain.
Chain does not start Run, Status, LastErrorText Confirm the chain is loaded with at least one task and that Run returned true.
Wait returns false Wait The chain may not have been started with Run, or the wait timeout may have expired.
Later tasks did not run StopOnFailedTask If StopOnFailedTask is true, the chain stops when an individual task fails.
Need to know which task failed GetTask, NumTasks Iterate the tasks and inspect each task's status, result, and error text.
Cancellation appears delayed Cancel, Status, Wait A running chain may need time to notice cancellation and transition to a finished state.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected append, run, wait, cancel, or task retrieval behavior.

Common Pitfalls

Pitfall Better Approach
Expecting tasks in the chain to run in parallel. A task chain runs tasks sequentially. Use separate tasks or chains if independent work should run concurrently.
Appending a task that already belongs to another chain. Each task can be part of only one chain. Create or obtain a separate task if needed.
Forgetting to call Run. A loaded chain does not execute until Run or RunSynchronously is called.
Assuming the chain always continues after a failed task. The default StopOnFailedTask value is true, so the chain stops on task failure unless changed.
Using only the chain status to diagnose a task failure. Retrieve individual tasks with GetTask and inspect the task-level result and diagnostics.
Assuming Wait starts the chain. Call Run first. Wait only waits for a chain that has already been started.
Expecting background task-chain events to fire. Task-chain event callbacks pertain only to Wait, not the background thread running the chain.

Best Practices

Recommendation Reason
Append tasks in the exact order they must execute. The chain runs tasks sequentially in append order.
Check the return value of Append. Appending can fail if the task already belongs to another chain.
Set StopOnFailedTask deliberately. The default is true, which is correct for dependent tasks but not always for independent tasks.
Use Run for asynchronous execution and RunSynchronously for blocking execution. This makes the chain's execution model explicit.
Use Wait with a finite timeout in responsive applications. It avoids blocking indefinitely while still allowing controlled waiting.
After completion, inspect individual tasks for detailed results. The chain coordinates execution; each task contains its own result and error information.
Check LastErrorText after task-chain method failures. It provides diagnostic details for failed append, run, wait, cancel, or retrieval operations.

Summary

Chilkat.TaskChain is the control object for running a sequence of Chilkat.Task objects in order. It can hold multiple tasks, queue the chain on Chilkat's internal thread pool, run the chain synchronously, wait for completion, cancel execution, and expose lifecycle status through properties such as Status, Live, Inert, and Finished.

The most important practical guidance is to append tasks in the required execution order, remember that a task can belong to only one chain, set StopOnFailedTask according to whether tasks are dependent or independent, call Run or RunSynchronously to start execution, and inspect the individual tasks with GetTask after the chain finishes.