#include <userver/dist_lock/dist_locked_task.hpp>

Detailed Description

A task that tries to acquire a distributed lock and runs user callback once while the lock is held.

When dist lock starts, the lock worker tries to take a lock in the loop. If succeeded, a task is launched that executes the user code. In the background, dist lock tries to extend the lock. In case of loss of the lock, the user task is canceled.

Example with retrying

    auto strategy = GetSomeDistLockStrategyForTheSample();
    std::atomic<std::size_t> counter = 0;
    dist_lock::DistLockedTask locked_task(
        "example",
        [&]() {
            counter++;
            if (counter < 5) {
                throw std::runtime_error("");
            }
        },
        strategy
    );
 
    UEXPECT_NO_THROW(locked_task.Get());
    EXPECT_EQ(counter, 5);

Example without retrying

    auto strategy = GetSomeDistLockStrategyForTheSample();
    std::atomic<std::size_t> counter = 0;
    dist_lock::DistLockedTask locked_task(
        "example",
        [&]() {
            counter++;
            throw std::runtime_error("123");
        },
        strategy,
        /*default settings*/ {},
        dist_lock::DistLockWaitingMode::kWait,
        dist_lock::DistLockRetryMode::kSingleAttempt
    );
 
    try {
        locked_task.Get();
        FAIL() << "Should have thrown";
    } catch (const std::runtime_error& exception) {
        EXPECT_EQ(exception.what(), std::string("123"));
    }
    EXPECT_EQ(counter, 1);

See also: Periodics and DistLocks; AlwaysBusyDistLockStrategy

Definition at line 48 of file dist_locked_task.hpp.

Inheritance diagram for dist_lock::DistLockedTask:

Public Types
using	WorkerFunc = std::function<void()>

enum class	Importance { kNormal , kCritical }
	Task importance. More...

enum class	State { kInvalid , kNew , kQueued , kRunning , kSuspended , kCancelled , kCompleted }
	Task state. More...

enum class	WaitMode { kSingleAwaiter , kMultipleAwaiters }
	Task wait mode. More...

Public Member Functions
	DistLockedTask ()=default

	DistLockedTask (DistLockedTask &&)=delete

DistLockedTask &	operator= (DistLockedTask &&)=delete

	DistLockedTask (const DistLockedTask &)=delete

DistLockedTask &	operator= (const DistLockedTask &&)=delete

	DistLockedTask (std::string name, WorkerFunc worker_func, std::shared_ptr< DistLockStrategyBase > strategy, const DistLockSettings &settings={}, DistLockWaitingMode mode=DistLockWaitingMode::kWait, DistLockRetryMode retry_mode=DistLockRetryMode::kRetry)

	DistLockedTask (engine::TaskProcessor &task_processor, std::string name, WorkerFunc worker_func, std::shared_ptr< DistLockStrategyBase > strategy, const DistLockSettings &settings={}, DistLockWaitingMode mode=DistLockWaitingMode::kWait, DistLockRetryMode retry_mode=DistLockRetryMode::kRetry)
	Creates a DistLockedTask to be run in a specific engine::TaskProcessor.

std::optional< std::chrono::steady_clock::duration >	GetLockedDuration () const

void	Get () noexcept(false)

bool	IsValid () const
	Checks whether this object owns an actual task (not State::kInvalid)

State	GetState () const
	Gets the task State.

bool	IsFinished () const
	Returns whether the task finished execution.

void	Wait () const noexcept(false)
	Suspends execution until the task finishes or caller is cancelled. Can be called from coroutine context only. For non-coroutine context use BlockingWait().

template<typename Rep, typename Period>
void	WaitFor (const std::chrono::duration< Rep, Period > &) const noexcept(false)
	Suspends execution until the task finishes or after the specified timeout or until caller is cancelled.

