Received-SPF: pass (google.com: domain of linux-nfs-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <3d3925de588eae4da34e53f7cd6648258801d692.camel@kernel.org>
Subject: Re: [PATCH] NFSD: Flesh out a documenting comment for filecache.c
From:   Jeff Layton <jlayton@kernel.org>
To:     Chuck Lever <chuck.lever@oracle.com>, linux-nfs@vger.kernel.org
Date:   Tue, 01 Nov 2022 14:21:53 -0400
In-Reply-To: <166732362009.147807.16481897041798638515.stgit@klimt.1015granger.net>
References: <166732362009.147807.16481897041798638515.stgit@klimt.1015granger.net>
Content-Type: text/plain; charset="ISO-8859-15"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.44.4 (3.44.4-2.fc36) 
MIME-Version: 1.0
Precedence: bulk

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.
>=20
> Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
> ---
>  fs/nfsd/filecache.c |   24 ++++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
>=20
> Here's what I had in mind for the top-of-file comment.
>=20
>=20
> 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 <jeff.layton@primarydata.com>
> + *
> + * 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.
>   */
> =20
>  #include <linux/hash.h>
>=20
>=20

Seems reasonable.

Reviewed-by: Jeff Layton <jlayton@kernel.org>