Distributed locks

This section explains how to use Cypress as a distributed locking service, similar to ZooKeeper.

General information

To use YTsaurus as a distributed locking service, you need to deploy master servers of a cluster in multiple locations.

There must be at least three locations so that the service can work if one of them is not available. If the master servers are located in five locations, the service can work if any two of them are not available.

How it works

YTsaurus supports master and tablet transactions. Master transactions use a pessimistic locking model. This means that a lock on a Cypress node is acquired synchronously, and the system checks for potential conflicts.

Using the pessimistic model, you can construct a simple emulation of a distributed lock:

1. Create a node in Cypress outside of transactions. This node will respond to the lock. The node can be of any type, for example, map_node.
2. In the program, create a transaction where you want to acquire a lock on the given node. An attempt to acquire an exclusive lock on the node is under this transaction.
3. If the lock is acquired, then you can execute the code that this lock protects. And it's important that you ping the transaction. If the ping call fails or the transaction is canceled, then the execution is no longer exclusive. In this case, you have to stop the process or take other actions.
4. If the lock isn't acquired, repeat the transaction creation and lock acquisition.

As with any distributed lock system, you can't fully guarantee that a process under a lock is exclusive when it makes changes to a third-party system that is not integrated with YTsaurus transactions. For example, between consecutive ping calls, it might happen that a transaction is interrupted and a parallel process that acquires a lock on the same node starts.

When you make changes on the cluster where the lock is acquired, you should use the prerequisite_transactions option in requests to the cluster. In this option, you should specify the transaction under which the lock was acquired. Thus, YTsaurus ensures that the request is executed only if the transaction is alive and the lock is acquired.

How to use

To run a process under a lock, you can use the run-command-with-lock command. Alternatively, you can define how to acquire a lock in the application code.

If the process makes changes on a cluster and needs to make them exclusively, we recommend using a lock directly on that cluster.

Quotas

The request quota is calculated for a user of the cluster regardless of the host from which they send these requests. The default quota on requests is 100 RPS. If this limit is reached, requests are queued. The default queue depth is 100 requests. If the queue is full, the user gets the Request queue size limit exceeded error when they send another request. You can ask your cluster administrator to increase the limits.