mysql::scheduler::Clock_lwm_registry Class Reference

Clock implementation that computes LWM (Low Water Mark) based on executed tasks. More...

#include <clock_lwm_registry.h>

Inheritance diagram for mysql::scheduler::Clock_lwm_registry:

Classes
struct	Task_state
	This structure is used to represent a registered task state and update LWM. More...

Public Member Functions
	Clock_lwm_registry (std::size_t clock_capacity=8192, Scheduler_clock_psi psi_params={})
	Construct the clock - initializes the internal task registry Since we use spin lock in this implementation, we skip PSI instrumentation. More...
Time_point_t	now () const override
	Get the current value of the LWM. More...
Time_point_t	start_time () const override
	Get start time of this clock - the first LWM value (0) More...
bool	add_time (Task_id task_id, Time_point_t) override
	Registers a task to execute at specific LWM. More...
bool	tick (Task_id task_id, Time_point_t) override
	Tick performed on the clock when task finishes. More...
void	test_set_current_lwm (Time_point_t lwm)
	Backdoor for unit tests to set LWM to a specific value. More...
Public Member Functions inherited from mysql::scheduler::Scheduler_clock
virtual	~Scheduler_clock ()=default
	Destructor. More...
virtual bool	advances_independently () const
	Returns property of a clock - information on whether this clock is steered by task ticks or advances independently. More...
virtual bool	try_unblock ()
	Maintenance function for unblocking the clock. More...
virtual Scheduler_dependency_type	get_type () const
	Typical scheduler clock dependency type is end to start. More...

Private Attributes
Task_registry_multi< Task_id, Task_state >	m_executed_registry
	Registry of executed tasks. More...
std::atomic< Time_point_t >	m_current_lwm {0}
	Current LWM value. More...

Additional Inherited Members
Public Types inherited from mysql::scheduler::Scheduler_clock
using	Time_point_t = uint64_t

Detailed Description

Clock implementation that computes LWM (Low Water Mark) based on executed tasks.

This class provides a Scheduler_clock interface where the "time" is represented by the LWM, which can be defined in two equivalent ways:

• The maximum task ID such that the task and all preceding tasks are completed.
• The minimum task ID that is not completed, minus 1.

Internally, this class uses a Task_registry_multi to track the state of tasks (registered, started, finished). It maintains an atomic LWM value, updated when tasks finish execution via the tick() method. The LWM advances to the maximum ID where all tasks up to that ID are finished.

Key Identifiers (Internal to this Class):

• Task_id: Opaque ID used in the Scheduler_clock API and internally. Assigned by the scheduler or caller; this class does not assign or translate IDs.
• LWM (Low Water Mark): The current "time" value, starting at 0 and monotonically increasing.

Performance Characteristics:

• Uses fine-grained locking with 16384 buckets in the Task_registry_multi.
• Employs spin locks for low-latency synchronization in low-contention scenarios.

API Overview:

• now(): Returns the current LWM.
• start_time(): Returns 0 (initial LWM).
• add_time(task_id, time_point): Registers a task at the given task_id. The time_point is ignored here.
• tick(task_id, time_point): Marks the task as finished and updates LWM if possible. The time_point is ignored.
• The class handles concurrency via atomics for LWM and per-bucket locking in the registry.

Relation to External Components (e.g., CSA): This class is designed for use in systems like Change Stream Apply (CSA), where:

• CSA assigns Task_id identifiers to received transactions and computes a last committed task ID (the ID of the last transaction that must precede it).
• Translation from source's parallel indexes to Task_id occurs outside this class (in CSA logic).
• A CSA task registers with add_time and waits until now() >= it's LWM time
• Upon finishing, it calls tick( on its task ID ).
• This ensures causality: a transaction applies only after all tasks up to its LWM time has completed
• LWM enables parallelism: tasks with higher IDs can proceed if LWM advances past lower ones.

Constructor & Destructor Documentation

Clock_lwm_registry()

mysql::scheduler::Clock_lwm_registry::Clock_lwm_registry ( std::size_t  clock_capacity = 8192, Scheduler_clock_psi  psi_params = {}  )

inline

Construct the clock - initializes the internal task registry Since we use spin lock in this implementation, we skip PSI instrumentation.

Parameters

clock_capacity	The maximum number of tasks this clock may handle
psi_params	Instrumentation

Member Function Documentation

add_time()

bool mysql::scheduler::Clock_lwm_registry::add_time ( Task_id  task_id, Time_point_t    )

overridevirtual

Registers a task to execute at specific LWM.

Here, we don't need to know at which LWM task executes.

Parameters

task_id

Id of the task that finished execution

Returns

True if task was registered successfully, false otherwise.

Implements mysql::scheduler::Scheduler_clock.

now()

Clock_lwm_registry::Time_point_t mysql::scheduler::Clock_lwm_registry::now ( ) const

overridevirtual

Get the current value of the LWM.

Returns

Current time (LWM)

Implements mysql::scheduler::Scheduler_clock.

start_time()

Clock_lwm_registry::Time_point_t mysql::scheduler::Clock_lwm_registry::start_time ( ) const

overridevirtual

Get start time of this clock - the first LWM value (0)

Returns

Clock start time for the scheduler to know from which time we calculate the task delay

Implements mysql::scheduler::Scheduler_clock.

test_set_current_lwm()

void mysql::scheduler::Clock_lwm_registry::test_set_current_lwm

(

Time_point_t

lwm

)

Backdoor for unit tests to set LWM to a specific value.

tick()

bool mysql::scheduler::Clock_lwm_registry::tick ( Task_id  task_id, Time_point_t    )

overridevirtual

Tick performed on the clock when task finishes.

Parameters

task_id

Id of the task that finished execution

Returns

True if clock value changed, false otherwise.

Implements mysql::scheduler::Scheduler_clock.

Member Data Documentation

m_current_lwm

std::atomic<Time_point_t> mysql::scheduler::Clock_lwm_registry::m_current_lwm {0}

private

Current LWM value.

m_executed_registry

Task_registry_multi<Task_id, Task_state> mysql::scheduler::Clock_lwm_registry::m_executed_registry

private

Registry of executed tasks.

Concurrency is covered by the Task Registry Multi (handles id conflicts)

---

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

• libs/mysql/scheduler/clock_lwm_registry.h
• libs/mysql/scheduler/clock_lwm_registry.cpp