.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "MPAGE_READPAGES" "9" "09 October 2005" "" ""

.SH NAME
mpage_readpages \- populate an address space with some pages, and
.SH SYNOPSIS
"SYNOPSIS"
.sp
\fB
.sp
int mpage_readpages  (struct address_space * \fImapping\fB, struct list_head * \fIpages\fB, unsigned \fInr_pages\fB, get_block_t \fIget_block\fB);
\fR
.SH "ARGUMENTS"
.TP
\fB\fImapping\fB\fR
the address_space
.TP
\fB\fIpages\fB\fR
The address of a list_head which contains the target pages.  These
pages have their ->index populated and are otherwise uninitialised.
.TP
\fB\fInr_pages\fB\fR
The number of pages at *\fIpages\fR
.TP
\fB\fIget_block\fB\fR
The filesystem's block mapper function.
.SH "DESCRIPTION"
.PP
This function walks the pages and the blocks within each page, building and
emitting large BIOs.
.PP
If anything unusual happens, such as:
.PP
- encountering a page which has buffers
- encountering a page which has a non-hole after a hole
- encountering a page with non-contiguous blocks
.PP
then this code just gives up and calls the buffer_head-based read function.
It does handle a page which has holes at the end - that is a common case:
the end-of-file on blocksize < PAGE_CACHE_SIZE setups.
.SH "DESCRIPTION"
.PP
This function walks the pages and the blocks within each page, building and
emitting large BIOs.
.PP
If anything unusual happens, such as:
.PP
- encountering a page which has buffers
- encountering a page which has a non-hole after a hole
- encountering a page with non-contiguous blocks
.PP
then this code just gives up and calls the buffer_head-based read function.
It does handle a page which has holes at the end - that is a common case:
the end-of-file on blocksize < PAGE_CACHE_SIZE setups.
.SH "DESCRIPTION"
.PP
This function walks the pages and the blocks within each page, building and
emitting large BIOs.
.PP
If anything unusual happens, such as:
.PP
- encountering a page which has buffers
- encountering a page which has a non-hole after a hole
- encountering a page with non-contiguous blocks
.PP
then this code just gives up and calls the buffer_head-based read function.
It does handle a page which has holes at the end - that is a common case:
the end-of-file on blocksize < PAGE_CACHE_SIZE setups.
.SH "BH_BOUNDARY EXPLANATION"
.PP
.PP
There is a problem.  The mpage read code assembles several pages, gets all
their disk mappings, and then submits them all.  That's fine, but obtaining
the disk mappings may require I/O.  Reads of indirect blocks, for example.
.PP
So an mpage read of the first 16 blocks of an ext2 file will cause I/O to be
.SH "SUBMITTED IN THE FOLLOWING ORDER"
.PP
12 0 1 2 3 4 5 6 7 8 9 10 11 13 14 15 16
because the indirect block has to be read to get the mappings of blocks
13,14,15,16.  Obviously, this impacts performance.
.PP
So what we do it to allow the filesystem's \fBget_block\fR function to set
BH_Boundary when it maps block 11.  BH_Boundary says: mapping of the block
after this one will require I/O against a block which is probably close to
this one.  So you should push what I/O you have currently accumulated.
.PP
This all causes the disk requests to be issued in the correct order.