#include <userver/dist_lock/dist_locked_task.hpp>

Inheritance diagram for dist_lock::DistLockedTask:

Collaboration diagram for dist_lock::DistLockedTask:

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

Public Types inherited from engine::Task
enum class	Importance { kNormal , kCritical }
	Task importance. More...

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

enum class	WaitMode { kSingleWaiter , kMultipleWaiters }
	Task wait mode. More...

Public Member Functions
	DistLockedTask ()=default

	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

Public Member Functions inherited from engine::TaskWithResult< void >
	TaskWithResult ()=default
	Default constructor.

	TaskWithResult (const TaskWithResult &)=delete

	TaskWithResult (TaskWithResult &&) noexcept=default

TaskWithResult &	operator= (const TaskWithResult &)=delete

TaskWithResult &	operator= (TaskWithResult &&) noexcept=default

void	Get () noexcept(false)
	Returns (or rethrows) the result of task invocation. After return from this method the task is not valid.

Public Member Functions inherited from engine::Task
	Task ()
	Default constructor.

virtual	~Task ()
	Destructor.

	Task (Task &&) noexcept

Task &	operator= (Task &&) noexcept

bool	IsValid () const
	Checks whether this `Task` 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.

void	Detach () &&
	Detaches task, allowing it to continue execution out of scope; memory safety is much better with concurrent::BackgroundTaskStorage.

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

Additional Inherited Members
Static Public Member Functions inherited from engine::Task
static const std::string &	GetStateName (State state)

Detailed Description

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

See also: AlwaysBusyDistLockStrategy

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);

Definition at line 39 of file dist_locked_task.hpp.

Member Typedef Documentation

◆ WorkerFunc

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

Definition at line 41 of file dist_locked_task.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

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

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

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

userver/dist_lock/dist_locked_task.hpp

Public Types

Public Member Functions

Additional Inherited Members