Reorganize classes so that it is easier to read. Before number 4 was
written in one lenghty paragraph. It is as long as number 6 and it is
basically same kind of class (rename()). Also old number 5 was list and
it is as short as 1, 2, 3 so it can be converted non list.
This makes file now much readible.
Signed-off-by: Kari Argillander <[email protected]>
---
.../filesystems/directory-locking.rst | 31 +++++++++----------
1 file changed, 15 insertions(+), 16 deletions(-)
diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst
index 504ba940c36c..33921dff7af4 100644
--- a/Documentation/filesystems/directory-locking.rst
+++ b/Documentation/filesystems/directory-locking.rst
@@ -11,7 +11,7 @@ When taking the i_rwsem on multiple non-directory objects, we
always acquire the locks in order by increasing address. We'll call
that "inode pointer" order in the following.
-For our purposes all operations fall in 5 classes:
+For our purposes all operations fall in 6 classes:
1) read access. Locking rules: caller locks directory we are accessing.
The lock is taken shared.
@@ -22,26 +22,25 @@ exclusive.
3) object removal. Locking rules: caller locks parent, finds victim,
locks victim and calls the method. Locks are exclusive.
-4) rename() that is _not_ cross-directory. Locking rules: caller locks
-the parent and finds source and target. In case of exchange (with
-RENAME_EXCHANGE in flags argument) lock both. In any case,
-if the target already exists, lock it. If the source is a non-directory,
-lock it. If we need to lock both, lock them in inode pointer order.
-Then call the method. All locks are exclusive.
-NB: we might get away with locking the source (and target in exchange
-case) shared.
+4) link creation. Locking rules: lock parent, check that source is not
+a directory, lock source and call the method. Locks are exclusive.
-5) link creation. Locking rules:
+5) rename() that is _not_ cross-directory.
+Locking rules:
- * lock parent
- * check that source is not a directory
- * lock source
- * call the method.
+ * Caller locks the parent and finds source and target.
+ * In case of exchange (with RENAME_EXCHANGE in flags argument)
+ lock both the source and the target.
+ * If the target exists, lock it, If the source is a non-directory,
+ lock it. If we need to lock both, do so in inode pointer order.
+ * Call the method.
All locks are exclusive.
+NB: we might get away with locking the source (and target in exchange
+case) shared.
-6) cross-directory rename. The trickiest in the whole bunch. Locking
-rules:
+6) rename() that _is_ cross-directory. The trickiest in the whole bunch.
+Locking rules:
* lock the filesystem
* lock parents in "ancestors first" order.
--
2.30.2
On Tue, Aug 17, 2021 at 01:26:39AM +0300, Kari Argillander wrote:
> Reorganize classes so that it is easier to read. Before number 4 was
> written in one lenghty paragraph. It is as long as number 6 and it is
> basically same kind of class (rename()). Also old number 5 was list and
> it is as short as 1, 2, 3 so it can be converted non list.
>
> This makes file now much readible.
Gently ping for this one.
>
> Signed-off-by: Kari Argillander <[email protected]>
> ---
> .../filesystems/directory-locking.rst | 31 +++++++++----------
> 1 file changed, 15 insertions(+), 16 deletions(-)
>
> diff --git a/Documentation/filesystems/directory-locking.rst b/Documentation/filesystems/directory-locking.rst
> index 504ba940c36c..33921dff7af4 100644
> --- a/Documentation/filesystems/directory-locking.rst
> +++ b/Documentation/filesystems/directory-locking.rst
> @@ -11,7 +11,7 @@ When taking the i_rwsem on multiple non-directory objects, we
> always acquire the locks in order by increasing address. We'll call
> that "inode pointer" order in the following.
>
> -For our purposes all operations fall in 5 classes:
> +For our purposes all operations fall in 6 classes:
>
> 1) read access. Locking rules: caller locks directory we are accessing.
> The lock is taken shared.
> @@ -22,26 +22,25 @@ exclusive.
> 3) object removal. Locking rules: caller locks parent, finds victim,
> locks victim and calls the method. Locks are exclusive.
>
> -4) rename() that is _not_ cross-directory. Locking rules: caller locks
> -the parent and finds source and target. In case of exchange (with
> -RENAME_EXCHANGE in flags argument) lock both. In any case,
> -if the target already exists, lock it. If the source is a non-directory,
> -lock it. If we need to lock both, lock them in inode pointer order.
> -Then call the method. All locks are exclusive.
> -NB: we might get away with locking the source (and target in exchange
> -case) shared.
> +4) link creation. Locking rules: lock parent, check that source is not
> +a directory, lock source and call the method. Locks are exclusive.
>
> -5) link creation. Locking rules:
> +5) rename() that is _not_ cross-directory.
> +Locking rules:
>
> - * lock parent
> - * check that source is not a directory
> - * lock source
> - * call the method.
> + * Caller locks the parent and finds source and target.
> + * In case of exchange (with RENAME_EXCHANGE in flags argument)
> + lock both the source and the target.
> + * If the target exists, lock it, If the source is a non-directory,
> + lock it. If we need to lock both, do so in inode pointer order.
> + * Call the method.
>
> All locks are exclusive.
> +NB: we might get away with locking the source (and target in exchange
> +case) shared.
>
> -6) cross-directory rename. The trickiest in the whole bunch. Locking
> -rules:
> +6) rename() that _is_ cross-directory. The trickiest in the whole bunch.
> +Locking rules:
>
> * lock the filesystem
> * lock parents in "ancestors first" order.
> --
> 2.30.2
>