Merge topic 'file-LOCK-command'

93017828 Help: Add notes for topic 'file-LOCK-command'
e6db4c5a file: Add LOCK subcommand to do file and directory locking
05d6531c cmSystemTools: Add StringToInt helper

2 files changed, 35 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.
diff --git a/Help/release/dev/file-LOCK-command.rst b/Help/release/dev/file-LOCK-command.rst
new file mode 100644
index 0000000..4b11e9e
--- /dev/null
+++ b/Help/release/dev/file-LOCK-command.rst
@@ -0,0 +1,5 @@
+file-LOCK-command
+-----------------
+
+* The :command:`file(LOCK)` subcommand was created to allow CMake
+  processes to synchronize through file and directory locks.