Struct vmap::Options [−][src]
Options and flags which can be used to configure how a map is allocated.
This builder exposes the ability to configure how a Map
or a MapMut
is allocated. These options can be used to either map a file or allocate
an anonymous memory region. For file-based operations, a std::fs::OpenOptions
value is maintained to match the desired abilities between the mapping and
the underlying resource. This allows the creation, truncation, and resizing
of a file to be coordinated when allocating a named map. For both mapping
and anonymous allocations the option can also specify an offset and a
mapping length.
The T
must either be a Map
or a MapMut
. Generally, this will be
created by Map::with_options()
or MapMut::with_options()
, then
chain calls to methods to set each option, then call either .open()
,
.map()
, or .alloc()
. This will return a Result
with the correct
Map
or MapMut
inside. Additionally, there are .open_if()
and
.map_if()
variations which instead return a Result
containing an
Option<T>
. These return Ok(None)
if the attempted range lies outside
of the file rather than an Err
.
Without specifying a size, the options defaults to either the full size of
the file when using .open()
or .map()
. When using .alloc()
, the default
size will be a single unit of allocation granularity.
Implementations
impl<T: FromPtr> Options<T>
[src]
pub fn new() -> Self
[src]
Creates a new Options
value with a default state.
Generally, Map::with_options()
or MapMut::with_options()
is the
preferred way to create options.
pub fn write(&mut self) -> &mut Self
[src]
Sets the option for write access.
This is applied automatically when using MapMut::with_options()
.
This can be useful with Map
when there is a future intent to call
Map::into_map_mut()
.
Examples
use vmap::Map; let (map, file) = Map::with_options().open("README.md")?; assert!(map.into_map_mut().is_err()); let (map, file) = Map::with_options().write().open("README.md")?; assert!(map.into_map_mut().is_ok());
pub fn copy(&mut self) -> &mut Self
[src]
Sets the option for copy-on-write access.
This efficiently implements a copy to an underlying modifiable resource. The allocated memory can be shared between multiple unmodified instances, and the copy operation is deferred until the first write. When used for an anonymous allocation, the deffered copy can be used in a child process.
Examples
use vmap::MapMut; let (mut map1, file) = MapMut::with_options().copy().open("README.md")?; let (mut map2, _) = MapMut::with_options().copy().open("README.md")?; let first = map1[0]; map1[0] = b'X'; assert_eq!(first, map2[0]);
pub fn create(&mut self, create: bool) -> &mut Self
[src]
Sets the option to create a new file, or open it if it already exists.
This only applies when using .open()
or .open_if()
. In order for the
file to be created, .write()
access must be used.
Examples
use vmap::{Map, MapMut}; use std::path::PathBuf; let path: PathBuf = /* path to file */ let (mut map, file) = MapMut::with_options().create(true).resize(100).open(&path)?; assert_eq!(100, map.len()); assert_eq!(b"\0\0\0\0", &map[..4]); map[..4].clone_from_slice(b"test"); let (map, file) = Map::with_options().open(&path)?; assert_eq!(100, map.len()); assert_eq!(b"test", &map[..4]);
pub fn create_new(&mut self, create_new: bool) -> &mut Self
[src]
Sets the option to create a new file, failing if it already exists.
This option is useful because it is atomic. Otherwise between checking whether a file exists and creating a new one, the file may have been created by another process (a TOCTOU race condition / attack).
If .create_new(true)
is set, .create()
and .truncate()
are
ignored.
This only applies when using .open()
or .open_if()
. In order for the
file to be created, .write()
access must be used.
Examples
use vmap::MapMut; use std::path::PathBuf; let path: PathBuf = /* path to file */ let (map, file) = MapMut::with_options().create_new(true).resize(10).open(&path)?; assert_eq!(10, map.len()); assert!(MapMut::with_options().create_new(true).open(&path).is_err());
pub fn truncate(&mut self, truncate: bool) -> &mut Self
[src]
Sets the option for truncating a previous file.
If a file is successfully opened with this option set it will truncate
the file to 0 length if it already exists. Given that the file will now
be empty, a .resize()
should be used.
In order for the file to be truncated, .write()
access must be used.
Examples
use vmap::MapMut; use std::path::PathBuf; let path: PathBuf = /* path to file */ { let (mut map, file) = MapMut::with_options() .create(true) .truncate(true) .resize(4) .open(&path)?; assert_eq!(b"\0\0\0\0", &map[..]); map[..4].clone_from_slice(b"test"); assert_eq!(b"test", &map[..]); } let (mut map, file) = MapMut::with_options().truncate(true).resize(4).open(&path)?; assert_eq!(b"\0\0\0\0", &map[..]);
pub fn offset(&mut self, offset: usize) -> &mut Self
[src]
Sets the byte offset into the mapping.
For file-based mappings, the offset defines the starting byte range from the beginning of the resource. This must be within the range of the file.
Examples
use vmap::Map; use std::path::PathBuf; use std::str::from_utf8; use std::fs; let path: PathBuf = /* path to file */ fs::write(&path, b"this is a test")?; let (map, file) = Map::with_options().offset(10).open(path)?; assert_eq!(Ok("test"), from_utf8(&map[..]));
pub fn len<E: Into<Extent>>(&mut self, value: E) -> &mut Self
[src]
Sets the byte length extent of the mapping.
For file-based mappings, this length must be available in the
underlying resource, including any .offset()
. When not specified,
the default length is implied to be Extent::End
.
Length with Extent::End
With this value, the length extent is set to the end of the underlying
resource. This is the default if no .len()
is applied, but this can
be set to override a prior setting if desired.
For anonymous mappings, it is generally preferred to use a different extent strategy. Without setting any other extent, the default length is a single allocation unit of granularity.
Length with Extent::Exact
Using an exact extent option will instruct the map to cover an exact byte length. That is, it will not consider the length of the underlying resource, if any. For file-based mappings, this length must be available in the file. For anonymous mappings, this is the minimum size that will be allocated, however, the resulting map will be sized exactly to this size.
A usize
may be used as an Extent::Exact
through the usize
implementation of Into<Extent>
.
use vmap::{Map, MapMut}; use std::path::PathBuf; use std::str::from_utf8; use std::fs; let path: PathBuf = /* path to file */ fs::write(&path, b"this is a test")?; let (map, file) = Map::with_options() .len(4) // or .len(Extent::Exaxt(4)) .open(&path)?; assert_eq!(Ok("this"), from_utf8(&map[..])); let mut anon = MapMut::with_options() .len(4) .alloc()?; assert_eq!(4, anon.len());
Length with Extent::Min
The minimum extent strategy creates a mapping that is at least the desired byte length, but may be larger. When applied to a file-based mapping, this ensures that the resulting memory region covers a minimum extent, but otherwise covers to the end of the file. For an anonymous map, this ensures the allocated region meets the minimum size required, but allows accessing the remaining allocated space that would otherwise be unusable.
use vmap::{Extent, Map, MapMut, Size}; use std::path::PathBuf; use std::str::from_utf8; use std::fs; let path: PathBuf = /* path to file */ fs::write(&path, b"this is a test")?; let (map, file) = Map::with_options() .offset(5) .len(Extent::Min(4)) .open(&path)?; assert_eq!(9, map.len()); assert_eq!(Ok("is a test"), from_utf8(&map[..])); assert!( Map::with_options() .len(Extent::Min(100)) .open_if(&path)? .0 .is_none() ); let mut anon = MapMut::with_options() .len(Extent::Min(2000)) .alloc()?; assert_eq!(Size::alloc().size(1), anon.len());
Length with Extent::Max
The maximum extent strategy creates a mapping that is no larger than the desired byte length, but may be smaller. When applied to a file- based mapping, this will ensure that the resulting
use vmap::{Extent, Map, MapMut}; use std::path::PathBuf; use std::str::from_utf8; use std::fs; let path: PathBuf = /* path to file */ fs::write(&path, b"this is a test")?; let (map, file) = Map::with_options() .offset(5) .len(Extent::Max(100)) .open(&path)?; assert_eq!(9, map.len()); assert_eq!(Ok("is a test"), from_utf8(&map[..])); let mut anon = MapMut::with_options() .len(Extent::Max(2000)) .alloc()?; assert_eq!(2000, anon.len());
pub fn resize<E: Into<Extent>>(&mut self, value: E) -> &mut Self
[src]
Sets the option to resize the file prior to mapping.
When mapping to a file using .open()
, .open_if()
, .map()
,
or .map_if()
this options conditionally adjusts the length of the
underlying resource to the desired size by calling .set_len()
on
the File
.
In order for the file to be resized, .write()
access must be used.
This has no affect on anonymous mappings.
Resize with Extent::End
This implies resizing to the current size of the file. In other words, no resize is performed, and this is the default strategy.
Resize with Extent::Exact
Using an exact extent option will instruct the map to cover an exact byte length. That is, it will not consider the length of the underlying resource, if any. For file-based mappings, this length must be available in the file. For anonymous mappings, this is the minimum size that will be allocated, however, the resulting map will be sized exactly to this size.
A usize
may be used as an Extent::Exact
through the usize
implementation of Into<Extent>
.
use vmap::Map; use std::path::PathBuf; use std::str::from_utf8; use std::fs; let path: PathBuf = /* path to file */ fs::write(&path, b"this is a test")?; let (map, file) = Map::with_options() .write() .resize(7) // or .resize(Extent::Exact(7)) .open(&path)?; assert_eq!(7, map.len()); assert_eq!(Ok("this is"), from_utf8(&map[..]));
Resize with Extent::Min
The minimum extent strategy resizes the file to be at least the desired byte length, but may be larger. If the file is already equal to or larger than the extent, no resize is performed.
use vmap::{Extent, Map}; use std::path::PathBuf; use std::str::from_utf8; use std::fs; let path: PathBuf = /* path to file */ fs::write(&path, b"this")?; { let (map, file) = Map::with_options() .write() .resize(Extent::Min(7)) .open(&path)?; assert_eq!(7, map.len()); assert_eq!(Ok("this\0\0\0"), from_utf8(&map[..])); } fs::write(&path, b"this is a test")?; let (map, file) = Map::with_options() .write() .resize(Extent::Min(7)) .open(&path)?; assert_eq!(14, map.len()); assert_eq!(Ok("this is a test"), from_utf8(&map[..]));
Resize with Extent::Max
The maximum extent strategy resizes the file to be no larger than the desired byte length, but may be smaller. If the file is already equal to or smaller than the extent, no resize is performed.
use vmap::{Extent, Map}; use std::path::PathBuf; use std::str::from_utf8; use std::fs; let path: PathBuf = /* path to file */ fs::write(&path, b"this")?; { let (map, file) = Map::with_options() .write() .resize(Extent::Max(7)) .open(&path)?; assert_eq!(4, map.len()); assert_eq!(Ok("this"), from_utf8(&map[..])); } fs::write(&path, b"this is a test")?; let (map, file) = Map::with_options() .write() .resize(Extent::Max(7)) .open(&path)?; assert_eq!(7, map.len()); assert_eq!(Ok("this is"), from_utf8(&map[..]));
pub fn open<P: AsRef<Path>>(&self, path: P) -> Result<(T, File)>
[src]
Opens and maps a file using the current options specified by self
.
Unlike .open_if()
, when the requested offset or length lies outside of
the underlying file, an error is returned.
The returned File
can be discarded if no longer needed to .flush()
or .map()
other regions. This does not need to be kept open in order to
use the mapped value.
Examples
use vmap::Map; use std::path::PathBuf; use std::fs; let path: PathBuf = /* path to file */ fs::write(&path, b"this is a test")?; assert!(Map::with_options().len(4).open(&path).is_ok()); assert!(Map::with_options().len(25).open(&path).is_err());
pub fn open_if<P: AsRef<Path>>(&self, path: P) -> Result<(Option<T>, File)>
[src]
Opens and maps a file with the options specified by self
if the
provided byte range is valid.
Unlike .open()
, when the requested offset or length lies outside of
the underlying file, Ok(None)
will be returned rather than an error.
The returned File
can be discarded if no longer needed to .flush()
or .map()
other regions. This does not need to be kept open in order to
use the mapped value.
Examples
use vmap::Map; use std::path::PathBuf; use std::fs; let path: PathBuf = /* path to file */ fs::write(&path, b"this is a test")?; assert!(Map::with_options().len(4).open_if(&path).is_ok()); let result = Map::with_options().len(25).open_if(&path); assert!(result.is_ok()); assert!(result.unwrap().0.is_none());
pub fn map(&self, f: &File) -> Result<T>
[src]
Maps an open File
using the current options specified by self
.
Unlike .map_if()
, when the requested offset or length lies outside of
the underlying file, an error is returned.
Examples
use vmap::Map; use std::path::PathBuf; use std::fs::OpenOptions; let path: PathBuf = /* path to file */ let f = OpenOptions::new() .read(true) .write(true) .create(true) .open(path)?; f.set_len(8)?; assert!(Map::with_options().len(4).map(&f).is_ok()); assert!(Map::with_options().len(25).map(&f).is_err());
pub fn map_if(&self, f: &File) -> Result<Option<T>>
[src]
Maps an open File
with the options specified by self
if the provided
byte range is valid.
Unlike .map()
, when the requested offset or length lies outside of
the underlying file, Ok(None)
will be returned rather than an error.
Examples
use vmap::Map; use std::path::PathBuf; use std::fs::OpenOptions; let path: PathBuf = /* path to file */ let f = OpenOptions::new() .read(true) .write(true) .create(true) .open(path)?; f.set_len(8)?; assert!(Map::with_options().len(4).map_if(&f).is_ok()); let result = Map::with_options().len(25).map_if(&f); assert!(result.is_ok()); assert!(result.unwrap().is_none());
pub fn alloc(&self) -> Result<T>
[src]
Creates an anonymous allocation using the options specified by self
.
Examples
use vmap::{Extent, MapMut}; let map = MapMut::with_options().len(Extent::Min(500)).alloc()?; assert!(map.len() >= 500);
Trait Implementations
Auto Trait Implementations
impl<T> RefUnwindSafe for Options<T> where
T: RefUnwindSafe,
[src]
T: RefUnwindSafe,
impl<T> Send for Options<T> where
T: Send,
[src]
T: Send,
impl<T> Sync for Options<T> where
T: Sync,
[src]
T: Sync,
impl<T> Unpin for Options<T> where
T: Unpin,
[src]
T: Unpin,
impl<T> UnwindSafe for Options<T> where
T: UnwindSafe,
[src]
T: UnwindSafe,
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,