# How to Configure Node Timeouts in CGraph Pipelines: A Complete Guide

> Master CGraph node timeouts with our guide. Learn to use setTimeout to abort or wait for pipeline completion, ensuring robust execution. Read now!

- Repository: [Chunel/cgraph](https://github.com/chunelfeng/cgraph)
- Tags: how-to-guide
- Published: 2026-02-27

---

**Set a timeout on any CGraph pipeline node by calling `setTimeout(CMSec timeout, GElementTimeoutStrategy strategy)` on the element, where `AS_ERROR` aborts the pipeline on timeout and `HOLD_BY_PIPELINE` waits for completion.**

CGraph is a high-performance C++ task scheduling engine that lets you build complex data pipelines. Configuring node timeouts ensures that long-running tasks don't block your entire workflow, providing resilience against hanging operations.

## Understanding Timeout Configuration in CGraph

CGraph implements timeouts at the `GElement` level, meaning any node, group, or region can have independent timeout constraints. The system tracks execution duration and applies your chosen strategy when limits are exceeded.

### Core Timeout Components

The timeout mechanism relies on three key components defined in the source:

- **`timeout_`** – A `CMSec` (millisecond) value stored in `GElement` that defines the maximum execution time. Declared in [[`src/GraphCtrl/GraphElement/GElement.h`](https://github.com/chunelfeng/cgraph/blob/main/src/GraphCtrl/GraphElement/GElement.h)](https://github.com/chunelfeng/cgraph/blob/main/src/GraphCtrl/GraphElement/GElement.h#L55-L61).
- **`CGRAPH_DEFAULT_ELEMENT_TIMEOUT`** – Defaults to `0`, meaning no timeout is enforced unless explicitly configured. Defined in [[`src/GraphCtrl/GraphElement/GElementDefine.h`](https://github.com/chunelfeng/cgraph/blob/main/src/GraphCtrl/GraphElement/GElementDefine.h)](https://github.com/chunelfeng/cgraph/blob/main/src/GraphCtrl/GraphElement/GElementDefine.h#L19).
- **`setTimeout()`** – The public API method that configures both duration and strategy behavior.

### Timeout Strategies Explained

The `GElementTimeoutStrategy` enum in [[`GElementDefine.h`](https://github.com/chunelfeng/cgraph/blob/main/GElementDefine.h)](https://github.com/chunelfeng/cgraph/blob/main/src/GraphCtrl/GraphElement/GElementDefine.h#L48-L52) defines how the pipeline responds when a timeout occurs:

- **`AS_ERROR`** (default) – Marks the element as `TIMEOUT`, aborts the pipeline, and returns a failure `CStatus`.
- **`HOLD_BY_PIPELINE`** – The pipeline continues executing other ready elements but blocks the final `process()` return until the timed-out element completes.
- **`NO_HOLD`** – Ignores the timeout entirely. This is strongly discouraged as it can lead to undefined behavior on some platforms.

## How to Set Node Timeouts in CGraph Pipelines

Configure timeouts after registering elements but before calling `process()`. The `setTimeout()` method accepts milliseconds and an optional strategy parameter.

### Basic Node Timeout Configuration

This example demonstrates setting a 300ms timeout with the default `AS_ERROR` strategy:

```cpp
#include "CGraph.h"
using namespace CGraph;

void configure_node_timeout() {
    GPipelinePtr pipeline = GPipelineFactory::create();
    
    GElementPtr node_a = nullptr;
    pipeline->registerGElement<MyNode>(&node_a, {}, "nodeA");
    
    // Set 300ms timeout - pipeline will fail if node exceeds this duration
    node_a->setTimeout(300, GElementTimeoutStrategy::AS_ERROR);
    
    CStatus status = pipeline->process();
    if (!status.isOK()) {
        std::cout << "Timeout occurred: " << status.getInfo() << "\n";
    }
    
    GPipelineFactory::remove(pipeline);
}

```

To remove a timeout, pass `0` as the duration:

```cpp
node_a->setTimeout(0);  // Disables timeout, returns to default behavior

```

### Configuring Timeouts on Groups

Timeouts apply to any `GElement` subclass, including clusters and regions. The engine monitors the aggregate execution time of all elements within the group:

```cpp
GElementPtr cluster = nullptr;
pipeline->registerGElement<GCluster>(&cluster, {node_a, node_b}, "myCluster");

// 500ms timeout for the entire cluster execution
cluster->setTimeout(500, GElementTimeoutStrategy::AS_ERROR);

```

### Checking Timeout Status Inside Custom Nodes

Custom node implementations can query their timeout status during execution using the protected `isTimeout()` method defined in [[`GElement.h`](https://github.com/chunelfeng/cgraph/blob/main/GElement.h)](https://github.com/chunelfeng/cgraph/blob/main/src/GraphCtrl/GraphElement/GElement.h) around line 251:

```cpp
class MonitoredNode : public GNode {
public:
    CStatus run() override {
        // Perform computation
        for (int i = 0; i < 1000; i++) {
            if (this->isTimeout()) {
                std::cout << "Detected timeout, performing cleanup\n";
                return CStatus::error("early_exit");
            }
            // ... work ...
        }
        return CStatus::success();
    }
};

```

## Timeout Strategy Behavior in Practice

Understanding the distinction between `AS_ERROR` and `HOLD_BY_PIPELINE` is crucial for pipeline design:

- **AS_ERROR** is appropriate for real-time systems where stale results are unacceptable. When triggered, the pipeline immediately begins shutdown, and `process()` returns an error status containing timeout details.

- **HOLD_BY_PIPELINE** suits batch processing scenarios where completion is mandatory but you want to log or alert on slow operations. The pipeline continues scheduling independent branches while waiting for the slow element at the synchronization point.

The tutorial file [[`tutorial/T22-Timeout.cpp`](https://github.com/chunelfeng/cgraph/blob/main/tutorial/T22-Timeout.cpp)](https://github.com/chunelfeng/cgraph/blob/main/tutorial/T22-Timeout.cpp#L35-L38) demonstrates both patterns in a runnable example, showing how to set timeouts, execute the pipeline, and handle the resulting `CStatus`.

## Summary

- Configure node timeouts in CGraph by calling `setTimeout(CMSec, GElementTimeoutStrategy)` on any `GElement` before executing the pipeline.
- Choose `AS_ERROR` to abort the pipeline on timeout, or `HOLD_BY_PIPELINE` to wait for completion while continuing other work.
- Set timeout to `0` to disable time limits and restore default behavior.
- Access timeout status inside custom nodes via the protected `isTimeout()` method for early exit logic.
- Reference implementation details in [`src/GraphCtrl/GraphElement/GElement.h`](https://github.com/chunelfeng/cgraph/blob/main/src/GraphCtrl/GraphElement/GElement.h) and practical examples in [`tutorial/T22-Timeout.cpp`](https://github.com/chunelfeng/cgraph/blob/main/tutorial/T22-Timeout.cpp).

## Frequently Asked Questions

### How do I disable a timeout after setting it?

Pass `0` as the timeout value to `setTimeout()`. According to the implementation in [`GElement.h`](https://github.com/chunelfeng/cgraph/blob/main/GElement.h), setting `timeout_` to `0` (which matches `CGRAPH_DEFAULT_ELEMENT_TIMEOUT`) disables the timeout mechanism entirely, allowing the element to run without time constraints.

### Can I set different timeout strategies for different nodes in the same pipeline?

Yes. Each `GElement` maintains its own `timeout_` value and strategy independently. You can configure one node with `AS_ERROR` (strict real-time requirements) while another uses `HOLD_BY_PIPELINE` (batch tolerance) within the same `GPipeline` instance.

### What happens if a node times out but has already completed execution?

The timeout check occurs during execution monitoring. If the node completes before the duration expires, the timeout never triggers. The `CMSec` counter tracks elapsed execution time, and the strategy only applies when the limit is exceeded during the `run()` or `process()` lifecycle.

### Where can I find a complete working example of timeout configuration?

The official tutorial [`tutorial/T22-Timeout.cpp`](https://github.com/chunelfeng/cgraph/blob/main/tutorial/T22-Timeout.cpp) in the chunelfeng/cgraph repository provides a complete, runnable demonstration. It shows how to register nodes, set millisecond timeouts with different strategies, execute the pipeline, and inspect the returned `CStatus` for timeout errors.