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

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#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#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/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:

#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:

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:

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/src/GraphCtrl/GraphElement/GElement.h) around line 251:

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#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 and practical examples in 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}