From 82a9635dbdc61d44c70ff31431822ea962fdfa39 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 23 Jan 2015 11:33:53 +0100 Subject: [PATCH 1/4] Reworded the explanation about when a lock is released --- components/filesystem/lock_handler.rst | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/components/filesystem/lock_handler.rst b/components/filesystem/lock_handler.rst index d57889190ef..723df1c63e1 100644 --- a/components/filesystem/lock_handler.rst +++ b/components/filesystem/lock_handler.rst @@ -62,8 +62,23 @@ You can pass an optional blocking argument as the first argument to the ``lock()`` method, which defaults to ``false``. If this is set to ``true``, your PHP code will wait indefinitely until the lock is released by another process. -The resource is automatically released by PHP at the end of the script. In -addition, you can invoke the -:method:`Symfony\\Component\\Filesystem\\LockHandler::release` method to release -the lock explicitly. Once it's released, any other process can lock the -resource. +Beware that the resource lock is automatically released as soon as PHP applies the +garbage-collection process to the ``LockHandler`` object. This means that if you +refactor the first example showed in this article as follows: + +.. code-block:: php + + use Symfony\Component\Filesystem\LockHandler; + + if (!(new LockHandler('hello.lock'))->lock()) { + // the resource "hello" is already locked by another process + + return 0; + } + +Now the code won't work as expected, because PHP's garbage collection mechanism +removes the reference to the ``LockHandler`` object and thus, the lock is released +just after it's been created. + +Another alternative way to release the lock explicitly when needed is to use the +:method:`Symfony\\Component\\Filesystem\\LockHandler::release` method. From 89a73200ccfdf2df154fafc4c1f7710354adb1f0 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 2 Feb 2015 16:47:06 +0100 Subject: [PATCH 2/4] Added the new documentation inside a "caution" admonition --- components/filesystem/lock_handler.rst | 30 ++++++++++++++------------ 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/components/filesystem/lock_handler.rst b/components/filesystem/lock_handler.rst index 723df1c63e1..26c423bc9f4 100644 --- a/components/filesystem/lock_handler.rst +++ b/components/filesystem/lock_handler.rst @@ -62,23 +62,25 @@ You can pass an optional blocking argument as the first argument to the ``lock()`` method, which defaults to ``false``. If this is set to ``true``, your PHP code will wait indefinitely until the lock is released by another process. -Beware that the resource lock is automatically released as soon as PHP applies the -garbage-collection process to the ``LockHandler`` object. This means that if you -refactor the first example showed in this article as follows: +.. caution:: -.. code-block:: php + Beware that the resource lock is automatically released as soon as PHP applies + the garbage-collection process to the ``LockHandler`` object. This means that + if you refactor the first example showed in this article as follows: - use Symfony\Component\Filesystem\LockHandler; + .. code-block:: php - if (!(new LockHandler('hello.lock'))->lock()) { - // the resource "hello" is already locked by another process + use Symfony\Component\Filesystem\LockHandler; - return 0; - } + if (!(new LockHandler('hello.lock'))->lock()) { + // the resource "hello" is already locked by another process + + return 0; + } -Now the code won't work as expected, because PHP's garbage collection mechanism -removes the reference to the ``LockHandler`` object and thus, the lock is released -just after it's been created. + Now the code won't work as expected, because PHP's garbage collection mechanism + removes the reference to the ``LockHandler`` object and thus, the lock is released + just after it's been created. -Another alternative way to release the lock explicitly when needed is to use the -:method:`Symfony\\Component\\Filesystem\\LockHandler::release` method. + Another alternative way to release the lock explicitly when needed is to use the + :method:`Symfony\\Component\\Filesystem\\LockHandler::release` method. From e632d49d763c737575d4c5a3957bd17222dd4fb3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Feb 2015 12:31:11 +0100 Subject: [PATCH 3/4] Fixed the errors spotted by Wouter --- components/filesystem/lock_handler.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/components/filesystem/lock_handler.rst b/components/filesystem/lock_handler.rst index 26c423bc9f4..36fe49e271e 100644 --- a/components/filesystem/lock_handler.rst +++ b/components/filesystem/lock_handler.rst @@ -64,11 +64,10 @@ PHP code will wait indefinitely until the lock is released by another process. .. caution:: - Beware that the resource lock is automatically released as soon as PHP applies - the garbage-collection process to the ``LockHandler`` object. This means that - if you refactor the first example showed in this article as follows: - - .. code-block:: php + Be aware of the fact that the resource lock is automatically released as soon + as PHP applies the garbage-collection process to the ``LockHandler`` object. + This means that if you refactor the first example showed in this article as + follows:: use Symfony\Component\Filesystem\LockHandler; From 6e14bac0aff5d0430b16b424b0126aae50e06bde Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Feb 2015 19:22:09 +0100 Subject: [PATCH 4/4] Fixed minor grammar issues --- components/filesystem/lock_handler.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/filesystem/lock_handler.rst b/components/filesystem/lock_handler.rst index 36fe49e271e..5d442e79547 100644 --- a/components/filesystem/lock_handler.rst +++ b/components/filesystem/lock_handler.rst @@ -66,7 +66,7 @@ PHP code will wait indefinitely until the lock is released by another process. Be aware of the fact that the resource lock is automatically released as soon as PHP applies the garbage-collection process to the ``LockHandler`` object. - This means that if you refactor the first example showed in this article as + This means that if you refactor the first example shown in this article as follows:: use Symfony\Component\Filesystem\LockHandler; @@ -77,7 +77,7 @@ PHP code will wait indefinitely until the lock is released by another process. return 0; } - Now the code won't work as expected, because PHP's garbage collection mechanism + Now the code won't work as expected because PHP's garbage collection mechanism removes the reference to the ``LockHandler`` object and thus, the lock is released just after it's been created.