file: Add LOCK subcommand to do file and directory locking

Provide options to fail without blocking or to block up to a timeout.
Provide options to specify the scope containing the lock so it can be
released automatically at the end of a function, file, or process.

Extend the RunCMake.file test with cases covering the file(LOCK) command
usage and error cases.

1 files changed, 30 insertions, 0 deletions

diff --git a/Help/command/file.rst b/Help/command/file.rst
index dbc4149..600464e 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -305,3 +305,33 @@ status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable),
 and ``NO_SOURCE_PERMISSIONS`` is default.
 Installation scripts generated by the :command:`install` command
 use this signature (with some undocumented options for internal use).
+
+------------------------------------------------------------------------------
+
+::
+
+  file(LOCK <path> [DIRECTORY] [RELEASE]
+       [GUARD <FUNCTION|FILE|PROCESS>]
+       [RESULT_VARIABLE <variable>]
+       [TIMEOUT <seconds>])
+
+Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file
+``<path>/cmake.lock`` otherwise. File will be locked for scope defined by
+``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used
+to unlock file explicitly. If option ``TIMEOUT`` is not specified CMake will
+wait until lock succeed or until fatal error occurs. If ``TIMEOUT`` is set to
+``0`` lock will be tried once and result will be reported immediately. If
+``TIMEOUT`` is not ``0`` CMake will try to lock file for the period specified
+by ``<seconds>`` value. Any errors will be interpreted as fatal if there is no
+``RESULT_VARIABLE`` option. Otherwise result will be stored in ``<variable>``
+and will be ``0`` on success or error message on failure.
+
+Note that lock is advisory - there is no guarantee that other processes will
+respect this lock, i.e. lock synchronize two or more CMake instances sharing
+some modifiable resources. Similar logic applied to ``DIRECTORY`` option -
+locking parent directory doesn't prevent other ``LOCK`` commands to lock any
+child directory or file.
+
+Trying to lock file twice is not allowed.  Any intermediate directories and
+file itself will be created if they not exist.  ``GUARD`` and ``TIMEOUT``
+options ignored on ``RELEASE`` operation.