@@ -7,41 +7,65 @@ use core::ops::Range;
77#[ cfg( feature = "std" ) ]
88use std:: { fs:: File , sync:: Arc } ;
99
10- /// A simple struct consisting of a page-aligned pointer to page-aligned
11- /// and initially-zeroed memory and a length.
12- #[ derive( Debug ) ]
13- pub struct Mmap {
14- sys : mmap:: Mmap ,
10+ /// A marker type for an [`Mmap`] where both the start address and length are a
11+ /// multiple of the host page size.
12+ ///
13+ /// For more information, see the documentation on [`Mmap`].
14+ #[ derive( Clone , Debug ) ]
15+ pub struct AlignedLength { }
16+
17+ /// A type of [`Mmap`] where the start address is host page-aligned, but the
18+ /// length is possibly not a multiple of the host page size.
19+ ///
20+ /// For more information, see the documentation on [`Mmap`].
21+ #[ derive( Clone , Debug ) ]
22+ pub struct UnalignedLength {
1523 #[ cfg( feature = "std" ) ]
1624 file : Option < Arc < File > > ,
1725}
1826
19- impl Mmap {
27+ /// A platform-independent abstraction over memory-mapped data.
28+ ///
29+ /// The type parameter can be one of:
30+ ///
31+ /// * [`AlignedLength`]: Both the start address and length are page-aligned
32+ /// (i.e. a multiple of the host page size). This is always the result of an
33+ /// mmap backed by anonymous memory.
34+ ///
35+ /// * [`UnalignedLength`]: The start address is host page-aligned, but the
36+ /// length is not necessarily page-aligned. This is usually backed by a file,
37+ /// but can also be backed by anonymous memory.
38+ ///
39+ /// ## Notes
40+ ///
41+ /// If the length of a file is not a multiple of the host page size, [POSIX does
42+ /// not specify any semantics][posix-mmap] for the rest of the last page. Linux
43+ /// [does say][linux-mmap] that the rest of the page is reserved and zeroed out,
44+ /// but for portability it's best to not assume anything about the rest of
45+ /// memory. `UnalignedLength` achieves a type-level distinction between an mmap
46+ /// that is backed purely by memory, and one that is possibly backed by a file.
47+ ///
48+ /// Currently, the OS-specific `mmap` implementations in this crate do not make
49+ /// this this distinction -- alignment is managed at this platform-independent
50+ /// layer. It might make sense to add this distinction to the OS-specific
51+ /// implementations in the future.
52+ ///
53+ /// [posix-mmap]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/mmap.html
54+ /// [linux-mmap]: https://man7.org/linux/man-pages/man2/mmap.2.html#NOTES
55+ #[ derive( Debug ) ]
56+ pub struct Mmap < T > {
57+ sys : mmap:: Mmap ,
58+ data : T ,
59+ }
60+
61+ impl Mmap < AlignedLength > {
2062 /// Create a new `Mmap` pointing to at least `size` bytes of page-aligned
2163/// accessible memory.
2264pub fn with_at_least ( size : usize ) -> Result < Self > {
2365 let rounded_size = crate :: runtime:: vm:: round_usize_up_to_host_pages ( size) ?;
2466 Self :: accessible_reserved ( rounded_size, rounded_size)
2567 }
2668
27- /// Creates a new `Mmap` by opening the file located at `path` and mapping
28- /// it into memory.
29- ///
30- /// The memory is mapped in read-only mode for the entire file. If portions
31- /// of the file need to be modified then the `region` crate can be use to
32- /// alter permissions of each page.
33- ///
34- /// The memory mapping and the length of the file within the mapping are
35- /// returned.
36- #[ cfg( feature = "std" ) ]
37- pub fn from_file ( file : Arc < File > ) -> Result < Self > {
38- let sys = mmap:: Mmap :: from_file ( & file) ?;
39- Ok ( Mmap {
40- sys,
41- file : Some ( file) ,
42- } )
43- }
44-
4569 /// Create a new `Mmap` pointing to `accessible_size` bytes of page-aligned
4670/// accessible memory, within a reserved mapping of `mapping_size` bytes.
4771/// `accessible_size` and `mapping_size` must be native page-size multiples.
@@ -58,22 +82,19 @@ impl Mmap {
5882 if mapping_size == 0 {
5983 Ok ( Mmap {
6084 sys : mmap:: Mmap :: new_empty ( ) ,
61- #[ cfg( feature = "std" ) ]
62- file : None ,
85+ data : AlignedLength { } ,
6386 } )
6487 } else if accessible_size == mapping_size {
6588 Ok ( Mmap {
6689 sys : mmap:: Mmap :: new ( mapping_size)
6790 . context ( format ! ( "mmap failed to allocate {mapping_size:#x} bytes" ) ) ?,
68- #[ cfg( feature = "std" ) ]
69- file : None ,
91+ data : AlignedLength { } ,
7092 } )
7193 } else {
7294 let mut result = Mmap {
7395 sys : mmap:: Mmap :: reserve ( mapping_size)
7496 . context ( format ! ( "mmap failed to reserve {mapping_size:#x} bytes" ) ) ?,
75- #[ cfg( feature = "std" ) ]
76- file : None ,
97+ data : AlignedLength { } ,
7798 } ;
7899 if accessible_size > 0 {
79100 result. make_accessible ( 0 , accessible_size) . context ( format ! (
@@ -84,6 +105,20 @@ impl Mmap {
84105 }
85106 }
86107
108+ /// Converts this `Mmap` into a `Mmap<UnalignedLength>`.
109+ ///
110+ /// `UnalignedLength` really means "_possibly_ unaligned length", so it can
111+ /// be freely converted over at the cost of losing the alignment guarantee.
112+ pub fn into_unaligned ( self ) -> Mmap < UnalignedLength > {
113+ Mmap {
114+ sys : self . sys ,
115+ data : UnalignedLength {
116+ #[ cfg( feature = "std" ) ]
117+ file : None ,
118+ } ,
119+ }
120+ }
121+
87122 /// Make the memory starting at `start` and extending for `len` bytes
88123/// accessible. `start` and `len` must be native page-size multiples and
89124/// describe a range within `self`'s reserved memory.
@@ -101,7 +136,34 @@ impl Mmap {
101136
102137 self . sys . make_accessible ( start, len)
103138 }
139+ }
104140
141+ #[ cfg( feature = "std" ) ]
142+ impl Mmap < UnalignedLength > {
143+ /// Creates a new `Mmap` by opening the file located at `path` and mapping
144+ /// it into memory.
145+ ///
146+ /// The memory is mapped in read-only mode for the entire file. If portions
147+ /// of the file need to be modified then the `region` crate can be use to
148+ /// alter permissions of each page.
149+ ///
150+ /// The memory mapping and the length of the file within the mapping are
151+ /// returned.
152+ pub fn from_file ( file : Arc < File > ) -> Result < Self > {
153+ let sys = mmap:: Mmap :: from_file ( & file) ?;
154+ Ok ( Mmap {
155+ sys,
156+ data : UnalignedLength { file : Some ( file) } ,
157+ } )
158+ }
159+
160+ /// Returns the underlying file that this mmap is mapping, if present.
161+ pub fn original_file ( & self ) -> Option < & Arc < File > > {
162+ self . data . file . as_ref ( )
163+ }
164+ }
165+
166+ impl < T > Mmap < T > {
105167 /// Return the allocated memory as a slice of u8.
106168///
107169/// # Safety
@@ -198,15 +260,16 @@ impl Mmap {
198260 . make_readonly ( range)
199261 . context ( "failed to make memory readonly" )
200262 }
201-
202- /// Returns the underlying file that this mmap is mapping, if present.
203- #[ cfg( feature = "std" ) ]
204- pub fn original_file ( & self ) -> Option < & Arc < File > > {
205- self . file . as_ref ( )
206- }
207263}
208264
209265fn _assert ( ) {
210266 fn _assert_send_sync < T : Send + Sync > ( ) { }
211- _assert_send_sync :: < Mmap > ( ) ;
267+ _assert_send_sync :: < Mmap < AlignedLength > > ( ) ;
268+ _assert_send_sync :: < Mmap < UnalignedLength > > ( ) ;
269+ }
270+
271+ impl From < Mmap < AlignedLength > > for Mmap < UnalignedLength > {
272+ fn from ( mmap : Mmap < AlignedLength > ) -> Mmap < UnalignedLength > {
273+ mmap. into_unaligned ( )
274+ }
212275}
0 commit comments