Skip to content

[Lock] Add documentation about Shared Locks #14231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 22, 2020
Merged

[Lock] Add documentation about Shared Locks #14231

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 61 additions & 11 deletions components/lock.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,56 @@ This component also provides two useful methods related to expiring locks:
``getExpiringDate()`` (which returns ``null`` or a ``\DateTimeImmutable``
object) and ``isExpired()`` (which returns a boolean).

Shared Locks
------------

Sometimes, a data structure cannot be updated atomically and is invalid during
the time of the update. In this situation, other process should not read or
write the data until the update is complete. But once updated, multiple process
can read the data in parallel.

In this situation, a common solution is to use shared lock which allows
concurent access for read-only operations, while write operations require
exclusive access.

Use the :method:`Symfony\\Component\\Lock\\LockInterface::acquireRead` method
to acquire a read-only lock, and the existing
:method:`Symfony\\Component\\Lock\\LockInterface::acquire` method to acquire a
write lock.::

$lock = $factory->createLock('user'.$user->id);
if (!$lock->acquireRead()) {
return;
}

Similare to the ``acquire`` method, pass ``true`` as the argument of the ``acquireRead()``
method to acquire the lock in a blocking mode.::

$lock = $factory->createLock('user'.$user->id);
$lock->acquireRead(true);

When a read-only lock is acquired with the method ``acquireRead``, it's
possible to **Promote** the lock, and change it to write lock, by calling the
``acquire`` method.::

$lock = $factory->createLock('user'.$userId);
$lock->acquireRead(true);

if (!$this->shouldUpdate($userId)) {
return;
}

$lock->acquire(true); // Promote the lock to write lock
$this->update($userId);

In the same way, it's possible to **Demote** a write lock, and change it to a
read-only lock by calling the ``acquireRead`` method.

.. versionadded:: 5.2

The ``Lock::acquireRead`` method and ``SharedLockStoreInterface`` interface
and were introduced in Symfony 5.2.

The Owner of The Lock
---------------------

Expand Down Expand Up @@ -219,17 +269,17 @@ Locks are created and managed in ``Stores``, which are classes that implement

The component includes the following built-in store types:

============================================ ====== ======== ========
Store Scope Blocking Expiring
============================================ ====== ======== ========
:ref:`FlockStore <lock-store-flock>` local yes no
:ref:`MemcachedStore <lock-store-memcached>` remote no yes
:ref:`MongoDbStore <lock-store-mongodb>` remote no yes
:ref:`PdoStore <lock-store-pdo>` remote no yes
:ref:`RedisStore <lock-store-redis>` remote no yes
:ref:`SemaphoreStore <lock-store-semaphore>` local yes no
:ref:`ZookeeperStore <lock-store-zookeeper>` remote no no
============================================ ====== ======== ========
============================================ ====== ======== ======== =======
Store Scope Blocking Expiring Sharing
============================================ ====== ======== ======== =======
:ref:`FlockStore <lock-store-flock>` local yes no yes
:ref:`MemcachedStore <lock-store-memcached>` remote no yes no
:ref:`MongoDbStore <lock-store-mongodb>` remote no yes no
:ref:`PdoStore <lock-store-pdo>` remote no yes no
:ref:`RedisStore <lock-store-redis>` remote no yes yes
:ref:`SemaphoreStore <lock-store-semaphore>` local yes no no
:ref:`ZookeeperStore <lock-store-zookeeper>` remote no no no
============================================ ====== ======== ======== =======

.. _lock-store-flock:

Expand Down