History

mm: document and polish read-ahead code

Add some "big-picture" documentation for read-ahead and polish the code to make it fit this documentation. The meaning of ->async_size is clarified to match its name. i.e. Any request to ->readahead() has a sync part and an async part. The caller will wait for the sync pages to complete, but will not wait for the async pages. The first async page is still marked PG_readahead Note that the current function names page_cache_sync_ra() and page_cache_async_ra() are misleading. All ra request are partly sync and partly async, so either part can be empty. A page_cache_sync_ra() request will usually set ->async_size non-zero, implying it is not all synchronous. When a non-zero req_count is passed to page_cache_async_ra(), the implication is that some prefix of the request is synchronous, though the calculation made there is incorrect - I haven't tried to fix it.

NeilBrown committed 4 years ago

Commit 84dacdb1 parent bf507034 files · +133 −10Browse files

Unified · Split

4 files
  1. Documentation/core-api/mm-api.rst +17 −2
  2. Documentation/filesystems/vfs.rst +10 −6
  3. include/linux/fs.h +7 −2
  4. mm/readahead.c +99 −0
Documentation/core-api/mm-api.rst+17−2
@@ -58,15 +58,30 @@ Virtually Contiguous Mappings · 57 unmodified lines
58File Mapping and Page Cache58File Mapping and Page Cache
59===========================59===========================
60 60
61.. kernel-doc:: mm/readahead.c61Filemap
62 :export:62-------
63 63
64.. kernel-doc:: mm/filemap.c64.. kernel-doc:: mm/filemap.c
65 :export:65 :export:
66 66
67Readahead
68---------
69
70.. kernel-doc:: mm/readahead.c
71 :doc: Readahead Overview
72
73.. kernel-doc:: mm/readahead.c
74 :export:
75
76Writeback
77---------
78
67.. kernel-doc:: mm/page-writeback.c79.. kernel-doc:: mm/page-writeback.c
68 :export:80 :export:
69 81
82Truncate
83--------
84
70.. kernel-doc:: mm/truncate.c85.. kernel-doc:: mm/truncate.c
71 :export:86 :export:
72 87
Documentation/filesystems/vfs.rst+10−6
@@ -806,12 +806,16 @@ cache in your filesystem. The following members are defined: · 805 unmodified lines
806 object. The pages are consecutive in the page cache and are806 object. The pages are consecutive in the page cache and are
807 locked. The implementation should decrement the page refcount807 locked. The implementation should decrement the page refcount
808 after starting I/O on each page. Usually the page will be808 after starting I/O on each page. Usually the page will be
809 unlocked by the I/O completion handler. If the filesystem decides809 unlocked by the I/O completion handler. The set of pages are
810 to stop attempting I/O before reaching the end of the readahead810 divided into some sync pages followed by some async pages,
811 window, it can simply return. The caller will decrement the page811 rac->ra->async_size gives the number of async pages. The
812 refcount and unlock the remaining pages for you. Set PageUptodate812 filesystem should attempt to read all sync pages but may decide
813 if the I/O completes successfully. Setting PageError on any page813 to stop once it reaches the async pages. If it does decide to
814 will be ignored; simply unlock the page if an I/O error occurs.814 stop attempting I/O, it can simply return. The caller will
815 remove the remaining pages from the address space, unlock them
816 and decrement the page refcount. Set PageUptodate if the I/O
817 completes successfully. Setting PageError on any page will be
818 ignored; simply unlock the page if an I/O error occurs.
815 819
816``readpages``820``readpages``
817 called by the VM to read pages associated with the address_space821 called by the VM to read pages associated with the address_space
include/linux/fs.h+7−2
@@ -930,10 +930,15 @@ struct fown_struct { · 929 unmodified lines
930 * struct file_ra_state - Track a file's readahead state.930 * struct file_ra_state - Track a file's readahead state.
931 * @start: Where the most recent readahead started.931 * @start: Where the most recent readahead started.
932 * @size: Number of pages read in the most recent readahead.932 * @size: Number of pages read in the most recent readahead.
933 * @async_size: Start next readahead when this many pages are left.933 * @async_size: Numer of pages that were/are not needed immediately
934 * @ra_pages: Maximum size of a readahead request.934 * and so were/are genuinely "ahead". Start next readahead when
935 * the first of these pages is accessed.
936 * @ra_pages: Maximum size of a readahead request, copied from the bdi.
935 * @mmap_miss: How many mmap accesses missed in the page cache.937 * @mmap_miss: How many mmap accesses missed in the page cache.
936 * @prev_pos: The last byte in the most recent read request.938 * @prev_pos: The last byte in the most recent read request.
939 *
940 * When this structure is passed to ->readahead(), the "most recent"
941 * readahead means the current readahead.
937 */942 */
938struct file_ra_state {943struct file_ra_state {
939 pgoff_t start;944 pgoff_t start;
mm/readahead.c+99−0
@@ -8,6 +8,105 @@ · 7 unmodified lines
8 * Initial version.8 * Initial version.
9 */9 */
10 10
11/**
12 * DOC: Readahead Overview
13 *
14 * Readahead is used to read content into the page cache before it is
15 * explicitly requested by the application. Readahead only ever
16 * attempts to read pages that are not yet in the page cache. If a
17 * page is present but not up-to-date, readahead will not try to read
18 * it. In that case a simple ->readpage() will be requested.
19 *
20 * Readahead is triggered when an application read request (whether a
21 * systemcall or a page fault) finds that the requested page is not in
22 * the page cache, or that it is in the page cache and has the
23 * %PG_readahead flag set. This flag indicates that the page was loaded
24 * as part of a previous read-ahead request and now that it has been
25 * accessed, it is time for the next read-ahead.
26 *
27 * Each readahead request is partly synchronous read, and partly async
28 * read-ahead. This is reflected in the struct file_ra_state which
29 * contains ->size being to total number of pages, and ->async_size
30 * which is the number of pages in the async section. The first page in
31 * this async section will have %PG_readahead set as a trigger for a
32 * subsequent read ahead. Once a series of sequential reads has been
33 * established, there should be no need for a synchronous component and
34 * all read ahead request will be fully asynchronous.
35 *
36 * When either of the triggers causes a readahead, three numbers need to
37 * be determined: the start of the region, the size of the region, and
38 * the size of the async tail.
39 *
40 * The start of the region is simply the first page address at or after
41 * the accessed address, which is not currently populated in the page
42 * cache. This is found with a simple search in the page cache.
43 *
44 * The size of the async tail is determined by subtracting the size that
45 * was explicitly requested from the determined request size, unless
46 * this would be less than zero - then zero is used. NOTE THIS
47 * CALCULATION IS WRONG WHEN THE START OF THE REGION IS NOT THE ACCESSED
48 * PAGE.
49 *
50 * The size of the region is normally determined from the size of the
51 * previous readahead which loaded the preceding pages. This may be
52 * discovered from the struct file_ra_state for simple sequential reads,
53 * or from examining the state of the page cache when multiple
54 * sequential reads are interleaved. Specifically: where the readahead
55 * was triggered by the %PG_readahead flag, the size of the previous
56 * readahead is assumed to be the number of pages from the triggering
57 * page to the start of the new readahead. In these cases, the size of
58 * the previous readahead is scaled, often doubled, for the new
59 * readahead, though see get_next_ra_size() for details.
60 *
61 * If the size of the previous read cannot be determined, the number of
62 * preceding pages in the page cache is used to estimate the size of
63 * a previous read. This estimate could easily be misled by random
64 * reads being coincidentally adjacent, so it is ignored unless it is
65 * larger than the current request, and it is not scaled up, unless it
66 * is at the start of file.
67 *
68 * In general read ahead is accelerated at the start of the file, as
69 * reads from there are often sequential. There are other minor
70 * adjustments to the read ahead size in various special cases and these
71 * are best discovered by reading the code.
72 *
73 * The above calculation determines the readahead, to which any requested
74 * read size may be added.
75 *
76 * Readahead requests are sent to the filesystem using the ->readahead()
77 * address space operation, for which mpage_readahead() is a canonical
78 * implementation. ->readahead() should normally initiate reads on all
79 * pages, but may fail to read any or all pages without causing an IO
80 * error. The page cache reading code will issue a ->readpage() request
81 * for any page which ->readahead() does not provided, and only an error
82 * from this will be final.
83 *
84 * ->readahead() will generally call readahead_page() repeatedly to get
85 * each page from those prepared for read ahead. It may fail to read a
86 * page by:
87 *
88 * * not calling readahead_page() sufficiently many times, effectively
89 * ignoring some pages, as might be appropriate if the path to
90 * storage is congested.
91 *
92 * * failing to actually submit a read request for a given page,
93 * possibly due to insufficient resources, or
94 *
95 * * getting an error during subsequent processing of a request.
96 *
97 * In the last two cases, the page should be unlocked to indicate that
98 * the read attempt has failed. In the first case the page will be
99 * unlocked by the caller.
100 *
101 * Those pages not in the final ``async_size`` of the request should be
102 * considered to be important and ->readahead() should not fail them due
103 * to congestion or temporary resource unavailability, but should wait
104 * for necessary resources (e.g. memory or indexing information) to
105 * become available. Pages in the final ``async_size`` may be
106 * considered less urgent and failure to read them is more acceptable.
107 * They will eventually be read individually using ->readpage().
108 */
109
11#include <linux/kernel.h>110#include <linux/kernel.h>
12#include <linux/dax.h>111#include <linux/dax.h>
13#include <linux/gfp.h>112#include <linux/gfp.h>

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t