Documentation/filesystems/netfs_library.rst

1 .. SPDX-License-Identifier: GPL-2.0
9  - Overview.
10  - Per-inode context.
11    - Inode context helper functions.
12  - Buffered read helpers.
13    - Read helper functions.
14    - Read helper structures.
15    - Read helper operations.
16    - Read helper procedure.
17    - Read helper cache API.
33 Per-Inode Context
76 ------------------------------
78 To help deal with the per-inode context, a number helper functions are
98 The library provides a set of read helpers that handle the ->read_folio(),
99 ->readahead() and much of the ->write_begin() VM operations and translate them
116  * Handle local caching, allowing cached data and server-read data to be
133 ---------------------
149 state in the per-inode context.
151 For ->readahead() and ->read_folio(), the network filesystem just point directly
152 at the corresponding read helper; whereas for ->write_begin(), it may be a
161 If an error occurs, the ->free_request() will be called to clean up the
174 the operation was asynchronous (ie. whether the follow-on processing can be
175 done in the current context, given this may involve sleeping).
179 ----------------------
203    may or may not point to inode->i_data.
218    may be altered by the ->expand_readahead() op.
290 ----------------------
327    Expansion is communicated by changing ->start and ->len in the request
328    structure.  Note that if any change is made, ->len must be increased by at
329    least as much as ->start is reduced.
343    reading.  In the subrequest, ->start, ->len and ->transferred indicate what
349    uptodate, unlocking them or dropping their refs - the helpers need to deal
382 ---------------------
442 ---------------------
500 With a termination handler function pointer::
528    downloaded from the server or read from the cache - or whether slicing
529    should be given up at the current point.
533    [Required] Called to configure the next slice of a request.  ->start and
534    ->len in the subrequest indicate where and how big the next slice can be;
544    Also provided is a pointer to a termination handler function and private
545    data to pass to that function.  The termination function should be called
547    indicating whether the termination is definitely happening in the caller's
558    caller is certain that no data has been written to that region - for example
566    Also provided is a pointer to a termination handler function and private
567    data to pass to that function.  The termination function should be called
569    indicating whether the termination is definitely happening in the caller's
581    It returns 0 if some data was found, -ENODATA if there was no usable data
582    within the region or -ENOBUFS if there is no caching on this file.
593 .. kernel-doc:: include/linux/netfs.h
594 .. kernel-doc:: fs/netfs/buffered_read.c