userver: userver/storages/mongo/dist_lock_component_base.hpp Source File
Loading...
Searching...
No Matches
dist_lock_component_base.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/storages/mongo/dist_lock_component_base.hpp
4/// @brief @copybrief storages::mongo::DistLockComponentBase
5
6#include <userver/components/component_base.hpp>
7#include <userver/dist_lock/dist_locked_worker.hpp>
8#include <userver/storages/mongo/collection.hpp>
9#include <userver/storages/mongo/dist_lock_strategy.hpp>
10#include <userver/utils/statistics/entry.hpp>
11
12USERVER_NAMESPACE_BEGIN
13
14namespace storages::mongo {
15
16// clang-format off
17
18/// @ingroup userver_components userver_base_classes
19///
20/// @brief Base class for mongo-based distlock worker components
21///
22/// A component that implements a distlock with lock in Mongo. Inherit from
23/// DistLockComponentBase and implement DoWork(). Lock options are configured
24/// in static config.
25///
26/// Mongo might not perform well on a high load, so you might want to use
27/// postgres-based distlock storages::postgres::DistLockComponentBase instead.
28/// @see storages::postgres::DistLockComponentBase
29///
30/// ## Cancellation checks
31/// Functions engine::current_task::ShouldCancel(),
32/// engine::InterruptibleSleepFor(), engine::InterruptibleSleepUntil() and
33/// engine::current_task::CancellationPoint() check for task cancellation.
34/// Overridden DistLockComponentBase::DoWork must use the above functions to
35/// honour task cancellation and stop ASAP when
36/// it is cancelled.
37///
38/// ## Static configuration example:
39///
40/// ```yaml
41/// example-distlock:
42/// lockname: master
43/// mongo-timeout: 1s
44/// lock-ttl: 10s
45/// ```
46///
47/// ## Static options:
48/// name | Description | Default value
49/// -------------- | ------------ | -------------
50/// lockname | name of the lock | --
51/// lock-ttl | TTL of the lock; must be at least as long as the duration between subsequent cancellation checks, otherwise brain split is possible | --
52/// mongo-timeout | timeout, must be less than lock-ttl / 2 | --
53/// restart-delay | how much time to wait after failed task restart | 100ms
54/// task-processor | the name of the TaskProcessor for running DoWork | main-task-processor
55/// testsuite-support | Enable testsuite support | false
56///
57/// @see @ref scripts/docs/en/userver/periodics.md
58
59// clang-format on
60
62 public:
63 DistLockComponentBase(const components::ComponentConfig&,
64 const components::ComponentContext&,
65 storages::mongo::Collection);
66
67 ~DistLockComponentBase() override;
68
69 dist_lock::DistLockedWorker& GetWorker();
70
71 bool OwnsLock() const noexcept;
72
73 static yaml_config::Schema GetStaticConfigSchema();
74
75 protected:
76 /// Override this function with anything that must be done under the mongo
77 /// lock.
78 ///
79 /// ## Example implementation
80 ///
81 /// @code
82 /// void MyDistLockComponent::DoWork()
83 /// {
84 /// while (!engine::ShouldCancel())
85 /// {
86 /// // Start a new trace_id
87 /// auto span = tracing::Span::MakeRootSpan("my-dist-lock");
88 ///
89 /// // If Foo() or other function in DoWork() throws an exception,
90 /// // DoWork() will be restarted in `restart-delay` seconds.
91 /// Foo();
92 ///
93 /// // Check for cancellation after cpu-intensive Foo().
94 /// // You must check for cancellation at least every `lock-ttl`
95 /// // seconds to have time to notice lock prolongation failure.
96 /// if (engine::ShouldCancel()) break;
97 ///
98 /// Bar();
99 /// }
100 /// }
101 /// @endcode
102 ///
103 /// @note `DoWork` must honour task cancellation and stop ASAP when
104 /// it is cancelled, otherwise brain split is possible (IOW, two different
105 /// users do work assuming both of them hold the lock, which is not true).
106 virtual void DoWork() = 0;
107
108 /// Override this function to provide custom testsuite handler.
109 virtual void DoWorkTestsuite() { DoWork(); }
110
111 /// Must be called in constructor
112 void Start();
113
114 /// Must be called in destructor
115 void Stop();
116
117 private:
118 std::unique_ptr<dist_lock::DistLockedWorker> worker_;
119 bool testsuite_enabled_{false};
120
121 // Subscriptions must be the last fields.
122 utils::statistics::Entry statistics_holder_;
123};
124
125} // namespace storages::mongo
126
127USERVER_NAMESPACE_END