template<typename Clock, typename Duration>
void	WaitUntil (const std::chrono::time_point< Clock, Duration > &) const noexcept(false)
	Suspends execution until the task finishes or until the specified time point is reached or until caller is cancelled.

void	WaitUntil (Deadline) const
	Suspends execution until the task finishes or until the specified deadline is reached or until caller is cancelled.

bool	WaitNothrow () const noexcept
	Suspends execution until the task finishes or caller is cancelled. Can be called from coroutine context only. For non-coroutine context use BlockingWait().

FutureStatus	WaitNothrowUntil (Deadline) const noexcept
	Suspends execution until the task finishes or until the specified deadline is reached or until caller is cancelled.

void	RequestCancel ()
	Queues task cancellation request.

void	SyncCancel () noexcept
	Cancels the task and suspends execution until it is finished. Can be called from coroutine context only. For non-coroutine context use RequestCancel() + BlockingWait().

TaskCancellationReason	CancellationReason () const
	Gets task cancellation reason.

void	BlockingWait () const

Static Public Member Functions
static std::string_view	GetStateName (State state)

Member Typedef Documentation

◆ WorkerFunc

using dist_lock::DistLockedTask::WorkerFunc = std::function<void()>

Definition at line 50 of file dist_locked_task.hpp.

Member Enumeration Documentation

◆ Importance

enum class engine::TaskBase::Importance

stronginherited

Task importance.

Enumerator
kNormal	Normal task.
kCritical	Critical task. The task will be started regardless of cancellations, e.g. due to user request, deadline or TaskProcessor overload. After the task starts, it may be cancelled. In particular, if it received any cancellation requests before starting, then it will start as cancelled.

Definition at line 36 of file task_base.hpp.

◆ State

enum class engine::TaskBase::State

stronginherited

Task state.

Enumerator
kInvalid	Unusable.
kNew	just created, not registered with task processor
kQueued	awaits execution
kRunning	executing user code
kSuspended	suspended, e.g. waiting for blocking call to complete
kCancelled	The task is cancelled and was finished without returning a value or throwing a user-provided exception. This can happen for two reasons: When a non-critical task (see Importance::kCritical, see flavors_of_async) is cancelled before it starts running, the task functor is skipped, only destructor is executed. This can be interpreted as every non-critical task having an implicit cancellation point at its start. See more details and examples in task_cancellation_before_start. When a task is cancelled because of a call to engine::current_task::CancellationPoint. This cancellation is implemented using a non-`std::exception`-based exception. In both cases, engine::TaskWithResult::Get throws engine::TaskCancelledException. Unintuitively, this status is not set when the task was cancelled after it started running, which caused the user code to exit early. Use TaskBase::CancellationReason instead to check whether the task was cancelled.
kCompleted	Exited user code with return or throw. This includes cases where the task was cancelled after it started running, which caused the user code to exit early. Use TaskBase::IsFinished instead to check whether the task finished execution.

Definition at line 48 of file task_base.hpp.

◆ WaitMode

enum class engine::TaskBase::WaitMode

stronginherited

Task wait mode.

Enumerator
kSingleAwaiter	Can be awaited by at most one task at a time.
kMultipleAwaiters	Can be awaited by multiple tasks simultaneously.

Definition at line 85 of file task_base.hpp.

Constructor & Destructor Documentation

◆ DistLockedTask() [1/2]

dist_lock::DistLockedTask::DistLockedTask ( )

default

Default constructor. Creates an invalid task.

◆ DistLockedTask() [2/2]

dist_lock::DistLockedTask::DistLockedTask	(	std::string	name,
		WorkerFunc	worker_func,
		std::shared_ptr< DistLockStrategyBase >	strategy,
		const DistLockSettings &	settings = {},
		DistLockWaitingMode	mode = DistLockWaitingMode::kWait,
		DistLockRetryMode	retry_mode = DistLockRetryMode::kRetry )

Creates a DistLockedTask.

Parameters

