Termination detection#

This example demonstrates how to use HPX’s termination detection API to ensure all asynchronous work has completed before shutting down the runtime. This is particularly useful when you need to guarantee that all posted tasks have finished execution before the application exits.

Overview#

The termination detection API provides a way to wait for all local HPX-threads to complete their work. This is essential in scenarios where you spawn asynchronous tasks using hpx::post or hpx::async and need to ensure they all finish before the runtime shuts down.

The API supports several use cases:

  • Basic usage: Wait indefinitely for all tasks to complete

  • Timeout: Wait for a specified duration

  • Deadline: Wait until a specific time point

  • Cancellation: Support for cancellation tokens to interrupt the wait

Setup#

The source code for this example can be found here: termination_detection.cpp.

To compile this program, go to your HPX build directory (see Building HPX for information on configuring and building HPX) and enter:

$ make examples.quickstart.termination_detection

To run the program type:

$ ./bin/termination_detection

This will execute all four examples demonstrating different usage patterns of the termination detection API.

Walkthrough#

The example demonstrates four different usage patterns of the termination detection API. Let’s examine each one:

Basic usage#

The simplest form waits indefinitely for all local threads to complete:

This is useful when you want to ensure all work is done before shutting down, and you don’t have time constraints.

Timeout usage#

You can specify a maximum duration to wait:

The function returns true if all threads completed within the timeout, or false if the timeout elapsed. This is useful when you want to give tasks a reasonable amount of time to complete but don’t want to wait indefinitely.

Deadline usage#

Similar to timeout, but you specify an absolute time point:

This is useful when you have a specific deadline by which all work must be completed.

Cancellation support#

The most flexible form supports cancellation tokens:

This allows external control over the wait operation. You can request cancellation from another thread, which is useful in scenarios like graceful shutdown with user interruption support.

API Reference#

The termination detection API is available in the hpx::local namespace:

void hpx::local::termination_detection()#

Wait indefinitely for all local HPX-threads to complete.

bool hpx::local::termination_detection(hpx::chrono::steady_duration const &timeout)#

Wait for all local HPX-threads to complete, with a timeout.

Parameters

timeout – Maximum duration to wait

Returns

true if all threads completed, false if timeout elapsed

bool hpx::local::termination_detection(hpx::chrono::steady_time_point const &deadline)#

Wait for all local HPX-threads to complete, until a deadline.

Parameters

deadline – Absolute time point to wait until

Returns

true if all threads completed, false if deadline passed

bool hpx::local::termination_detection(hpx::stop_token stop_token, hpx::chrono::steady_duration const &timeout)#

Wait for all local HPX-threads to complete, with cancellation support.

Parameters

  • stop_token – Token that can be used to request cancellation

  • timeout – Maximum duration to wait (defaults to maximum duration)

Returns

true if all threads completed, false if timeout elapsed or stop was requested

Use cases#

The termination detection API is particularly useful in the following scenarios:

  • Graceful shutdown: Ensure all background tasks complete before exiting

  • Testing: Verify that all spawned tasks have finished in unit tests

  • Batch processing: Wait for all work items in a batch to complete

  • Resource cleanup: Ensure all tasks using shared resources have finished before cleanup

See also#