The Lock Component

Automatically Releasing The Lock

Locks are automatically released when their Lock objects are destroyed. This is an implementation detail that is important when sharing Locks between processes. In the example below, pcntl_fork() creates two processes and the Lock will be released automatically as soon as one process finishes:

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

// ...
$lock = $factory->createLock('pdf-creation');
if (!$lock->acquire()) {
    return;
}

$pid = pcntl_fork();
if (-1 === $pid) {
    // Could not fork
    exit(1);
} elseif ($pid) {
    // Parent process
    sleep(30);
} else {
    // Child process
    echo 'The lock will be released now.';
    exit(0);
}
// ...

To disable this behavior, set the autoRelease argument of LockFactory::createLock() to false. That will make the lock acquired for 3600 seconds or until Lock::release() is called:

1
2
3
4
5

$lock = $factory->createLock(
    'pdf-creation',
    3600, // ttl
    false // autoRelease
);

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);

MongoDbStore

The MongoDbStore saves locks on a MongoDB server >=2.2, it requires a \MongoDB\Collection or \MongoDB\Client from mongodb/mongodb or a MongoDB Connection String. This store does not support blocking and expects a TTL to avoid stalled locks:

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Component\Lock\Store\MongoDbStore;

$mongo = 'mongodb://localhost/database?collection=lock';
$options = [
    'gcProbablity' => 0.001,
    'database' => 'myapp',
    'collection' => 'lock',
    'uriOptions' => [],
    'driverOptions' => [],
];
$store = new MongoDbStore($mongo, $options);

The MongoDbStore takes the following $options (depending on the first parameter type):

When the first parameter is a:

MongoDB\Collection:

• $options['database'] is ignored
• $options['collection'] is ignored

MongoDB\Client:

• $options['database'] is mandatory
• $options['collection'] is mandatory

MongoDB Connection String:

• $options['database'] is used otherwise /path from the DSN, at least one is mandatory
• $options['collection'] is used otherwise ?collection= from the DSN, at least one is mandatory

PdoStore

The PdoStore saves locks in an SQL database. It is identical to DoctrineDbalStore but requires a PDO connection or a Data Source Name (DSN). This store does not support blocking, and expects a TTL to avoid stalled locks:

1
2
3
4
5

use Symfony\Component\Lock\Store\PdoStore;

// a PDO or DSN for lazy connecting through PDO
$databaseConnectionOrDSN = 'mysql:host=127.0.0.1;dbname=app';
$store = new PdoStore($databaseConnectionOrDSN, ['db_username' => 'myuser', 'db_password' => 'mypassword']);

The table where values are stored is created automatically on the first call to the save() method. You can also create this table explicitly by calling the createTable() method in your code.

DoctrineDbalStore

The DoctrineDbalStore saves locks in an SQL database. It is identical to PdoStore but requires a Doctrine DBAL Connection, or a Doctrine DBAL URL. This store does not support blocking, and expects a TTL to avoid stalled locks:

1
2
3
4
5

use Symfony\Component\Lock\Store\DoctrineDbalStore;

// a Doctrine DBAL connection or DSN
$connectionOrURL = 'mysql://myuser:mypassword@127.0.0.1/app';
$store = new DoctrineDbalStore($connectionOrURL);

The table where values are stored is created automatically on the first call to the save() method. You can also add this table to your schema by calling configureSchema() method in your code or create this table explicitly by calling the createTable() method.

PostgreSqlStore

The PostgreSqlStore and DoctrineDbalPostgreSqlStore uses Advisory Locks provided by PostgreSQL. It is identical to DoctrineDbalPostgreSqlStore but requires PDO connection or a Data Source Name (DSN). It supports native blocking, as well as sharing locks:

1
2
3
4
5

use Symfony\Component\Lock\Store\PostgreSqlStore;

// a PDO instance or DSN for lazy connecting through PDO
$databaseConnectionOrDSN = 'pgsql:host=localhost;port=5634;dbname=app';
$store = new PostgreSqlStore($databaseConnectionOrDSN, ['db_username' => 'myuser', 'db_password' => 'mypassword']);

In opposite to the PdoStore, the PostgreSqlStore does not need a table to store locks and it does not expire.

DoctrineDbalPostgreSqlStore

The DoctrineDbalPostgreSqlStore uses Advisory Locks provided by PostgreSQL. It is identical to PostgreSqlStore but requires a Doctrine DBAL Connection or a Doctrine DBAL URL. It supports native blocking, as well as sharing locks:

1
2
3
4
5

use Symfony\Component\Lock\Store\DoctrineDbalPostgreSqlStore;

// a Doctrine Connection or DSN
$databaseConnectionOrDSN = 'postgresql+advisory://myuser:mypassword@127.0.0.1:5634/lock';
$store = new DoctrineDbalPostgreSqlStore($databaseConnectionOrDSN);

In opposite to the DoctrineDbalStore, the DoctrineDbalPostgreSqlStore does not need a table to store locks and does not expire.

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 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 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:

1
2
3
4

use Symfony\Component\Lock\Store\CombinedStore;
use Symfony\Component\Lock\Strategy\UnanimousStrategy;

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

ZookeeperStore

The ZookeeperStore saves locks on a ZooKeeper server. It requires a ZooKeeper connection implementing the \Zookeeper class. This store does not support blocking and expiration but the lock is automatically released when the PHP process is terminated:

1
2
3
4
5
6
7

use Symfony\Component\Lock\Store\ZookeeperStore;

$zookeeper = new \Zookeeper('localhost:2181');
// use the following to define a high-availability cluster:
// $zookeeper = new \Zookeeper('localhost1:2181,localhost2:2181,localhost3:2181');

$store = new ZookeeperStore($zookeeper);

Remote Stores

Remote stores (MemcachedStore, MongoDbStore, PdoStore, PostgreSqlStore, RedisStore and ZookeeperStore) use a 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.

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

Expiring Stores

Expiring stores (MemcachedStore, MongoDbStore, PdoStore 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 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('pdf-creation', 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 seconds
}

By design, locks are stored on 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 store 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 containers running 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 any time.

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.

MongoDbStore

A TTL index must be used to automatically clean up expired locks. Such an index can be created manually:

1
2
3
4

db.lock.createIndex(
    { "expires_at": 1 },
    { "expireAfterSeconds": 0 }
)

Alternatively, the method MongoDbStore::createTtlIndex(int $expireAfterSeconds = 0) can be called once to create the TTL index during database setup. Read more about Expire Data from Collections by Setting TTL in MongoDB.

writeConcern and readConcern are not specified by MongoDbStore meaning the collection's settings will take effect. readPreference is primary for all queries. Read more about Replica Set Read and Write Semantics in MongoDB.

PdoStore

The PdoStore relies on the ACID properties of the SQL engine.

In order to purge old locks, this store uses a current datetime to define an expiration date reference. This mechanism relies on all server nodes to have synchronized clocks.

PostgreSqlStore

The PostgreSqlStore relies on the Advisory Locks properties of the PostgreSQL database. That means that by using PostgreSqlStore the locks will be automatically released at the end of the session in case the client cannot unlock for any reason.

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

If the TCP connection is lost, the PostgreSQL may release locks without notifying the application.

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 any time.

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 the storage of 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.

ZookeeperStore

The way ZookeeperStore works is by maintaining locks as ephemeral nodes on the server. That means that by using ZookeeperStore the locks will be automatically released at the end of the session in case the client cannot unlock for any reason.

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

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.