From d408dc43e734b8ae9750b132cc1bf730e25c2c63 Mon Sep 17 00:00:00 2001 From: Simon Date: Fri, 28 Oct 2022 18:31:14 +0100 Subject: [PATCH 1/4] remove warning from locks page --- docs/locks.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/docs/locks.md b/docs/locks.md index 11f76587b3..e59d094ae4 100644 --- a/docs/locks.md +++ b/docs/locks.md @@ -1,18 +1,5 @@ # Locks -!!! warning - This page will soon replace . - - ** - It still needs to be ported from *reStructuredText* (.rst) to *MarkDown* (.md), - and you can help with that! - ** - - - source: [`docs/Locks.rst` in `easybuilders/easybuild` repo](https://raw.githubusercontent.com/easybuilders/easybuild/develop/docs/Locks.rst) - - target: [`docs/locks.md` in `easybuilders/easybuild-docs` repo](https://github.com/easybuilders/easybuild-docs/tree/main/docs/locks.md) - - See for more information. - ```rst .. _locks: From 71400b95f6e0058d99731a32c8de7c76f10f2182 Mon Sep 17 00:00:00 2001 From: Simon Date: Fri, 28 Oct 2022 18:39:58 +0100 Subject: [PATCH 2/4] locks page --- docs/locks.md | 82 ++++++++++++++++++--------------------------------- 1 file changed, 29 insertions(+), 53 deletions(-) diff --git a/docs/locks.md b/docs/locks.md index e59d094ae4..671de521df 100644 --- a/docs/locks.md +++ b/docs/locks.md @@ -1,44 +1,34 @@ # Locks -```rst -.. _locks: - -Locks to prevent duplicate installations running at the same time -================================================================= +## Locks to prevent duplicate installations running at the same time Easybuild creates a lock before starting the installation of an easyconfig file, to avoid a collision between multiple installations running at the same time. If an EasyBuild session tries to install an easyconfig file when a lock for that installation already exists, -it will be automatically aborted with an error like "``Lock ... already exists, aborting!``". - -.. note:: Locking of installations was implemented in EasyBuild version 4.2.0 . +it will be automatically aborted with an error like "`Lock ... already exists, aborting!`". +!!! note + Locking of installations was implemented in EasyBuild version 4.2.0 . -.. contents:: - :depth: 3 - :backlinks: none -.. _locks_implementation: - -Locking implementation details ------------------------------- +### Locking implementation details Easybuild will create a lock when starting an installation if no corresponding lock exists yet, regardless of whether the installation was requested explicitly or is performed to resolve a dependency. -The name of the lock corresponds to the *full* path of the installation directory, with slashes (``/``) and -dashes (``-``) replaced by underscores (``_``), and with an additional ``.lock`` added at the end. +The name of the lock corresponds to the *full* path of the installation directory, with slashes (`/`) and +dashes (`-`) replaced by underscores (`_`), and with an additional `.lock` added at the end. -Locks are created in the :ref:`locks_dir`. +Locks are created in the [locks directory](#locks-directory). The lock created by EasyBuild is an empty directory (rather than a file), because that can be created more atomically on modern filesystems. -For example, if ``OpenFOAM-7-foss-2019b.eb`` is being installed to ``/apps/easybuild/software``, +For example, if `OpenFOAM-7-foss-2019b.eb` is being installed to `/apps/easybuild/software`, an empty directory that serves as a lock for this installation will be created at -``/apps/easybuild/software/.locks/_apps_easybuild_software_OpenFOAM_7_foss_2019b.lock`` -(assuming the default :ref:`locks_dir` is used). +`/apps/easybuild/software/.locks/_apps_easybuild_software_OpenFOAM_7_foss_2019b.lock` +(assuming the default [locks directory](#locks-directory) is used). A lock is automatically removed by Easybuild when the installation ends, regardless of whether the installation was successful or not. Therefore, new installations of the same easyconfig will be aborted in case of: @@ -47,61 +37,47 @@ was successful or not. Therefore, new installations of the same easyconfig will * a previous installation of the same easyconfig was abruptly interrupted; -.. _locks_removing: - -Removing locks --------------- +### Removing locks If a previous installation was abruptly interrupted and a lock was left in place, -it can be easily removed using the ``rmdir`` command (since the lock is actually an empty directory). +it can be easily removed using the `rmdir` command (since the lock is actually an empty directory). -.. _locks_configuration_options: - -Configuration options related to installation locks ---------------------------------------------------- +### Configuration options related to installation locks The behaviour of the locking mechanism in Easybuild can be tuned with the following configuration options: -.. _locks_ignore: - -Ignoring locks (``--ignore-locks``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#### Ignoring locks (`--ignore-locks`) -Using the ``--ignore-locks`` configuration option, you can instruct EasyBuild to ignore any existing locks. +Using the `--ignore-locks` configuration option, you can instruct EasyBuild to ignore any existing locks. Locks that exist are left untouched, even if the installation completes successfully. **Use this with caution, since installations may be (partially) overwritten if another EasyBuild session is also performing those installations!** -.. _locks_wait: +#### Waiting for locks to be removed (`--wait-on-lock`) -Waiting for locks to be removed (``--wait-on-lock``) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Using the ``--wait-on-lock`` configuration option, you can change how EasyBuild deals with existing locks, -by specifying how frequently EasyBuild should check whether an existing lock was removed. By specifying a non-zero value ``S``, +Using the `--wait-on-lock` configuration option, you can change how EasyBuild deals with existing locks, +by specifying how frequently EasyBuild should check whether an existing lock was removed. By specifying a non-zero value `S`, you can indicate how many seconds EasyBuild should wait before checking again whether the lock is still in place. -.. note:: EasyBuild will wait indefinitely for an existing lock to be removed if ``--wait-on-lock`` is set to a non-zero value... +!!! note + EasyBuild will wait indefinitely for an existing lock to be removed if `--wait-on-lock` is set to a non-zero value... - If the lock is never removed, the EasyBuild session will never terminate; it will keep checking every ``S`` seconds whether the lock is still in place. + If the lock is never removed, the EasyBuild session will never terminate; it will keep checking every `S` seconds whether the lock is still in place. -By default, EasyBuild will *abort* the installation with an error like "``Lock ... already exists, aborting!``" -if a corresponding lock already exists, which is equivalent to setting ``--wait-on-lock`` to zero (``0``), +By default, EasyBuild will *abort* the installation with an error like "`Lock ... already exists, aborting!`" +if a corresponding lock already exists, which is equivalent to setting `--wait-on-lock` to zero (`0`), implying that no waiting should be done at all. -.. _locks_dir: - -Locks directory ---------------- +### Locks directory -If desired, an alternate location where locks should be created and checked for can be specified via the ``--locks-dir`` configuration option. +If desired, an alternate location where locks should be created and checked for can be specified via the `--locks-dir` configuration option. -.. note:: Keep in mind that a path on a *shared* filesystem should be used, to ensure that active EasyBuild sessions running on different systems use the same locks directory. +!!! note + Keep in mind that a path on a *shared* filesystem should be used, to ensure that active EasyBuild sessions running on different systems use the same locks directory. -By default, locks are created in a hidden subdirectory ``.locks`` in the top-level ``software`` installation directory; that is, the ``software`` subdirectory of the ``installpath`` configuration setting of the active EasyBuild session. +By default, locks are created in a hidden subdirectory `.locks` in the top-level `software` installation directory; that is, the `software` subdirectory of the `installpath` configuration setting of the active EasyBuild session. -``` From d420c708bd48028fd1cf68c01878acec50ab93eb Mon Sep 17 00:00:00 2001 From: Simon Branford <4967+branfosj@users.noreply.github.com> Date: Wed, 2 Nov 2022 18:01:05 +0000 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: James Carpenter --- docs/locks.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/locks.md b/docs/locks.md index 671de521df..bdb76ab5c4 100644 --- a/docs/locks.md +++ b/docs/locks.md @@ -47,7 +47,9 @@ it can be easily removed using the `rmdir` command (since the lock is actually a The behaviour of the locking mechanism in Easybuild can be tuned with the following configuration options: -#### Ignoring locks (`--ignore-locks`) +#### Ignoring locks {: #locks_ignore } + +*(`--ignore-locks`)* Using the `--ignore-locks` configuration option, you can instruct EasyBuild to ignore any existing locks. Locks that exist are left untouched, even if the installation completes successfully. @@ -56,7 +58,9 @@ Locks that exist are left untouched, even if the installation completes successf performing those installations!** -#### Waiting for locks to be removed (`--wait-on-lock`) +#### Waiting for locks to be removed {: #locks_wait } + +*(`--wait-on-lock`)* Using the `--wait-on-lock` configuration option, you can change how EasyBuild deals with existing locks, by specifying how frequently EasyBuild should check whether an existing lock was removed. By specifying a non-zero value `S`, From 78255a6af830becaa894641a8a8d4ee22ef12bdd Mon Sep 17 00:00:00 2001 From: James Carpenter Date: Wed, 2 Nov 2022 22:50:17 +0000 Subject: [PATCH 4/4] use newer internal links --- docs/locks.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/locks.md b/docs/locks.md index bdb76ab5c4..43ad29659b 100644 --- a/docs/locks.md +++ b/docs/locks.md @@ -1,6 +1,6 @@ # Locks -## Locks to prevent duplicate installations running at the same time +## Locks to prevent duplicate installations running at the same time {: #locks } Easybuild creates a lock before starting the installation of an easyconfig file, to avoid a collision between multiple installations running at the same time. @@ -12,7 +12,7 @@ it will be automatically aborted with an error like "`Lock ... already exists, a Locking of installations was implemented in EasyBuild version 4.2.0 . -### Locking implementation details +### Locking implementation details {: #locks_implementation } Easybuild will create a lock when starting an installation if no corresponding lock exists yet, regardless of whether the installation was requested explicitly or is performed to resolve a dependency. @@ -20,7 +20,7 @@ regardless of whether the installation was requested explicitly or is performed The name of the lock corresponds to the *full* path of the installation directory, with slashes (`/`) and dashes (`-`) replaced by underscores (`_`), and with an additional `.lock` added at the end. -Locks are created in the [locks directory](#locks-directory). +Locks are created in the [locks directory][locks_dir]. The lock created by EasyBuild is an empty directory (rather than a file), because that can be created more atomically on modern filesystems. @@ -28,7 +28,7 @@ because that can be created more atomically on modern filesystems. For example, if `OpenFOAM-7-foss-2019b.eb` is being installed to `/apps/easybuild/software`, an empty directory that serves as a lock for this installation will be created at `/apps/easybuild/software/.locks/_apps_easybuild_software_OpenFOAM_7_foss_2019b.lock` -(assuming the default [locks directory](#locks-directory) is used). +(assuming the default [locks directory][locks_dir] is used). A lock is automatically removed by Easybuild when the installation ends, regardless of whether the installation was successful or not. Therefore, new installations of the same easyconfig will be aborted in case of: @@ -37,13 +37,13 @@ was successful or not. Therefore, new installations of the same easyconfig will * a previous installation of the same easyconfig was abruptly interrupted; -### Removing locks +### Removing locks {: #locks_removing } If a previous installation was abruptly interrupted and a lock was left in place, it can be easily removed using the `rmdir` command (since the lock is actually an empty directory). -### Configuration options related to installation locks +### Configuration options related to installation locks {: #locks_configuration_options } The behaviour of the locking mechanism in Easybuild can be tuned with the following configuration options: @@ -76,7 +76,7 @@ if a corresponding lock already exists, which is equivalent to setting `--wait-o implying that no waiting should be done at all. -### Locks directory +### Locks directory {: #locks_dir } If desired, an alternate location where locks should be created and checked for can be specified via the `--locks-dir` configuration option.