name	name of the task
worker_func	a callback that is started once we've acquired the lock and is cancelled when the lock is lost.
settings	distributed lock settings
strategy	distributed locking strategy
mode	distributed lock waiting mode
retry_mode	run task continuously or once (needed mainly for tests)

Note: worker_func must honour task cancellation and stop ASAP when it is cancelled, otherwise brain split is possible (IOW, two different users do work assuming both of them hold the lock, which is not true).

Member Function Documentation

◆ BlockingWait()

void engine::TaskBase::BlockingWait ( ) const

inherited

Waits for the task in non-coroutine context (e.g. non-TaskProcessor's std::thread).

◆ GetLockedDuration()

std::optional< std::chrono::steady_clock::duration > dist_lock::DistLockedTask::GetLockedDuration ( ) const

Returns for how long the lock is held (if held at all). Returned value may be less than the real duration.

◆ IsValid()

bool engine::TaskBase::IsValid ( ) const

inherited

Checks whether this object owns an actual task (not State::kInvalid)

An invalid task cannot be used. The task becomes invalid after each of the following calls:

the default constructor
moving from this task object
engine::TaskWithResult::Get
concurrent::BackgroundTaskStorageCore::Detach
engine::DetachUnscopedUnsafe

Notably, the task does not become invalid immediately after it finishes execution. (That would always cause race conditions when trying to await a task.) It means that some of the task's resources are held onto until the task object is invalidated or destroyed.

◆ Wait()

void engine::TaskBase::Wait ( ) const

inherited

Suspends execution until the task finishes or caller is cancelled. Can be called from coroutine context only. For non-coroutine context use BlockingWait().

Exceptions

WaitInterruptedException when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

◆ WaitFor()

template<typename Rep, typename Period>

void engine::TaskBase::WaitFor ( const std::chrono::duration< Rep, Period > & duration ) const

inherited

Suspends execution until the task finishes or after the specified timeout or until caller is cancelled.

Exceptions

WaitInterruptedException when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

Definition at line 210 of file task_base.hpp.

◆ WaitNothrow()

bool engine::TaskBase::WaitNothrow ( ) const

nodiscardnoexceptinherited

Suspends execution until the task finishes or caller is cancelled. Can be called from coroutine context only. For non-coroutine context use BlockingWait().

Returns: false when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

◆ WaitNothrowUntil()

FutureStatus engine::TaskBase::WaitNothrowUntil ( Deadline ) const

nodiscardnoexceptinherited

Suspends execution until the task finishes or until the specified deadline is reached or until caller is cancelled.

Returns: FutureStatus::kCancelled when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

◆ WaitUntil() [1/2]

template<typename Clock, typename Duration>

void engine::TaskBase::WaitUntil ( const std::chrono::time_point< Clock, Duration > & until ) const

inherited

Suspends execution until the task finishes or until the specified time point is reached or until caller is cancelled.

Exceptions

WaitInterruptedException when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

Definition at line 215 of file task_base.hpp.

◆ WaitUntil() [2/2]

void engine::TaskBase::WaitUntil ( Deadline ) const

inherited

Suspends execution until the task finishes or until the specified deadline is reached or until caller is cancelled.

Exceptions

WaitInterruptedException when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

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

userver/dist_lock/dist_locked_task.hpp

Detailed Description

Example with retrying

Example without retrying

Public Types

Public Member Functions

Static Public Member Functions

Member Typedef Documentation

◆ WorkerFunc

Member Enumeration Documentation

◆ Importance

◆ State

◆ WaitMode

Constructor & Destructor Documentation

◆ DistLockedTask() [1/2]

◆ DistLockedTask() [2/2]

Member Function Documentation

◆ BlockingWait()

◆ GetLockedDuration()

◆ IsValid()

◆ Wait()

◆ WaitFor()

◆ WaitNothrow()

◆ WaitNothrowUntil()

◆ WaitUntil() [1/2]

◆ WaitUntil() [2/2]