class PagedView

PagedView is an adapter for a set of PMM memory pages that provides typed "views" into these

pages. The view does not own the lifetime of these pages, so it should not be used once the pages

have been deallocated.

Internally, it operates page-at-a-time, so it is safe to deallocate and unlink pages

above or below the current page (as returned by the current_page() method).

There are three different interfaces, which can be mixed as needed:

// Assume for the examples below:

assert(ZX_OK == pmm_alloc_pages(num_pages,

&page

_list));

struct MyNode { int foo; };

fbl::PagedView

<MyNode

> paged_view(page_list);

1. Record-at-a-time: Good for building data when the producer drives the loop.

The pattern is:

for ( /* producer loop */ ) {

paged_view.record().foo = x;

if (!paged_view.next_record()) {

// Reached the end of the allocated pages. This is either a logical error (not enough

// pages were allocated) or is by design, and we need to "consume" the data and

// somehow resume the producer loop.

}

}

2. Page-at-a-time: Good for consuming the data in the pages. The pattern is:

do {

for (auto

&

node : paged_view.span()) {

consume_data(.., node.foo, ..);

}

} while(paged_view.next_page());

Note that span() returns all the memory of that page. If a particular page

has not been fully initialized, you should use the marker mode below.

3. Marker mode: Allows saving a cursor and returning to it. Applicable to either of

the above forms but easier to see in the second case:

// Assume we allocated exactly the number of pages needed.

for ( /* producer loop */ ) {

paged_view.record().foo = x;

assert(paged_view.next_record());

}

// The producer is done. Now we need to consume however many nodes have been added;

// however, the last page might not be full. We can handle that by getting a marker

// and resetting the internal cursor.

auto marker = paged_view.reset();

do {

for (auto

&

node : paged_view.span(marker)) {

consume_data(.., node.foo, ..);

}

if (paged_view.marker_in_page(marker)) break;

} while(paged_view.next_page());

// Note the use of span(marker) rather than just span(), so that for the last

// page, the correct number of records are returned.

Marker Direction

The markers come in two flavors, referred to below as "direction of travel". The reset() method

returns a "from-start" marker that can be used to iterate from the first record to the last

record that was current at the reset() callsite. This is what the last example above shows.

Also, you can use get_marker_to_end() to obtain a "to-end" marker, which can be used to iterate

from the currently active record to the last record.

The correct use of both these markers is guaranteed by using the for_each_page() method, or its

source can be inspected to roll your own version.