Permalink
Browse files

feature #3956 [Command] Added LockHelper (lyrixx)

This PR was merged into the master branch.

Discussion
----------

[Command] Added LockHelper

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes symfony/symfony#10475
| Applies to    | Symfony version 2.6+
| Fixed tickets | -

Commits
-------

909a294 [Filesystem] Added documentation for the new LockHandler
2bf8c55 [Filesystem] Moved current document to a dedicated folder
  • Loading branch information...
weaverryan committed Oct 18, 2014
2 parents 39b4430 + 909a294 commit 0f34bb861128116c2f8267575746fc01d5c2fbfc
@@ -0,0 +1,8 @@
Filesystem
==========
.. toctree::
:maxdepth: 2
introduction
lock_handler
@@ -10,6 +10,12 @@ The Filesystem Component
The Filesystem component was introduced in Symfony 2.1. Previously, the
``Filesystem`` class was located in the HttpKernel component.
.. tip::
A lock handler feature was introduce in symfony 2.6.
:doc:`See the documentation for more information </components/filesystem/lock_handler>`.
Installation
------------
@@ -0,0 +1,69 @@
LockHandler
===========
.. versionadded:: 2.6
The lock handler feature was introduced in Symfony 2.6
What is a Lock?
---------------
File locking is a mechanism that restricts access to a computer file by allowing
only one user or process access at any specific time. This mechanism was
introduced a few decades ago for mainframes, but continues being useful for
modern applications.
Symfony provides a LockHelper to help you use locks in your project.
Usage
-----
.. caution::
The lock handler only works if you're using just one server. If you have
several hosts, you must not use this helper.
A lock can be used, for example, to allow only one instance of a command to run.
.. code-block:: php
use Symfony\Component\Filesystem\LockHandler;
$lockHandler = new LockHandler('hello.lock');
if (!$lockHandler->lock()) {
// the resource "hello" is already locked by another process
return 0;
}
The first argument of the constructor is a string that it will use as part of
the name of the file used to create the lock on the local filesystem. A best
practice for Symfony commands is to use the command name, such as ``acme:my-command``.
``LockHandler`` sanitizes the contents of the string before creating
the file, so you can pass any value for this argument.
.. tip::
The ``.lock`` extension is optional, but it's a common practice to include
it. This will make it easier to find lock files on the filesystem. Moreover,
to avoid name collisions, ``LockHandler`` also appends a hash to the name of
the lock file.
By default, the lock will be created in the temporary directory, but you can
optionally select the directory where locks are created by passing it as the
second argument of the constructor.
The :method:`Symfony\\Component\\Filesystem\\LockHandler::lock` method tries to
acquire the lock. If the lock is acquired, the method returns ``true``,
``false`` otherwise. If the ``lock`` method is called several times on the same
instance it will always return ``true`` if the lock was acquired on the first
call.
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.
@@ -14,7 +14,7 @@ The Components
dom_crawler
event_dispatcher/index
expression_language/index
filesystem
filesystem/index
finder
form/index
http_foundation/index
@@ -70,9 +70,10 @@
* :doc:`/components/expression_language/extending`
* :doc:`/components/expression_language/caching`
* **Filesystem**
* :doc:`/components/filesystem/index`
* :doc:`/components/filesystem`
* :doc:`/components/filesystem/introduction`
* :doc:`/components/filesystem/lock_handler`
* **Finder**
@@ -22,6 +22,7 @@
/cookbook/console/generating_urls /cookbook/console/sending_emails
/components/yaml /components/yaml/introduction
/components/templating /components/templating/introduction
/components/filesystem /components/filesystem/introduction
/cmf/reference/configuration/block /cmf/bundles/block/configuration
/cmf/reference/configuration/content /cmf/bundles/content/configuration
/cmf/reference/configuration/core /cmf/bundles/core/configuration

0 comments on commit 0f34bb8

Please sign in to comment.