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

Classes
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

using utils::PeriodicTask::Callback = std::function<void()>

Signature of the task to be executed each period.

Definition at line 120 of file periodic_task.hpp.

Member Enumeration Documentation

◆ Flags

enum class utils::PeriodicTask::Flags

strong

Enumerator
kNone	None of the below flags.
kNow	Immediately call a function.
kStrong	Account function call time as a part of wait period.
kChaotic	Randomize wait period (+-25% by default)
kCritical	Deprecated Does nothing, PeriodicTask is always spawned as `engine::Task::Importance::kCritical`. Note 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.

Note: 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 ( )

noexcept

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

Warning: 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).

Parameters

preserve_span run periodic task current span if true. It's here for backward compatibility with existing tests. Will be removed in TAXIDATA-1499.

Returns: true if task was successfully executed.

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

userver/utils/periodic_task.hpp