On Mon 17-02-20 17:12:10, Mauro Carvalho Chehab wrote:
> - Add a SPDX header;
> - Add a document title;
> - Adjust document title;
> - Fix list markups;
> - Some whitespace fixes and new line breaks;
> - Add it to filesystems/index.rst.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
Thanks. You can add:
Acked-by: Jan Kara <jack@xxxxxxx>
or tell me if you want me to pick up this patch.
Honza
> ---
> Documentation/filesystems/index.rst | 1 +
> .../filesystems/{inotify.txt => inotify.rst} | 33 ++++++++++++-------
> 2 files changed, 23 insertions(+), 11 deletions(-)
> rename Documentation/filesystems/{inotify.txt => inotify.rst} (83%)
>
> diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> index 3fbe2fa0b5c5..5a737722652c 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -70,6 +70,7 @@ Documentation for filesystem implementations.
> hfs
> hfsplus
> hpfs
> + inotify
> fuse
> overlayfs
> virtiofs
> diff --git a/Documentation/filesystems/inotify.txt b/Documentation/filesystems/inotify.rst
> similarity index 83%
> rename from Documentation/filesystems/inotify.txt
> rename to Documentation/filesystems/inotify.rst
> index 51f61db787fb..7f7ef8af0e1e 100644
> --- a/Documentation/filesystems/inotify.txt
> +++ b/Documentation/filesystems/inotify.rst
> @@ -1,27 +1,36 @@
> - inotify
> - a powerful yet simple file change notification system
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===============================================================
> +Inotify - A Powerful yet Simple File Change Notification System
> +===============================================================
>
>
>
> Document started 15 Mar 2005 by Robert Love <rml@xxxxxxxxxx>
> +
> Document updated 4 Jan 2015 by Zhang Zhen <zhenzhang.zhang@xxxxxxxxxx>
> - --Deleted obsoleted interface, just refer to manpages for user interface.
> +
> + - Deleted obsoleted interface, just refer to manpages for user interface.
>
> (i) Rationale
>
> -Q: What is the design decision behind not tying the watch to the open fd of
> +Q:
> + What is the design decision behind not tying the watch to the open fd of
> the watched object?
>
> -A: Watches are associated with an open inotify device, not an open file.
> +A:
> + Watches are associated with an open inotify device, not an open file.
> This solves the primary problem with dnotify: keeping the file open pins
> the file and thus, worse, pins the mount. Dnotify is therefore infeasible
> for use on a desktop system with removable media as the media cannot be
> unmounted. Watching a file should not require that it be open.
>
> -Q: What is the design decision behind using an-fd-per-instance as opposed to
> +Q:
> + What is the design decision behind using an-fd-per-instance as opposed to
> an fd-per-watch?
>
> -A: An fd-per-watch quickly consumes more file descriptors than are allowed,
> +A:
> + An fd-per-watch quickly consumes more file descriptors than are allowed,
> more fd's than are feasible to manage, and more fd's than are optimally
> select()-able. Yes, root can bump the per-process fd limit and yes, users
> can use epoll, but requiring both is a silly and extraneous requirement.
> @@ -29,8 +38,8 @@ A: An fd-per-watch quickly consumes more file descriptors than are allowed,
> spaces is thus sensible. The current design is what user-space developers
> want: Users initialize inotify, once, and add n watches, requiring but one
> fd and no twiddling with fd limits. Initializing an inotify instance two
> - thousand times is silly. If we can implement user-space's preferences
> - cleanly--and we can, the idr layer makes stuff like this trivial--then we
> + thousand times is silly. If we can implement user-space's preferences
> + cleanly--and we can, the idr layer makes stuff like this trivial--then we
> should.
>
> There are other good arguments. With a single fd, there is a single
> @@ -65,9 +74,11 @@ A: An fd-per-watch quickly consumes more file descriptors than are allowed,
> need not be a one-fd-per-process mapping; it is one-fd-per-queue and a
> process can easily want more than one queue.
>
> -Q: Why the system call approach?
> +Q:
> + Why the system call approach?
>
> -A: The poor user-space interface is the second biggest problem with dnotify.
> +A:
> + The poor user-space interface is the second biggest problem with dnotify.
> Signals are a terrible, terrible interface for file notification. Or for
> anything, for that matter. The ideal solution, from all perspectives, is a
> file descriptor-based one that allows basic file I/O and poll/select.
> --
> 2.24.1
>
--
Jan Kara <jack@xxxxxxxx>
SUSE Labs, CR
