2022-11-01 17:35:14

by Chuck Lever III

Subject: [PATCH] NFSD: Flesh out a documenting comment for filecache.c

Record what we've learned recently about the NFSD filecache in a
documenting comment so our future selves don't forget what all this
is for.

Signed-off-by: Chuck Lever <[email protected]>
---
fs/nfsd/filecache.c | 24 ++++++++++++++++++++++++
1 file changed, 24 insertions(+)

Here's what I had in mind for the top-of-file comment.


diff --git a/fs/nfsd/filecache.c b/fs/nfsd/filecache.c
index 28f91c97e045..02b4871b9ffc 100644
--- a/fs/nfsd/filecache.c
+++ b/fs/nfsd/filecache.c
@@ -2,6 +2,30 @@
* Open file cache.
*
* (c) 2015 - Jeff Layton <[email protected]>
+ *
+ * An nfsd_file object is a per-file collection of open state that binds
+ * together:
+ * - a struct file *
+ * - a user credential
+ * - a network namespace
+ * - a read-ahead context
+ * - monitoring for writeback errors
+ *
+ * nfsd_file objects are reference-counted. Consumers acquire a new
+ * object via the nfsd_file_acquire API. They manage their interest in
+ * the acquired object, and hence the object's reference count, via
+ * nfsd_file_get and nfsd_file_put. There are two varieties of nfsd_file
+ * object:
+ *
+ * * non-garbage-collected: When a consumer wants to precisely control
+ * the lifetime of a file's open state, it acquires a non-garbage-
+ * collected nfsd_file. The final nfsd_file_put releases the open
+ * state immediately.
+ *
+ * * garbage-collected: When a consumer does not control the lifetime
+ * of open state, it acquires a garbage-collected nfsd_file. The
+ * final nfsd_file_put allows the open state to linger for a period
+ * during which it may be re-used.
*/

#include <linux/hash.h>

2022-11-01 18:25:39

by Jeff Layton

Subject: Re: [PATCH] NFSD: Flesh out a documenting comment for filecache.c

On Tue, 2022-11-01 at 13:30 -0400, Chuck Lever wrote:
> Record what we've learned recently about the NFSD filecache in a
> documenting comment so our future selves don't forget what all this
> is for.
>
> Signed-off-by: Chuck Lever <[email protected]>
> ---
> fs/nfsd/filecache.c | 24 ++++++++++++++++++++++++
> 1 file changed, 24 insertions(+)
>
> Here's what I had in mind for the top-of-file comment.
>
>
> diff --git a/fs/nfsd/filecache.c b/fs/nfsd/filecache.c
> index 28f91c97e045..02b4871b9ffc 100644
> --- a/fs/nfsd/filecache.c
> +++ b/fs/nfsd/filecache.c
> @@ -2,6 +2,30 @@
> * Open file cache.
> *
> * (c) 2015 - Jeff Layton <[email protected]>
> + *
> + * An nfsd_file object is a per-file collection of open state that binds
> + * together:
> + * - a struct file *
> + * - a user credential
> + * - a network namespace
> + * - a read-ahead context
> + * - monitoring for writeback errors
> + *
> + * nfsd_file objects are reference-counted. Consumers acquire a new
> + * object via the nfsd_file_acquire API. They manage their interest in
> + * the acquired object, and hence the object's reference count, via
> + * nfsd_file_get and nfsd_file_put. There are two varieties of nfsd_file
> + * object:
> + *
> + * * non-garbage-collected: When a consumer wants to precisely control
> + * the lifetime of a file's open state, it acquires a non-garbage-
> + * collected nfsd_file. The final nfsd_file_put releases the open
> + * state immediately.
> + *
> + * * garbage-collected: When a consumer does not control the lifetime
> + * of open state, it acquires a garbage-collected nfsd_file. The
> + * final nfsd_file_put allows the open state to linger for a period
> + * during which it may be re-used.
> */
>
> #include <linux/hash.h>
>
>

Seems reasonable.

Reviewed-by: Jeff Layton <[email protected]>