|
| 1 | +LockHandler |
| 2 | +=========== |
| 3 | + |
| 4 | +.. versionadded:: 2.6 |
| 5 | + The lock handler feature was introduced in Symfony 2.6 |
| 6 | + |
| 7 | +What is a Lock? |
| 8 | +--------------- |
| 9 | + |
| 10 | +File locking is a mechanism that restricts access to a computer file by allowing |
| 11 | +only one user or process access at any specific time. This mechanism was |
| 12 | +introduced a few decades ago for mainframes, but continues being useful for |
| 13 | +modern applications. |
| 14 | + |
| 15 | +Symfony provides a LockHelper to help you use locks in your project. |
| 16 | + |
| 17 | +Usage |
| 18 | +----- |
| 19 | + |
| 20 | +.. caution:: |
| 21 | + |
| 22 | + The lock handler only works if you're using just one server. If you have |
| 23 | + several hosts, you must not use this helper. |
| 24 | + |
| 25 | +A lock can be used, for example, to allow only one instance of a command to run. |
| 26 | + |
| 27 | +.. code-block:: php |
| 28 | +
|
| 29 | + use Symfony\Component\Filesystem\LockHandler; |
| 30 | +
|
| 31 | + $lockHandler = new LockHandler('hello.lock'); |
| 32 | + if (!$lockHandler->lock()) { |
| 33 | + // the resource "hello" is already locked by another process |
| 34 | +
|
| 35 | + return 0; |
| 36 | + } |
| 37 | +
|
| 38 | +The first argument of the constructor is a string that it will use as part of |
| 39 | +the name of the file used to create the lock on the local filesystem. A best |
| 40 | +practice for Symfony commands is to use the command name, such as ``acme:my-command``. |
| 41 | +``LockHandler`` sanitizes the contents of the string before creating |
| 42 | +the file, so you can pass any value for this argument. |
| 43 | + |
| 44 | +.. tip:: |
| 45 | + |
| 46 | + The ``.lock`` extension is optional, but it's a common practice to include |
| 47 | + it. This will make it easier to find lock files on the filesystem. Moreover, |
| 48 | + to avoid name collisions, ``LockHandler`` also appends a hash to the name of |
| 49 | + the lock file. |
| 50 | + |
| 51 | +By default, the lock will be created in the temporary directory, but you can |
| 52 | +optionally select the directory where locks are created by passing it as the |
| 53 | +second argument of the constructor. |
| 54 | + |
| 55 | +The :method:`Symfony\\Component\\Filesystem\\LockHandler::lock` method tries to |
| 56 | +acquire the lock. If the lock is acquired, the method returns ``true``, |
| 57 | +``false`` otherwise. If the ``lock`` method is called several times on the same |
| 58 | +instance it will always return ``true`` if the lock was acquired on the first |
| 59 | +call. |
| 60 | + |
| 61 | +You can pass an optional blocking argument as the first argument to the |
| 62 | +``lock()`` method, which defaults to ``false``. If this is set to ``true``, your |
| 63 | +PHP code will wait indefinitely until the lock is released by another process. |
| 64 | + |
| 65 | +The resource is automatically released by PHP at the end of the script. In |
| 66 | +addition, you can invoke the |
| 67 | +:method:`Symfony\\Component\\Filesystem\\LockHandler::release` method to release |
| 68 | +the lock explicitly. Once it's released, any other process can lock the |
| 69 | +resource. |
0 commit comments