dist_locked_task.hpp

Go to the documentation of this file.

#pragma once
 
/// @file userver/dist_lock/dist_locked_task.hpp
/// @brief @copybrief dist_lock::DistLockedTask
 
#include <chrono>
#include <functional>
#include <memory>
#include <optional>
#include <string>
 
#include <userver/dist_lock/dist_lock_settings.hpp>
#include <userver/dist_lock/dist_lock_strategy.hpp>
#include <userver/engine/task/task_base.hpp>
#include <userver/engine/task/task_processor_fwd.hpp>
#include <userver/logging/level.hpp>
 
USERVER_NAMESPACE_BEGIN
 
namespace dist_lock {
namespace impl {
 
class Locker;
 
}  // namespace impl
 
/// @ingroup userver_concurrency
///
/// @brief 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
/// @snippet dist_lock/dist_lock_test.cpp Sample distributed locked task Retry
/// ## Example without retrying
/// @snippet dist_lock/dist_lock_test.cpp Sample distributed locked task SingleAttempt
///
/// @see @ref scripts/docs/en/userver/periodics.md
/// @see AlwaysBusyDistLockStrategy
class DistLockedTask final : public engine::TaskBase {
public:
    using WorkerFunc = std::function<void()>;
 
    /// Default constructor.
    /// Creates an invalid task.
    DistLockedTask() = default;
 
    DistLockedTask(DistLockedTask&&) = delete;
    DistLockedTask& operator=(DistLockedTask&&) = delete;
 
    DistLockedTask(const DistLockedTask&) = delete;
    DistLockedTask& operator=(const DistLockedTask&&) = delete;
 
    ~DistLockedTask();
 
    /// Creates a DistLockedTask.
    /// @param name name of the task
    /// @param worker_func a callback that is started once we've acquired the lock
    /// and is cancelled when the lock is lost.
    /// @param settings distributed lock settings
    /// @param strategy distributed locking strategy
    /// @param mode distributed lock waiting mode
    /// @param retry_mode run task continuously or once (needed mainly for tests)
    /// @param base_log_level logging level settings. WARNING and ERROR levels are not overridden
    /// @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).
    DistLockedTask(
        std::string name,
        WorkerFunc worker_func,
        std::shared_ptr<DistLockStrategyBase> strategy,
        const DistLockSettings& settings = {},
        DistLockWaitingMode mode = DistLockWaitingMode::kWait,
        DistLockRetryMode retry_mode = DistLockRetryMode::kRetry,
        logging::Level base_log_level = logging::Level::kInfo
    );
 
    /// Creates a DistLockedTask to be run in a specific engine::TaskProcessor
    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,
        logging::Level base_log_level = logging::Level::kInfo
    );
 
    /// Returns for how long the lock is held (if held at all). Returned value
    /// may be less than the real duration.
    std::optional<std::chrono::steady_clock::duration> GetLockedDuration() const;
 
    void Get() noexcept(false);
 
private:
    DistLockedTask(engine::TaskProcessor&, std::shared_ptr<impl::Locker>, DistLockWaitingMode);
 
    std::shared_ptr<impl::Locker> locker_ptr_;
};
 
}  // namespace dist_lock
 
USERVER_NAMESPACE_END