From 2bf8c55a79474a3750c92891797969c706e59528 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Pineau?= Date: Mon, 22 Sep 2014 19:36:36 +0200 Subject: [PATCH 1/2] [Filesystem] Moved current document to a dedicated folder --- components/{ => filesystem}/filesystem.rst | 21 ++------------------- components/filesystem/index.rst | 9 +++++++++ components/filesystem/introduction.rst | 16 ++++++++++++++++ components/filesystem/lockhandler.rst | 2 ++ components/index.rst | 2 +- redirection_map | 1 + 6 files changed, 31 insertions(+), 20 deletions(-) rename components/{ => filesystem}/filesystem.rst (92%) create mode 100644 components/filesystem/index.rst create mode 100644 components/filesystem/introduction.rst create mode 100644 components/filesystem/lockhandler.rst diff --git a/components/filesystem.rst b/components/filesystem/filesystem.rst similarity index 92% rename from components/filesystem.rst rename to components/filesystem/filesystem.rst index 076d7c38d1f..e41dfd0b98b 100644 --- a/components/filesystem.rst +++ b/components/filesystem/filesystem.rst @@ -1,22 +1,5 @@ -.. index:: - single: Filesystem - -The Filesystem Component -======================== - - The Filesystem component provides basic utilities for the filesystem. - -.. versionadded:: 2.1 - The Filesystem component was introduced in Symfony 2.1. Previously, the - ``Filesystem`` class was located in the HttpKernel component. - -Installation ------------- - -You can install the component in 2 different ways: - -* :doc:`Install it via Composer ` (``symfony/filesystem`` on `Packagist`_); -* Use the official Git repository (https://github.com/symfony/Filesystem). +Filesystem +========== Usage ----- diff --git a/components/filesystem/index.rst b/components/filesystem/index.rst new file mode 100644 index 00000000000..b3629ef0af9 --- /dev/null +++ b/components/filesystem/index.rst @@ -0,0 +1,9 @@ +Filesystem +========== + +.. toctree:: + :maxdepth: 2 + + introduction + filesystem + lockhandler diff --git a/components/filesystem/introduction.rst b/components/filesystem/introduction.rst new file mode 100644 index 00000000000..15c8d46628a --- /dev/null +++ b/components/filesystem/introduction.rst @@ -0,0 +1,16 @@ +The Filesystem Component +======================== + + The Filesystem component provides basic utilities for the filesystem. + +.. versionadded:: 2.1 + The Filesystem component was introduced in Symfony 2.1. Previously, the + ``Filesystem`` class was located in the HttpKernel component. + +Installation +------------ + +You can install the component in 2 different ways: + +* :doc:`Install it via Composer ` (``symfony/filesystem`` on `Packagist`_); +* Use the official Git repository (https://github.com/symfony/Filesystem). diff --git a/components/filesystem/lockhandler.rst b/components/filesystem/lockhandler.rst new file mode 100644 index 00000000000..30aa687bd9b --- /dev/null +++ b/components/filesystem/lockhandler.rst @@ -0,0 +1,2 @@ +Lockhandler +=========== diff --git a/components/index.rst b/components/index.rst index 8e167cd2ac9..91b3dfc466a 100644 --- a/components/index.rst +++ b/components/index.rst @@ -14,7 +14,7 @@ The Components dom_crawler event_dispatcher/index expression_language/index - filesystem + filesystem/index finder form/index http_foundation/index diff --git a/redirection_map b/redirection_map index 1a6758a5560..33d8293f670 100644 --- a/redirection_map +++ b/redirection_map @@ -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 From 909a2940c86110752c7401bf9998aac479712cc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Pineau?= Date: Mon, 22 Sep 2014 20:00:46 +0200 Subject: [PATCH 2/2] [Filesystem] Added documentation for the new LockHandler --- components/filesystem/filesystem.rst | 253 ------------------------ components/filesystem/index.rst | 3 +- components/filesystem/introduction.rst | 260 +++++++++++++++++++++++++ components/filesystem/lock_handler.rst | 69 +++++++ components/filesystem/lockhandler.rst | 2 - components/map.rst.inc | 5 +- 6 files changed, 333 insertions(+), 259 deletions(-) delete mode 100644 components/filesystem/filesystem.rst create mode 100644 components/filesystem/lock_handler.rst delete mode 100644 components/filesystem/lockhandler.rst diff --git a/components/filesystem/filesystem.rst b/components/filesystem/filesystem.rst deleted file mode 100644 index e41dfd0b98b..00000000000 --- a/components/filesystem/filesystem.rst +++ /dev/null @@ -1,253 +0,0 @@ -Filesystem -========== - -Usage ------ - -The :class:`Symfony\\Component\\Filesystem\\Filesystem` class is the unique -endpoint for filesystem operations:: - - use Symfony\Component\Filesystem\Filesystem; - use Symfony\Component\Filesystem\Exception\IOExceptionInterface; - - $fs = new Filesystem(); - - try { - $fs->mkdir('/tmp/random/dir/' . mt_rand()); - } catch (IOExceptionInterface $e) { - echo "An error occurred while creating your directory at ".$e->getPath(); - } - -.. versionadded:: 2.4 - The ``IOExceptionInterface`` and its ``getPath`` method were introduced in - Symfony 2.4. Prior to 2.4, you would catch the ``IOException`` class. - -.. note:: - - Methods :method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir`, - :method:`Symfony\\Component\\Filesystem\\Filesystem::exists`, - :method:`Symfony\\Component\\Filesystem\\Filesystem::touch`, - :method:`Symfony\\Component\\Filesystem\\Filesystem::remove`, - :method:`Symfony\\Component\\Filesystem\\Filesystem::chmod`, - :method:`Symfony\\Component\\Filesystem\\Filesystem::chown` and - :method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` can receive a - string, an array or any object implementing :phpclass:`Traversable` as - the target argument. - -Mkdir -~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir` creates a directory. -On posix filesystems, directories are created with a default mode value -`0777`. You can use the second argument to set your own mode:: - - $fs->mkdir('/tmp/photos', 0700); - -.. note:: - - You can pass an array or any :phpclass:`Traversable` object as the first - argument. - -Exists -~~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::exists` checks for the -presence of all files or directories and returns ``false`` if a file is missing:: - - // this directory exists, return true - $fs->exists('/tmp/photos'); - - // rabbit.jpg exists, bottle.png does not exists, return false - $fs->exists(array('rabbit.jpg', 'bottle.png')); - -.. note:: - - You can pass an array or any :phpclass:`Traversable` object as the first - argument. - -Copy -~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::copy` is used to copy -files. If the target already exists, the file is copied only if the source -modification date is later than the target. This behavior can be overridden by -the third boolean argument:: - - // works only if image-ICC has been modified after image.jpg - $fs->copy('image-ICC.jpg', 'image.jpg'); - - // image.jpg will be overridden - $fs->copy('image-ICC.jpg', 'image.jpg', true); - -Touch -~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::touch` sets access and -modification time for a file. The current time is used by default. You can set -your own with the second argument. The third argument is the access time:: - - // set modification time to the current timestamp - $fs->touch('file.txt'); - // set modification time 10 seconds in the future - $fs->touch('file.txt', time() + 10); - // set access time 10 seconds in the past - $fs->touch('file.txt', time(), time() - 10); - -.. note:: - - You can pass an array or any :phpclass:`Traversable` object as the first - argument. - -Chown -~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::chown` is used to change -the owner of a file. The third argument is a boolean recursive option:: - - // set the owner of the lolcat video to www-data - $fs->chown('lolcat.mp4', 'www-data'); - // change the owner of the video directory recursively - $fs->chown('/video', 'www-data', true); - -.. note:: - - You can pass an array or any :phpclass:`Traversable` object as the first - argument. - -Chgrp -~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` is used to change -the group of a file. The third argument is a boolean recursive option:: - - // set the group of the lolcat video to nginx - $fs->chgrp('lolcat.mp4', 'nginx'); - // change the group of the video directory recursively - $fs->chgrp('/video', 'nginx', true); - -.. note:: - - You can pass an array or any :phpclass:`Traversable` object as the first - argument. - -Chmod -~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::chmod` is used to change -the mode of a file. The fourth argument is a boolean recursive option:: - - // set the mode of the video to 0600 - $fs->chmod('video.ogg', 0600); - // change the mod of the src directory recursively - $fs->chmod('src', 0700, 0000, true); - -.. note:: - - You can pass an array or any :phpclass:`Traversable` object as the first - argument. - -Remove -~~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` is used to remove -files, symlinks, directories easily:: - - $fs->remove(array('symlink', '/path/to/directory', 'activity.log')); - -.. note:: - - You can pass an array or any :phpclass:`Traversable` object as the first - argument. - -Rename -~~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::rename` is used to rename -files and directories:: - - // rename a file - $fs->rename('/tmp/processed_video.ogg', '/path/to/store/video_647.ogg'); - // rename a directory - $fs->rename('/tmp/files', '/path/to/store/files'); - -symlink -~~~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::symlink` creates a -symbolic link from the target to the destination. If the filesystem does not -support symbolic links, a third boolean argument is available:: - - // create a symbolic link - $fs->symlink('/path/to/source', '/path/to/destination'); - // duplicate the source directory if the filesystem - // does not support symbolic links - $fs->symlink('/path/to/source', '/path/to/destination', true); - -makePathRelative -~~~~~~~~~~~~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::makePathRelative` returns -the relative path of a directory given another one:: - - // returns '../' - $fs->makePathRelative( - '/var/lib/symfony/src/Symfony/', - '/var/lib/symfony/src/Symfony/Component' - ); - // returns 'videos/' - $fs->makePathRelative('/tmp/videos', '/tmp') - -mirror -~~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` mirrors a -directory:: - - $fs->mirror('/path/to/source', '/path/to/target'); - -isAbsolutePath -~~~~~~~~~~~~~~ - -:method:`Symfony\\Component\\Filesystem\\Filesystem::isAbsolutePath` returns -``true`` if the given path is absolute, ``false`` otherwise:: - - // return true - $fs->isAbsolutePath('/tmp'); - // return true - $fs->isAbsolutePath('c:\\Windows'); - // return false - $fs->isAbsolutePath('tmp'); - // return false - $fs->isAbsolutePath('../dir'); - -dumpFile -~~~~~~~~ - -.. versionadded:: 2.3 - The ``dumpFile()`` was introduced in Symfony 2.3. - -:method:`Symfony\\Component\\Filesystem\\Filesystem::dumpFile` allows you to -dump contents to a file. It does this in an atomic manner: it writes a temporary -file first and then moves it to the new file location when it's finished. -This means that the user will always see either the complete old file or -complete new file (but never a partially-written file):: - - $fs->dumpFile('file.txt', 'Hello World'); - -The ``file.txt`` file contains ``Hello World`` now. - -A desired file mode can be passed as the third argument. - -Error Handling --------------- - -Whenever something wrong happens, an exception implementing -:class:`Symfony\\Component\\Filesystem\\Exception\\ExceptionInterface` or -:class:`Symfony\\Component\\Filesystem\\Exception\\IOExceptionInterface` is thrown. - -.. note:: - - An :class:`Symfony\\Component\\Filesystem\\Exception\\IOException` is - thrown if directory creation fails. - -.. _`Packagist`: https://packagist.org/packages/symfony/filesystem diff --git a/components/filesystem/index.rst b/components/filesystem/index.rst index b3629ef0af9..e643f5a90f4 100644 --- a/components/filesystem/index.rst +++ b/components/filesystem/index.rst @@ -5,5 +5,4 @@ Filesystem :maxdepth: 2 introduction - filesystem - lockhandler + lock_handler diff --git a/components/filesystem/introduction.rst b/components/filesystem/introduction.rst index 15c8d46628a..8990198aa41 100644 --- a/components/filesystem/introduction.rst +++ b/components/filesystem/introduction.rst @@ -1,3 +1,6 @@ +.. index:: + single: Filesystem + The Filesystem Component ======================== @@ -7,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 `. + Installation ------------ @@ -14,3 +23,254 @@ You can install the component in 2 different ways: * :doc:`Install it via Composer ` (``symfony/filesystem`` on `Packagist`_); * Use the official Git repository (https://github.com/symfony/Filesystem). + +Usage +----- + +The :class:`Symfony\\Component\\Filesystem\\Filesystem` class is the unique +endpoint for filesystem operations:: + + use Symfony\Component\Filesystem\Filesystem; + use Symfony\Component\Filesystem\Exception\IOExceptionInterface; + + $fs = new Filesystem(); + + try { + $fs->mkdir('/tmp/random/dir/' . mt_rand()); + } catch (IOExceptionInterface $e) { + echo "An error occurred while creating your directory at ".$e->getPath(); + } + +.. versionadded:: 2.4 + The ``IOExceptionInterface`` and its ``getPath`` method were introduced in + Symfony 2.4. Prior to 2.4, you would catch the ``IOException`` class. + +.. note:: + + Methods :method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir`, + :method:`Symfony\\Component\\Filesystem\\Filesystem::exists`, + :method:`Symfony\\Component\\Filesystem\\Filesystem::touch`, + :method:`Symfony\\Component\\Filesystem\\Filesystem::remove`, + :method:`Symfony\\Component\\Filesystem\\Filesystem::chmod`, + :method:`Symfony\\Component\\Filesystem\\Filesystem::chown` and + :method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` can receive a + string, an array or any object implementing :phpclass:`Traversable` as + the target argument. + +Mkdir +~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir` creates a directory. +On posix filesystems, directories are created with a default mode value +`0777`. You can use the second argument to set your own mode:: + + $fs->mkdir('/tmp/photos', 0700); + +.. note:: + + You can pass an array or any :phpclass:`Traversable` object as the first + argument. + +Exists +~~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::exists` checks for the +presence of all files or directories and returns ``false`` if a file is missing:: + + // this directory exists, return true + $fs->exists('/tmp/photos'); + + // rabbit.jpg exists, bottle.png does not exists, return false + $fs->exists(array('rabbit.jpg', 'bottle.png')); + +.. note:: + + You can pass an array or any :phpclass:`Traversable` object as the first + argument. + +Copy +~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::copy` is used to copy +files. If the target already exists, the file is copied only if the source +modification date is later than the target. This behavior can be overridden by +the third boolean argument:: + + // works only if image-ICC has been modified after image.jpg + $fs->copy('image-ICC.jpg', 'image.jpg'); + + // image.jpg will be overridden + $fs->copy('image-ICC.jpg', 'image.jpg', true); + +Touch +~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::touch` sets access and +modification time for a file. The current time is used by default. You can set +your own with the second argument. The third argument is the access time:: + + // set modification time to the current timestamp + $fs->touch('file.txt'); + // set modification time 10 seconds in the future + $fs->touch('file.txt', time() + 10); + // set access time 10 seconds in the past + $fs->touch('file.txt', time(), time() - 10); + +.. note:: + + You can pass an array or any :phpclass:`Traversable` object as the first + argument. + +Chown +~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::chown` is used to change +the owner of a file. The third argument is a boolean recursive option:: + + // set the owner of the lolcat video to www-data + $fs->chown('lolcat.mp4', 'www-data'); + // change the owner of the video directory recursively + $fs->chown('/video', 'www-data', true); + +.. note:: + + You can pass an array or any :phpclass:`Traversable` object as the first + argument. + +Chgrp +~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` is used to change +the group of a file. The third argument is a boolean recursive option:: + + // set the group of the lolcat video to nginx + $fs->chgrp('lolcat.mp4', 'nginx'); + // change the group of the video directory recursively + $fs->chgrp('/video', 'nginx', true); + +.. note:: + + You can pass an array or any :phpclass:`Traversable` object as the first + argument. + +Chmod +~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::chmod` is used to change +the mode of a file. The fourth argument is a boolean recursive option:: + + // set the mode of the video to 0600 + $fs->chmod('video.ogg', 0600); + // change the mod of the src directory recursively + $fs->chmod('src', 0700, 0000, true); + +.. note:: + + You can pass an array or any :phpclass:`Traversable` object as the first + argument. + +Remove +~~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` is used to remove +files, symlinks, directories easily:: + + $fs->remove(array('symlink', '/path/to/directory', 'activity.log')); + +.. note:: + + You can pass an array or any :phpclass:`Traversable` object as the first + argument. + +Rename +~~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::rename` is used to rename +files and directories:: + + // rename a file + $fs->rename('/tmp/processed_video.ogg', '/path/to/store/video_647.ogg'); + // rename a directory + $fs->rename('/tmp/files', '/path/to/store/files'); + +symlink +~~~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::symlink` creates a +symbolic link from the target to the destination. If the filesystem does not +support symbolic links, a third boolean argument is available:: + + // create a symbolic link + $fs->symlink('/path/to/source', '/path/to/destination'); + // duplicate the source directory if the filesystem + // does not support symbolic links + $fs->symlink('/path/to/source', '/path/to/destination', true); + +makePathRelative +~~~~~~~~~~~~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::makePathRelative` returns +the relative path of a directory given another one:: + + // returns '../' + $fs->makePathRelative( + '/var/lib/symfony/src/Symfony/', + '/var/lib/symfony/src/Symfony/Component' + ); + // returns 'videos/' + $fs->makePathRelative('/tmp/videos', '/tmp') + +mirror +~~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::mirror` mirrors a +directory:: + + $fs->mirror('/path/to/source', '/path/to/target'); + +isAbsolutePath +~~~~~~~~~~~~~~ + +:method:`Symfony\\Component\\Filesystem\\Filesystem::isAbsolutePath` returns +``true`` if the given path is absolute, ``false`` otherwise:: + + // return true + $fs->isAbsolutePath('/tmp'); + // return true + $fs->isAbsolutePath('c:\\Windows'); + // return false + $fs->isAbsolutePath('tmp'); + // return false + $fs->isAbsolutePath('../dir'); + +dumpFile +~~~~~~~~ + +.. versionadded:: 2.3 + The ``dumpFile()`` was introduced in Symfony 2.3. + +:method:`Symfony\\Component\\Filesystem\\Filesystem::dumpFile` allows you to +dump contents to a file. It does this in an atomic manner: it writes a temporary +file first and then moves it to the new file location when it's finished. +This means that the user will always see either the complete old file or +complete new file (but never a partially-written file):: + + $fs->dumpFile('file.txt', 'Hello World'); + +The ``file.txt`` file contains ``Hello World`` now. + +A desired file mode can be passed as the third argument. + +Error Handling +-------------- + +Whenever something wrong happens, an exception implementing +:class:`Symfony\\Component\\Filesystem\\Exception\\ExceptionInterface` or +:class:`Symfony\\Component\\Filesystem\\Exception\\IOExceptionInterface` is thrown. + +.. note:: + + An :class:`Symfony\\Component\\Filesystem\\Exception\\IOException` is + thrown if directory creation fails. + +.. _`Packagist`: https://packagist.org/packages/symfony/filesystem diff --git a/components/filesystem/lock_handler.rst b/components/filesystem/lock_handler.rst new file mode 100644 index 00000000000..d57889190ef --- /dev/null +++ b/components/filesystem/lock_handler.rst @@ -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. diff --git a/components/filesystem/lockhandler.rst b/components/filesystem/lockhandler.rst deleted file mode 100644 index 30aa687bd9b..00000000000 --- a/components/filesystem/lockhandler.rst +++ /dev/null @@ -1,2 +0,0 @@ -Lockhandler -=========== diff --git a/components/map.rst.inc b/components/map.rst.inc index f9eab711e07..1bccb80fb61 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -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**