| Message ID | 166732362009.147807.16481897041798638515.stgit@klimt.1015granger.net (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | NFSD: Flesh out a documenting comment for filecache.c | expand |
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 <chuck.lever@oracle.com> > --- > 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 <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. > */ > > #include <linux/hash.h> > > Seems reasonable. Reviewed-by: Jeff Layton <jlayton@kernel.org>
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. */ #include <linux/hash.h>
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 <chuck.lever@oracle.com> --- fs/nfsd/filecache.c | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) Here's what I had in mind for the top-of-file comment.