mappedpages 0.1.0

A fixed-size page provider backed by memory mapping, intended for building higher-level allocators and storage systems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! [`PageAllocator`] trait and its [`PageHandle`] bound.

use crate::error::MappedPageError;
use crate::page::{MappedPage, PageId};
use crate::pager::Pager;
use crate::protected::{ProtectedPageId, ProtectedPageWriter};

/// A handle to an allocated page that can borrow its contents from the
/// allocator that produced it.
///
/// The `Mut` associated type allows each handle to name its own mutable
/// accessor: [`PageId`] returns `&mut MappedPage` directly, while
/// [`ProtectedPageId`] returns a [`ProtectedPageWriter`] that must be
/// committed to make the write crash-consistent.
///
/// The `Error` associated type is the error returned by [`get`](Self::get)
/// and [`get_mut`](Self::get_mut), allowing implementations to use error
/// types other than [`MappedPageError`].
pub trait PageHandle<A: ?Sized> {
    /// The error type returned by [`get`](Self::get) and [`get_mut`](Self::get_mut).
    type Error;

    /// The type returned by [`get_mut`](Self::get_mut).
    type Mut<'a>: 'a
    where
        A: 'a,
        Self: 'a;

    /// Immutably borrow the page contents from `allocator`.
    fn get<'a>(&self, allocator: &'a A) -> Result<&'a MappedPage, Self::Error>;

    /// Mutably access the page contents through `allocator`.
    fn get_mut<'a>(&self, allocator: &'a mut A) -> Result<Self::Mut<'a>, Self::Error>;
}

/// Allocates and frees pages of type `AllocatedType`.
///
/// `AllocatedType` must implement [`PageHandle<Self>`] so that callers can
/// borrow page data back through the same allocator.
///
/// The `Error` associated type is the error returned by [`alloc`](Self::alloc)
/// and [`free`](Self::free), allowing implementations to use error types other
/// than [`MappedPageError`].
pub trait PageAllocator<AllocatedType: PageHandle<Self>>: Sized {
    /// The error type returned by [`alloc`](Self::alloc) and [`free`](Self::free).
    type Error;

    /// Allocate a fresh page, returning a handle to it.
    fn alloc(&mut self) -> Result<AllocatedType, Self::Error>;

    /// Free a previously allocated page.
    fn free(&mut self, id: AllocatedType) -> Result<(), Self::Error>;
}

// ── PageId ────────────────────────────────────────────────────────────────────

impl PageHandle<Pager> for PageId {
    type Error = MappedPageError;
    type Mut<'a> = &'a mut MappedPage;

    fn get<'a>(&self, pager: &'a Pager) -> Result<&'a MappedPage, MappedPageError> {
        pager.get_page(*self)
    }

    fn get_mut<'a>(&self, pager: &'a mut Pager) -> Result<&'a mut MappedPage, MappedPageError> {
        pager.get_page_mut(*self)
    }
}

impl PageAllocator<PageId> for Pager {
    type Error = MappedPageError;

    fn alloc(&mut self) -> Result<PageId, MappedPageError> {
        Pager::alloc(self)
    }

    fn free(&mut self, id: PageId) -> Result<(), MappedPageError> {
        Pager::free(self, id)
    }
}

// ── ProtectedPageId ───────────────────────────────────────────────────────────

impl PageHandle<Pager> for ProtectedPageId {
    type Error = MappedPageError;
    /// A [`ProtectedPageWriter`] that must be [`commit`](ProtectedPageWriter::commit)ted
    /// to make the write crash-consistent.
    type Mut<'a> = ProtectedPageWriter<'a>;

    fn get<'a>(&self, pager: &'a Pager) -> Result<&'a MappedPage, MappedPageError> {
        pager.get_protected_page(*self)
    }

    fn get_mut<'a>(
        &self,
        pager: &'a mut Pager,
    ) -> Result<ProtectedPageWriter<'a>, MappedPageError> {
        pager.get_protected_page_mut(*self)
    }
}

impl PageAllocator<ProtectedPageId> for Pager {
    type Error = MappedPageError;

    fn alloc(&mut self) -> Result<ProtectedPageId, MappedPageError> {
        Pager::alloc_protected(self)
    }

    fn free(&mut self, id: ProtectedPageId) -> Result<(), MappedPageError> {
        Pager::free_protected(self, id)
    }
}