concurrent::BackgroundTaskStorage Class Reference

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

class WellOrderedComponent {
public:
    // ...
 
    void Launch() {
        bts_.AsyncDetach("task", [this] {
            // OK, because foo_ will be destroyed after bts_.
            Use(foo_);
 
            // OK, because bar_ will be destroyed before bts_.
            Use(bar_);
        });
    }
 
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 116 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.
void	WaitAndDisposeSlow () noexcept
	Wait for the remaining tasks to complete without cancelling them. New tasks must not be launched after this call returns.
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

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

ActiveTasksApprox()

std::int64_t concurrent::BackgroundTaskStorage::ActiveTasksApprox ( ) const

noexcept

Returns

Approximate number of currently active tasks.

Can be called from a coroutine or a non-coroutine thread. Cannot be called after CancelAndWait or WaitAndDisposeSlow has been called.

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 162 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.

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 this call will wait as well.

Can only be called from a coroutine.

CriticalAsyncDetach()

template<typename... Args>

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

inline

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

Execution of function is guaranteed to start regardless of engine::TaskProcessor load limits. engine::TaskInheritedVariable instances are not inherited from the caller except baggage::Baggage. See utils::CriticalAsyncBackground for details.

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

Definition at line 177 of file background_task_storage.hpp.

WaitAndDisposeSlow()

void concurrent::BackgroundTaskStorage::WaitAndDisposeSlow ( )

noexcept

Wait for the remaining tasks to complete without cancelling them. New tasks must not be launched after this call returns.

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, for which this call will wait as well.

Note

Running this method burns some CPU time (a few microseconds). Awaiting the tasks once on service shutdown, or even periodically, is okay, but don't use BackgroundTaskStorage as a substitute for std::vector<Task> in handlers, because it is less efficient.

Can only be called from a coroutine.

---

The documentation for this class was generated from the following file:

• userver/concurrent/background_task_storage.hpp