userver: utils::PeriodicTask Class Reference
No Matches
utils::PeriodicTask Class Referencefinal

#include <userver/utils/periodic_task.hpp>

Detailed Description

Task that periodically runs a user callback. Callback is started after the previous callback execution is finished every period + A - B, where:

  • A is +/- distribution * rand(0.0, 1.0) if Flags::kChaotic flag is set, otherwise is 0;
  • B is the time of previous callback execution if Flags::kStrong flag is set, otherwise is 0;

TaskProcessor to execute the callback and many other options are specified in PeriodicTask::Settings.

Definition at line 38 of file periodic_task.hpp.


struct  Settings
 Configuration parameters for PeriodicTask. More...

Public Types

enum class  Flags {
  kNone = 0 ,
  kNow = 1 << 0 ,
  kStrong = 1 << 1 ,
  kChaotic = 1 << 2 ,
  kCritical = 1 << 4
using Callback = std::function<void()>
 Signature of the task to be executed each period.

Public Member Functions

 PeriodicTask ()
 Default constructor that does nothing.
 PeriodicTask (PeriodicTask &&)=delete
 PeriodicTask (const PeriodicTask &)=delete
 PeriodicTask (std::string name, Settings settings, Callback callback)
 Constructs the periodic task and calls Start()
void Start (std::string name, Settings settings, Callback callback)
void Stop () noexcept
 Stops the PeriodicTask. If a Step() is in progress, cancels it and waits for its completion.
void SetSettings (Settings settings)
 Set all settings except flags. All flags must be set at the start.
void ForceStepAsync ()
 Non-blocking force next iteration.
bool SynchronizeDebug (bool preserve_span=false)
void SuspendDebug ()
void ResumeDebug ()
bool IsRunning () const
void RegisterInTestsuite (testsuite::PeriodicTaskControl &periodic_task_control)
Settings GetCurrentSettings () const
 Get current settings. Note that they might become stale very quickly.

Member Typedef Documentation

◆ Callback

Signature of the task to be executed each period.

Definition at line 120 of file periodic_task.hpp.

Member Enumeration Documentation

◆ Flags


None of the below flags.


Immediately call a function.


Account function call time as a part of wait period.


Randomize wait period (+-25% by default)

Does nothing, PeriodicTask is always spawned as engine::Task::Importance::kCritical.
Although this periodic task cannot be cancelled due to system overload, it's cancelled upon calling Stop. Subtasks that may be spawned in the callback are not critical by default and may be cancelled as usual.

Definition at line 40 of file periodic_task.hpp.

Member Function Documentation

◆ ForceStepAsync()

void utils::PeriodicTask::ForceStepAsync ( )

Non-blocking force next iteration.

Returns immediately, without waiting for Step() to finish.

  • If PeriodicTask isn't running, then a Step() will be performed at the start.
  • If the PeriodicTask is waiting for the next iteration, then the wait is interrupted and the next Step() is executed.
  • If Step() is being executed, the current iteration will be completed and only after that a new iteration will be called. Reason: the current iteration is considered to be using stale data.
If 'ForceStepAsync' is called multiple times while Step() is being executed, all events will be conflated (one extra Step() call will be executed).

◆ IsRunning()

bool utils::PeriodicTask::IsRunning ( ) const

Checks if a periodic task (not a single iteration only) is running. It may be in a callback execution or sleeping between callbacks.

◆ RegisterInTestsuite()

void utils::PeriodicTask::RegisterInTestsuite ( testsuite::PeriodicTaskControl & periodic_task_control)

Make this periodic task available for testsuite. Testsuite provides a way to call it directly from testcase.

◆ ResumeDebug()

void utils::PeriodicTask::ResumeDebug ( )

Stop skipping Step() calls from loop. Returns without waiting for DoStep() call. The purpose is to control task execution from tests.

◆ Start()

void utils::PeriodicTask::Start ( std::string name,
Settings settings,
Callback callback )

Stops the periodic execution of previous task and starts the periodic execution of the new task.

◆ Stop()

void utils::PeriodicTask::Stop ( )

Stops the PeriodicTask. If a Step() is in progress, cancels it and waits for its completion.

PeriodicTask must be stopped before the callback becomes invalid. E.g. if your class X stores PeriodicTask and the callback is class' X method, you have to explicitly stop PeriodicTask in ~X() as after ~X() exits the object is destroyed and using X's 'this' in callback is UB.

◆ SuspendDebug()

void utils::PeriodicTask::SuspendDebug ( )

Skip Step() calls from loop until ResumeDebug() is called. If DoStep() is executing, wait its completion, for a potentially long time. The purpose is to control task execution from tests.

◆ SynchronizeDebug()

bool utils::PeriodicTask::SynchronizeDebug ( bool preserve_span = false)

Force next DoStep() iteration. It is guaranteed that there is at least one call to DoStep() during SynchronizeDebug() execution. DoStep() is executed as usual in the PeriodicTask's task (NOT in current task).

preserve_spanrun periodic task current span if true. It's here for backward compatibility with existing tests. Will be removed in TAXIDATA-1499.
true if task was successfully executed.
On concurrent invocations, the task is guaranteed to be invoked serially, one time after another.

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