.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 =============== Resumable tasks =============== **[scheduler.resumable_tasks]** Functions to suspend task execution at a specific point and signal to resume it later. .. code:: cpp // Defined in header using oneapi::tbb::task::suspend_point = /* implementation-defined */; template < typename Func > void oneapi::tbb::task::suspend( Func ); void oneapi::tbb::task::resume( oneapi::tbb::task::suspend_point ); Requirements: * The ``Func`` type must meet the :doc:`SuspendFunc requirements <../../named_requirements/task_scheduler/suspend_func>`. The ``oneapi::tbb::task::suspend`` function called within a running task suspends execution of the task and switches the thread to participate in other oneTBB parallel work. This function accepts a user callable object with the current execution context ``oneapi::tbb::task::suspend_point`` as an argument. The user-specified callable object is executed by the calling thread. The ``oneapi::tbb::task::suspend_point`` context tag must be passed to the ``oneapi::tbb::task::resume`` function to trigger a program execution at the suspended point. The ``oneapi::tbb::task::resume`` function can be called at any point of an application, even on a separate thread. In this regard, this function acts as a signal for the task scheduler. .. note:: There are no guarantees that the same thread that called ``oneapi::tbb::task::suspend`` continues execution after the suspended point. However, these guarantees are provided for the outermost blocking oneTBB calls (such as ``oneapi::tbb::parallel_for`` and ``oneapi::tbb::flow::graph::wait_for_all``) and ``oneapi::tbb::task_arena::execute`` calls. Example ------- .. code:: cpp // Parallel computation region oneapi::tbb::parallel_for(0, N, [&](int) { // Suspend the current task execution and capture the context oneapi::tbb::task::suspend([&] (oneapi::tbb::task::suspend_point tag) { // Dedicated user-managed activity that processes async requests. async_activity.submit(tag); // could be OpenCL/IO/Database/Network etc. }); // execution will be resumed after this function }); .. code:: cpp // Dedicated user-managed activity: // Signal to resume execution of the task referenced by the oneapi::tbb::task::suspend_point // from a dedicated user-managed activity oneapi::tbb::task::resume(tag);