The Lock Component

FlockStore

The FlockStore uses the file system on the local computer to create the locks. It does not support expiration, but the lock is automatically released when the lock object goes out of scope and is freed by the garbage collector (for example when the PHP process ends):

1
2
3
4
5

use Symfony\Component\Lock\Store\FlockStore;

// the argument is the path of the directory where the locks are created
// if none is given, sys_get_temp_dir() is used internally.
$store = new FlockStore('/var/stores');

MemcachedStore

The MemcachedStore saves locks on a Memcached server, it requires a Memcached connection implementing the \Memcached class. This store does not support blocking, and expects a TTL to avoid stalled locks:

1
2
3
4
5
6

use Symfony\Component\Lock\Store\MemcachedStore;

$memcached = new \Memcached();
$memcached->addServer('localhost', 11211);

$store = new MemcachedStore($memcached);

RedisStore

The RedisStore saves locks on a Redis server, it requires a Redis connection implementing the \Redis, \RedisArray, \RedisCluster or \Predis classes. This store does not support blocking, and expects a TTL to avoid stalled locks:

1
2
3
4
5
6

use Symfony\Component\Lock\Store\RedisStore;

$redis = new \Redis();
$redis->connect('localhost');

$store = new RedisStore($redis);

SemaphoreStore

The SemaphoreStore uses the PHP semaphore functions to create the locks:

1
2
3

use Symfony\Component\Lock\Store\SemaphoreStore;

$store = new SemaphoreStore();

CombinedStore

The CombinedStore is designed for High Availability applications because it manages several stores in sync (for example, several Redis servers). When a lock is being acquired, it forwards the call to all the managed stores, and it collects their responses. If a simple majority of stores have acquired the lock, then the lock is considered as acquired; otherwise as not acquired:

1
2
3
4
5
6
7
8
9
10
11
12
13

use Symfony\Component\Lock\Store\CombinedStore;
use Symfony\Component\Lock\Store\RedisStore;
use Symfony\Component\Lock\Strategy\ConsensusStrategy;

$stores = [];
foreach (['server1', 'server2', 'server3'] as $server) {
    $redis = new \Redis();
    $redis->connect($server);

    $stores[] = new RedisStore($redis);
}

$store = new CombinedStore($stores, new ConsensusStrategy());

Instead of the simple majority strategy (ConsensusStrategy) an UnanimousStrategy can be used to require the lock to be acquired in all the stores.

Remote Stores

Remote stores (MemcachedStore and RedisStore) use an unique token to recognize the true owner of the lock. This token is stored in the Key object and is used internally by the Lock, therefore this key must not be shared between processes (session, caching, fork, ...).

Every concurrent process must store the Lock in the same server. Otherwise two different machines may allow two different processes to acquire the same Lock.

Expiring Stores

Expiring stores (MemcachedStore and RedisStore) guarantee that the lock is acquired only for the defined duration of time. If the task takes longer to be accomplished, then the lock can be released by the store and acquired by someone else.

The Lock provides several methods to check its health. The isExpired() method checks whether or not its lifetime is over and the getRemainingLifetime() method returns its time to live in seconds.

Using the above methods, a more robust code would be:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// ...
$lock = $factory->createLock('invoice-publication', 30);

if (!$lock->acquire()) {
    return;
}
while (!$finished) {
    if ($lock->getRemainingLifetime() <= 5) {
        if ($lock->isExpired()) {
            // lock was lost, perform a rollback or send a notification
            throw new \RuntimeException('Lock lost during the overall process');
        }

        $lock->refresh();
    }

    // Perform the task whose duration MUST be less than 5 minutes
}

By design, locks are stored in servers with a defined lifetime. If the date or time of the machine changes, a lock could be released sooner than expected.

FlockStore

By using the file system, this Store is reliable as long as concurrent processes use the same physical directory to stores locks.

Processes must run on the same machine, virtual machine or container. Be careful when updating a Kubernetes or Swarm service because for a short period of time, there can be two running containers in parallel.

The absolute path to the directory must remain the same. Be careful of symlinks that could change at anytime: Capistrano and blue/green deployment often use that trick. Be careful when the path to that directory changes between two deployments.

Some file systems (such as some types of NFS) do not support locking.

Files on the file system can be removed during a maintenance operation. For instance, to clean up the /tmp directory or after a reboot of the machine when a directory uses tmpfs. It's not an issue if the lock is released when the process ended, but it is in case of Lock reused between requests.

MemcachedStore

The way Memcached works is to store items in memory. That means that by using the MemcachedStore the locks are not persisted and may disappear by mistake at anytime.

If the Memcached service or the machine hosting it restarts, every lock would be lost without notifying the running processes.

By default Memcached uses a LRU mechanism to remove old entries when the service needs space to add new items.

When the Memcached service is shared and used for multiple usage, Locks could be removed by mistake. For instance some implementation of the PSR-6 clear() method uses the Memcached's flush() method which purges and removes everything.

RedisStore

The way Redis works is to store items in memory. That means that by using the RedisStore the locks are not persisted and may disappear by mistake at anytime.

If the Redis service or the machine hosting it restarts, every locks would be lost without notifying the running processes.

When the Redis service is shared and used for multiple usages, locks could be removed by mistake.

CombinedStore

Combined stores allow to store locks across several backends. It's a common mistake to think that the lock mechanism will be more reliable. This is wrong. The CombinedStore will be, at best, as reliable as the least reliable of all managed stores. As soon as one managed store returns erroneous information, the CombinedStore won't be reliable.

SemaphoreStore

Semaphores are handled by the Kernel level. In order to be reliable, processes must run on the same machine, virtual machine or container. Be careful when updating a Kubernetes or Swarm service because for a short period of time, there can be two running containers in parallel.

Overall

Changing the configuration of stores should be done very carefully. For instance, during the deployment of a new version. Processes with new configuration must not be started while old processes with old configuration are still running.