storages::postgres::DistLockComponentBase Class Reference

#include <userver/storages/postgres/dist_lock_component_base.hpp>

Detailed Description

Base class for postgres-based distlock worker components.

A component that implements a distlock with lock in Postgres. Inherit from DistLockComponentBase and implement DoWork(). Lock options are configured in static config. To customize a distlock for testsuite override DoWorkTestsuite().

By default the distlock is started and stopped automatically by the framework in all environments except testsuite. If manual control over the distlock startup and shutdown is needed pass DisableAutostartAtBase{} to the DistLockComponentBase .ctor.

The class must be used for infinite loop jobs. If you want a distributed periodic, you should look at locked_periodiccomponents::PgLockedPeriodic.

See also

dist_lock::DistLockedTask

locked_periodiccomponents::PgLockedPeriodic

Static configuration example:

example-distlock:
    cluster: postgresql-service
    table: service.distlocks
    lockname: master
    pg-timeout: 1s
    lock-ttl: 10s
    autostart: true

See config POSTGRES_DISTLOCK_SETTINGS, some of parameters can be dynamically overridden.

Static options of storages::postgres::DistLockComponentBase :

Name	Description	Default value
cluster	Postgres cluster name.	–
shard-number	Postgres shard number.	–
table	Table name to store distlocks.	–
lockname	Name of the lock.	–
lock-ttl	TTL of the lock; must be at least as long as the duration between subsequent cancellation checks, otherwise brain split is possible.	–
pg-timeout	Timeout, must be less than lock-ttl/2.	–
restart-delay	How much time to wait after failed task restart.	100ms
autostart	If true, start automatically after component load.	true
task-processor	The name of the TaskProcessor for running DoWork.	main-task-processor
testsuite-support	Enable testsuite support.	true if autostart_at_base_component parameter passed to the .ctor is kYes, false otherwise
locker-log-level	Base logging level for locker logs (default is info).	–

Options inherited from components::ComponentBase :

Name	Description	Default value
load-enabled	Set to false to disable loading of the component.	true

Migration example

You have to create a SQL table for distlocks. An example of the migration script is as following:

CREATE TABLE service.distlocks
(
    key             TEXT PRIMARY KEY,
    owner           TEXT,
    expiration_time TIMESTAMPTZ
);

See also

Periodics and DistLocks

Definition at line 68 of file dist_lock_component_base.hpp.

Inheritance diagram for storages::postgres::DistLockComponentBase:

Classes
struct	DisableAutostartAtBase

Public Member Functions
	DistLockComponentBase (const components::ComponentConfig &component_config, const components::ComponentContext &component_context)
	Constructs the distlock base and enables automatic startup and shutdown of the distlock.
	DistLockComponentBase (const components::ComponentConfig &component_config, const components::ComponentContext &component_context, DisableAutostartAtBase)
	Constructs the distlock base and disables automatic startup and shutdown of the distlock. The dislock should be started and stopped manually via AutostartDistlock() and StopDistLock() calls.
dist_lock::DistLockedWorker &	GetWorker ()
bool	OwnsLock () const noexcept
ComponentHealth	GetComponentHealth () const override
void	OnLoadingCancelled () override
void	OnAllComponentsLoaded () override
void	OnGracefulShutdown (engine::Deadline serving_shutdown_deadline) override
void	OnAllComponentsAreStopping () override

Static Public Member Functions
static yaml_config::Schema	GetStaticConfigSchema ()

Protected Types
using	LoggableComponentBase = ComponentBase

Protected Member Functions
virtual void	DoWork ()=0
virtual void	DoWorkTestsuite ()
	Override this function to provide custom testsuite handler.
void	AutostartDistLock ()
void	StopDistLock ()
bool	IsCancelAdvised () const

Member Typedef Documentation

LoggableComponentBase

using components::ComponentBase::LoggableComponentBase = ComponentBase

protectedinherited

Deprecated

use components::ComponentBase instead.

Definition at line 79 of file component_base.hpp.

Member Function Documentation

AutostartDistLock()

void storages::postgres::DistLockComponentBase::AutostartDistLock ( )

protected

Should be called in a .ctor of a derived class iff DisableAutostartAtBase{} has been passed to the DistLockComponentBase .ctor.

DoWork()

virtual void storages::postgres::DistLockComponentBase::DoWork ( )

protectedpure virtual

