[Filesystem] Added documentation for the new LockHandler

Author: lyrixx

components/filesystem/lockhandler.rst

@@ -1,2 +1,51 @@
-Lockhandler
+LockHandler
 ===========
+
+.. versionadded:: 2.6
+    The Lock handler feature was introduced in Symfony 2.6
+
+What is a Lock?
+---------------
+
+    In computer science, a lock is a synchronization mechanism for enforcing
+    limits on access to a resource in an environment where there are many
+    threads of execution. A lock is designed to enforce a mutual exclusion
+    concurrency control policy.
+
+    -- `Wikipedia`_
+
+Usage
+-----
+
+.. caution::
+
+    This lock handler works only when using one and only one host. 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.
+
+Usage::
+
+    use Symfony\Component\Filesystem\LockHandler;
+
+    $lockHandler = new LockHelper('hello.lock');
+    if (!$lockHandler->lock()) {
+        'The resource "hello" is already locked by another process.');
+
+        return 0;
+    }
+
+The first argument of the ``LockHelper`` is used to create a file on the local
+filesystem. By default, the LockHelper will create the file in the temporary
+directory. Another directory can be chosen by using the second argument.
+
+The ``lock`` method tries to acquire the lock. If the lock is acquired, the
+method returns ``true``, false otherwise. If the method ``lock`` method is
+called severals times it will always return ``true`` if the lack was acquired on
+the first call.
+
+The ``release`` method release the lock. So after the release, another process
+can lock the resource. The release is always released by PHP at the end of the
+script.
+
+.. _Wikipedia: http://en.wikipedia.org/wiki/Lock_%28computer_science%29