#include <userver/concurrent/background_task_storage.hpp>

Detailed Description

A storage that allows one to start detached tasks; cancels and waits for unfinished tasks completion at the destructor. Provides CancelAndWait to explicitly cancel tasks (recommended).

Usable for detached tasks that capture references to resources with a limited lifetime. You must guarantee that the resources are available while the BackgroundTaskStorage is alive.

Performance considerations

Tasks remove themselves from the BackgroundTaskStorage on completion, so there is no memory leak.

Warning: The implementation is optimized for spawning tasks. Waiting for remaining tasks may be slow CPU-wise. As a guideline, do not create BackgroundTaskStorage instances for each request, use std::vector<Task> for storing per-request child tasks instead.

Usage synopsis

    std::string x = kString;
    std::string y;
    {
        // You must guarantee that 'x' and 'y' are alive during 'bts' lifetime.
        concurrent::BackgroundTaskStorage bts;
 
        bts.AsyncDetach("task", [&x, &y] {
            engine::InterruptibleSleepFor(20s);
            EXPECT_TRUE(engine::current_task::ShouldCancel());
            y = std::move(x);
        });
 
        do_stuff();
 
        // It is recommended to call CancelAndWait explicitly for the clarity of
        // tasks' lifetime. BTS destructor calls CancelAndWait implicitly as well.
        bts.CancelAndWait();
    }

Lifetime of task's captures

All the advice from utils::Async is applicable here.

BackgroundTaskStorage is always stored as a class field. Tasks that are launched inside it (or moved inside it, for BackgroundTaskStorageCore) can safely access fields declared before it, but not after it:

class Frobnicator {
public:
    // ...
 
    void Launch(const Dependencies& stuff);
 
private:
    // ...
    Foo foo_;
    concurrent::BackgroundTaskStorage bts_;
    Bar bar_;
    // ...
};
 
void Frobnicator::Launch(const Dependencies& stuff) {
    int x{};
    bts_.AsyncDetach("task", [this, &stuff, &x] {
        // BUG! All local variables will be gone.
        // They should be captured by move or by copy.
        Use(x);
 
        // OK, because foo_ will be destroyed after bts_.
        Use(foo_);
 
        // BUG, because bar_ will be destroyed before bts_.
        Use(bar_);
 
        // Most likely a BUG! Unless `stuff` is contained within other fields,
        // there is probably no guarantee that it outlives `bts_`.
        // It should have been captured by move or by copy instead.
        Use(stuff);
    });
}

Generally, it's a good idea to declare bts_ after most other fields to avoid lifetime bugs. An example of fool-proof code:

private:
    Foo foo_;
    Bar bar_;
 
    // bts_ must be the last field for lifetime reasons.
    concurrent::BackgroundTaskStorage bts_;
};

Components and their clients can always be safely captured by reference:

See also: Component system

So for a BackgroundTaskStorage stored in a component, its tasks can only safely use the fields declared before the BTS field, as well as everything from the components, on which the current component depends.

Definition at line 104 of file background_task_storage.hpp.

Public Member Functions
	BackgroundTaskStorage ()

	BackgroundTaskStorage (engine::TaskProcessor &task_processor)
	Creates a BTS that launches tasks in the specified engine::TaskProcessor.

	BackgroundTaskStorage (const BackgroundTaskStorage &)=delete

BackgroundTaskStorage &	operator= (const BackgroundTaskStorage &)=delete

void	CancelAndWait () noexcept
	Explicitly cancel and wait for the tasks. New tasks must not be launched after this call returns. Should be called no more than once.

void	CloseAndWaitDebug () noexcept
	Explicitly stop accepting new tasks and wait for execution tasks in the store. Should be called no more than once.

template<typename... Args>
void	AsyncDetach (std::string name, Args &&... args)
	Launch a task that will be cancelled and waited for in the BTS destructor.

template<typename... Args>
void	CriticalAsyncDetach (std::string name, Args &&... args)
	Launch a task that will be cancelled and waited for in the BTS destructor.

std::int64_t	ActiveTasksApprox () const noexcept
	Approximate number of currently active tasks.

Constructor & Destructor Documentation

◆ BackgroundTaskStorage()

concurrent::BackgroundTaskStorage::BackgroundTaskStorage ( )

Creates a BTS that launches tasks in the engine::TaskProcessor used at the BTS creation.

Member Function Documentation

◆ AsyncDetach()

template<typename... Args>

void concurrent::BackgroundTaskStorage::AsyncDetach	(	std::string	name,
		Args &&...	args )

inline

Launch a task that will be cancelled and waited for in the BTS destructor.

The task is started as non-Critical, it may be cancelled due to TaskProcessor overload. engine::TaskInheritedVariable instances are not inherited from the caller except baggage::Baggage. See utils::AsyncBackground for details.

Can be called from a coroutine or a non-coroutine thread.

Definition at line 142 of file background_task_storage.hpp.

◆ CancelAndWait()

void concurrent::BackgroundTaskStorage::CancelAndWait ( )

noexcept

Explicitly cancel and wait for the tasks. New tasks must not be launched after this call returns. Should be called no more than once.

More precisely, new tasks must not be launched once this call is completed, but can be launched in the process of waiting for the remaining tasks. This means that one detached task is allowed to spawn another detached task into the same BTS, which will immediately be cancelled and for which CancelAndWait will wait as well.

Can only be called from a coroutine.

◆ CloseAndWaitDebug()

void concurrent::BackgroundTaskStorage::CloseAndWaitDebug ( )