Override this function with anything that must be done under the pg lock.

Example implementation

void MyDistLockComponent::DoWork()
{
    // `IsCancelAdvised` is advisory/soft signal to stop the task.
    // Check it in every independent processing iteration.
    // Whereas @ref engine::current_task::ShouldCancel() checks as frequently,
    // as you can to honor low-level task cancellation.
    while (!IsCancelAdvised())
    {
        // Start a new trace_id
        auto span = tracing::Span::MakeRootSpan("my-dist-lock");
 
        // If Foo() or other function in DoWork() throws an exception,
        // DoWork() will be restarted in `restart-delay` seconds.
        Foo();
 
        // Check for cancellation after cpu-intensive Foo().
        // You must check for cancellation at least every `lock-ttl`
        // seconds to have time to notice lock prolongation failure.
        if (engine::ShouldCancel()) break;
 
        Bar();
    }
}

Note

DoWork 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).

DoWorkTestsuite()

virtual void storages::postgres::DistLockComponentBase::DoWorkTestsuite ( )

inlineprotectedvirtual

Override this function to provide custom testsuite handler.

Definition at line 132 of file dist_lock_component_base.hpp.

GetComponentHealth()

ComponentHealth components::ComponentBase::GetComponentHealth ( ) const

inlineoverridevirtualinherited

Override this function to inform the world of the state of your component.

Warning

The function is called concurrently from multiple threads.

Reimplemented from components::RawComponentBase.

Reimplemented in components::Redis, and server::handlers::Restart.

Definition at line 35 of file component_base.hpp.

IsCancelAdvised()

bool storages::postgres::DistLockComponentBase::IsCancelAdvised ( ) const

protected

Check this method when going for the next independent processing iteration. Whereas engine::current_task::ShouldCancel() checks as frequently, as you can to honor low-level task cancellation.

OnAllComponentsAreStopping()

void components::ComponentBase::OnAllComponentsAreStopping ( )

inlineoverridevirtualinherited

Component may use this function to stop doing work before the stop of the components that depend on it.

Base components may override it and make final to do some work before the derived object constructor is called. Don't use it otherwise.

Reimplemented from components::RawComponentBase.

Reimplemented in components::Server, and urabbitmq::ConsumerComponentBase.

Definition at line 70 of file component_base.hpp.

OnAllComponentsLoaded()

void components::ComponentBase::OnAllComponentsLoaded ( )

inlineoverridevirtualinherited

Component may use this function to finalize registration of other components that depend on it (for example, handler components register in server component, and the latter uses OnAllComponentsLoaded() to start processing requests).

Base components may override it and make final to do some work after the derived object constructor is called. Don't use it otherwise.

Reimplemented from components::RawComponentBase.

Reimplemented in components::Server, server::handlers::Ping, and urabbitmq::ConsumerComponentBase.

Definition at line 51 of file component_base.hpp.

OnGracefulShutdown()

void components::ComponentBase::OnGracefulShutdown ( engine::Deadline serving_shutdown_deadline )

overridevirtualinherited

Serving components like HTTP and gRPC servers may use this function to stop accepting new requests and shutdown serving in the given time interval. Application components likely do not need to override it.

Parameters

[in]

serving_shutdown_deadline

The deadline until already running requests should be allowed to complete. The component is supposed to stop accepting new requests and continue processing of already active requests until this deadline (unless those requests finish earlier). And it might completely shutdown requests processing when the deadline is reached (or when no active requests left).

Reimplemented from components::RawComponentBase.

Reimplemented in components::Server.

OnLoadingCancelled()

void components::ComponentBase::OnLoadingCancelled ( )

inlineoverridevirtualinherited

Called once if the creation of any other component failed. If the current component expects some other component to take any action with the current component, this call is a signal that such action may never happen due to components loading was cancelled. Application components might not want to override it.

Reimplemented from components::RawComponentBase.

Definition at line 42 of file component_base.hpp.

OwnsLock()

bool storages::postgres::DistLockComponentBase::OwnsLock ( ) const

noexcept

Note

In testsuite always returns true, because there is only one host.

StopDistLock()

void storages::postgres::DistLockComponentBase::StopDistLock ( )

protected

Should be called in a .dtor of a derived class iff DisableAutostartAtBase{} has been passed to the DistLockComponentBase .ctor.

---

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

• userver/storages/postgres/dist_lock_component_base.hpp