diff --git a/src/memory/mmap.rs b/src/memory/mmap.rs index 6691988..7dd4822 100644 --- a/src/memory/mmap.rs +++ b/src/memory/mmap.rs @@ -1,48 +1,105 @@ //! An implementation of a `ByteBuf` based on virtual memory. //! //! This implementation uses `mmap` on POSIX systems (and should use `VirtualAlloc` on windows). +//! There are possibilities to improve the performance for the reallocating case by reserving +//! memory up to maximum. This might be a problem for systems that don't have a lot of virtual +//! memory. use std::ptr::{self, NonNull}; use std::slice; struct Mmap { + /// The pointer that points to the start of the mapping. + /// + /// This value doesn't change after creation. ptr: NonNull, + /// The length of this mapping. + /// + /// Cannot be more than `isize::max_value()`. This value doesn't change after creation. len: usize, } impl Mmap { fn new(len: usize) -> Self { + assert!(len < isize::max_value() as usize); assert!(len > 0); - unsafe { - let ptr = libc::mmap( + let ptr_or_err = unsafe { + // Safety Proof: + // There are not specific safety proofs are required for this call, since the call + // by itself can't invoke any safety problems (however, misusing its result can). + libc::mmap( + // `addr` - let the system to choose the address at which to create the mapping. ptr::null_mut(), + // the length of the mapping in bytes. len, + // `prot` - protection flags: READ WRITE !EXECUTE libc::PROT_READ | libc::PROT_WRITE, - libc::MAP_PRIVATE | libc::MAP_ANON, + // `flags` + // `MAP_ANON` - mapping is not backed by any file and initial contents are + // initialized to zero. + // `MAP_PRIVATE` - the mapping is private to this process. + libc::MAP_ANON | libc::MAP_PRIVATE, + // `fildes` - a file descriptor. Pass -1 as this is required for some platforms + // when the `MAP_ANON` is passed. -1, + // `offset` - offset from the file. 0, - );; - assert!(ptr as isize != -1); - Self { - ptr: NonNull::new(ptr as *mut u8).unwrap(), - len, + ) + }; + + match ptr_or_err as usize { + // `mmap` shouldn't return 0 since it has a special meaning. + x if x == 0 || x as isize == -1 => panic!(), + _ => { + let ptr = unsafe { + // Safety Proof: + // the ptr cannot be null as checked within the enclosing match. + NonNull::new_unchecked(ptr_or_err as *mut u8) + }; + Self { ptr, len } } } } - pub fn as_slice(&self) -> &[u8] { - unsafe { slice::from_raw_parts(self.ptr.as_ptr(), self.len) } + fn as_slice(&self) -> &[u8] { + unsafe { + // Safety Proof: + // - Aliasing guarantees of `self.ptr` are not violated since `self` is the only owner. + // - This pointer was allocated for `self.len` bytes and thus is a valid slice. + // - `self.len` doesn't change throughout the lifetime of `self`. + // - The value is returned valid for the duration of lifetime of `self`. + // `self` cannot be destroyed while the returned slice is alive. + // - `self.ptr` is of `NonNull` type and thus `.as_ptr()` can never return NULL. + // - `self.len` cannot be larger than `isize::max_value()`. + slice::from_raw_parts(self.ptr.as_ptr(), self.len) + } } - pub fn as_slice_mut(&mut self) -> &mut [u8] { - unsafe { slice::from_raw_parts_mut(self.ptr.as_ptr(), self.len) } + fn as_slice_mut(&mut self) -> &mut [u8] { + unsafe { + // Safety Proof: + // - See the proof for `Self::as_slice` + // - Additionally, it is not possible to obtain two mutable references for `self.ptr` + slice::from_raw_parts_mut(self.ptr.as_ptr(), self.len) + } } } impl Drop for Mmap { fn drop(&mut self) { - let r = unsafe { libc::munmap(self.ptr.as_ptr() as *mut libc::c_void, self.len) }; - assert_eq!(r, 0, "munmap failed"); + let ret_val = unsafe { + // Safety proof: + // - `self.ptr` was allocated by a call to `mmap`. + // - `self.len` was saved at the same time and it doesn't change throughout the lifetime + // of `self`. + libc::munmap(self.ptr.as_ptr() as *mut libc::c_void, self.len) + }; + + // There is no reason for `munmap` to fail to deallocate a private annonymous mapping + // allocated by `mmap`. + // However, for the cases when it actually fails prefer to fail, in order to not leak + // and exhaust the virtual memory. + assert_eq!(ret_val, 0, "munmap failed"); } } @@ -53,7 +110,6 @@ pub struct ByteBuf { impl ByteBuf { pub fn new(len: usize) -> Self { let mmap = if len == 0 { None } else { Some(Mmap::new(len)) }; - Self { mmap } } @@ -66,11 +122,10 @@ impl ByteBuf { } else { let mut new_mmap = Mmap::new(new_len); - unsafe { + { let src = self.mmap.as_ref().unwrap().as_slice(); let dst = new_mmap.as_slice_mut(); - - ptr::copy_nonoverlapping(src.as_ptr(), dst.as_mut_ptr(), src.len()); + dst[..src.len()].copy_from_slice(src); } Some(new_mmap)