Add linear view into a storage (#571)
This commit is contained in:
Julien Cretin
GitHub
373
libraries/persistent_store/src/linear.rs
Normal file
373
libraries/persistent_store/src/linear.rs
Normal file
@@ -0,0 +1,373 @@
|
||||
// Copyright 2022 Google LLC
|
||||
//
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
//! Provides a linear view into a storage.
|
||||
|
||||
use core::ops::Range;
|
||||
|
||||
use alloc::borrow::Cow;
|
||||
use alloc::vec::Vec;
|
||||
|
||||
use crate::{Storage, StorageError, StorageIndex, StorageResult};
|
||||
|
||||
/// Provides a linear view into a storage.
|
||||
///
|
||||
/// The storage may be read and written as if it were a contiguous slice. This implementation is not
|
||||
/// power-loss resistant.
|
||||
pub struct Linear<S: Storage> {
|
||||
pub storage: S,
|
||||
}
|
||||
|
||||
impl<S: Storage> Linear<S> {
|
||||
/// Returns the length of the storage.
|
||||
///
|
||||
/// In particular, offsets should be less than this value (or equal for the one-past-the-end
|
||||
/// offset).
|
||||
pub fn length(&self) -> usize {
|
||||
self.storage.num_pages() * self.storage.page_size()
|
||||
}
|
||||
|
||||
/// Reads a slice from the storage (ignoring page boundaries).
|
||||
///
|
||||
/// This function may allocate if the slice spans multiple pages (because they may not be
|
||||
/// contiguous). However, a slice is returned if the range fits within a page.
|
||||
pub fn read(&self, range: Range<usize>) -> StorageResult<Cow<[u8]>> {
|
||||
if range.is_empty() {
|
||||
return Ok(Cow::Borrowed(&[]));
|
||||
}
|
||||
let Range { start, end } = range;
|
||||
if end < start {
|
||||
return Err(StorageError::OutOfBounds);
|
||||
}
|
||||
let page_size = self.storage.page_size();
|
||||
let mut index = StorageIndex {
|
||||
page: start / page_size,
|
||||
byte: start % page_size,
|
||||
};
|
||||
let mut length = end - start;
|
||||
if end <= (index.page + 1) * page_size {
|
||||
// The range fits in a page.
|
||||
return self.storage.read_slice(index, length);
|
||||
}
|
||||
// The range doesn't fit in a page.
|
||||
let mut result = Vec::with_capacity(length);
|
||||
while length > 0 {
|
||||
let slice_length = core::cmp::min(length, page_size - index.byte);
|
||||
result.extend_from_slice(&self.storage.read_slice(index, slice_length)?);
|
||||
index.page += 1;
|
||||
index.byte = 0;
|
||||
length -= slice_length;
|
||||
}
|
||||
Ok(Cow::Owned(result))
|
||||
}
|
||||
|
||||
/// Writes a slice to the storage (ignoring page boundaries and regardless of previous value).
|
||||
///
|
||||
/// This function will erase pages as needed (and restore the non-overwritten parts). As such it
|
||||
/// may allocate and is not power-loss resistant.
|
||||
pub fn write(&mut self, offset: usize, mut value: &[u8]) -> StorageResult<()> {
|
||||
if self.length() < value.len() || self.length() - value.len() < offset {
|
||||
return Err(StorageError::OutOfBounds);
|
||||
}
|
||||
let page_size = self.storage.page_size();
|
||||
let mut index = StorageIndex {
|
||||
page: offset / page_size,
|
||||
byte: offset % page_size,
|
||||
};
|
||||
while !value.is_empty() {
|
||||
let length = core::cmp::min(value.len(), page_size - index.byte);
|
||||
self.write_within(index, &value[..length])?;
|
||||
index.page += 1;
|
||||
index.byte = 0;
|
||||
value = &value[length..];
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Erases a slice from the storage (ignoring page boundaries and preserving previous value).
|
||||
///
|
||||
/// This is equivalent to writing a slice of `0xff` bytes but doesn't need the slice as
|
||||
/// argument. But the function still allocates to preserve previous values if needed and is thus
|
||||
/// still not power-loss resistant.
|
||||
pub fn erase(&mut self, mut range: Range<usize>) -> StorageResult<()> {
|
||||
if range.end < range.start || self.length() < range.end {
|
||||
return Err(StorageError::OutOfBounds);
|
||||
}
|
||||
let page_size = self.storage.page_size();
|
||||
let mut index = StorageIndex {
|
||||
page: range.start / page_size,
|
||||
byte: range.start % page_size,
|
||||
};
|
||||
while !range.is_empty() {
|
||||
let length = core::cmp::min(range.len(), page_size - index.byte);
|
||||
self.erase_within(index, length)?;
|
||||
index.page += 1;
|
||||
index.byte = 0;
|
||||
range.start += length;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Writes a slice fitting a page (regardless of previous value).
|
||||
///
|
||||
/// This function will erase the page if needed and restore the non-overwritten part. This is
|
||||
/// not power-loss resistant.
|
||||
fn write_within(&mut self, index: StorageIndex, value: &[u8]) -> StorageResult<()> {
|
||||
self.erase_within(index, value.len())?;
|
||||
self.write_unaligned(index, value)
|
||||
}
|
||||
|
||||
/// Writes a slice fitting a page (assuming erased but not necessarily word-aligned).
|
||||
fn write_unaligned(&mut self, mut index: StorageIndex, mut value: &[u8]) -> StorageResult<()> {
|
||||
let word_size = self.storage.word_size();
|
||||
// Align the beginning if needed.
|
||||
let unaligned = index.byte % word_size;
|
||||
if unaligned != 0 {
|
||||
let len = core::cmp::min(value.len(), word_size - unaligned);
|
||||
index.byte -= unaligned;
|
||||
let mut word = self.storage.read_slice(index, word_size)?.into_owned();
|
||||
word[unaligned..unaligned + len].copy_from_slice(&value[..len]);
|
||||
self.storage.write_slice(index, &word)?;
|
||||
value = &value[len..];
|
||||
index.byte += word_size;
|
||||
}
|
||||
// Write as long as aligned.
|
||||
let len = value.len() - (value.len() % word_size);
|
||||
self.storage.write_slice(index, &value[..len])?;
|
||||
value = &value[len..];
|
||||
index.byte += len;
|
||||
// Write the unaligned end if needed.
|
||||
if value.len() > 0 {
|
||||
let mut word = self.storage.read_slice(index, word_size)?.into_owned();
|
||||
word[..value.len()].copy_from_slice(value);
|
||||
self.storage.write_slice(index, &word)?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Erases a slice fitting a page (regardless of previous value).
|
||||
///
|
||||
/// This function will erase the page if needed and restore the non-overwritten part. This is
|
||||
/// not power-loss resistant.
|
||||
fn erase_within(&mut self, index: StorageIndex, length: usize) -> StorageResult<()> {
|
||||
let previous_value = self.storage.read_slice(index, length)?;
|
||||
if previous_value.iter().all(|&x| x == 0xff) {
|
||||
// The slice is already erased, so nothing to do.
|
||||
return Ok(());
|
||||
}
|
||||
// We must erase the page, so we save the rest.
|
||||
let complement = self.save_complement(index, length)?;
|
||||
self.storage.erase_page(index.page)?;
|
||||
self.restore_complement(index.page, complement)
|
||||
}
|
||||
|
||||
/// Saves the complement of a slice fitting a page.
|
||||
fn save_complement(&self, index: StorageIndex, length: usize) -> StorageResult<Complement> {
|
||||
let page_size = self.storage.page_size();
|
||||
let prefix = self
|
||||
.storage
|
||||
.read_slice(
|
||||
StorageIndex {
|
||||
page: index.page,
|
||||
byte: 0,
|
||||
},
|
||||
index.byte,
|
||||
)?
|
||||
.into_owned();
|
||||
let suffix = self
|
||||
.storage
|
||||
.read_slice(
|
||||
StorageIndex {
|
||||
page: index.page,
|
||||
byte: index.byte + length,
|
||||
},
|
||||
page_size - index.byte - length,
|
||||
)?
|
||||
.into_owned();
|
||||
Ok(Complement { prefix, suffix })
|
||||
}
|
||||
|
||||
/// Restores the complement of a slice fitting a page.
|
||||
fn restore_complement(&mut self, page: usize, complement: Complement) -> StorageResult<()> {
|
||||
let page_size = self.storage.page_size();
|
||||
let Complement { prefix, suffix } = complement;
|
||||
self.write_unaligned(StorageIndex { page, byte: 0 }, &prefix)?;
|
||||
self.write_unaligned(
|
||||
StorageIndex {
|
||||
page,
|
||||
byte: page_size - suffix.len(),
|
||||
},
|
||||
&suffix,
|
||||
)?;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
/// Represents the complement of a slice within a page.
|
||||
struct Complement {
|
||||
prefix: Vec<u8>,
|
||||
suffix: Vec<u8>,
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::test::MINIMAL;
|
||||
use crate::{BufferOptions, BufferStorage};
|
||||
|
||||
/// Creates a linear view into a fresh minimal buffer storage.
|
||||
fn new_linear() -> Linear<BufferStorage> {
|
||||
let mut options = BufferOptions::from(&MINIMAL);
|
||||
options.strict_mode = false;
|
||||
let storage = vec![0xff; MINIMAL.num_pages * MINIMAL.page_size].into_boxed_slice();
|
||||
let storage = BufferStorage::new(storage, options);
|
||||
Linear { storage }
|
||||
}
|
||||
|
||||
/// Returns some interesting test ranges.
|
||||
fn ranges(linear: &Linear<BufferStorage>) -> Vec<Range<usize>> {
|
||||
let storage_length = linear.length();
|
||||
let page_size = linear.storage.page_size();
|
||||
let count = 2 * linear.storage.word_size();
|
||||
let mut ranges = Vec::new();
|
||||
let convert = |page: usize, byte: usize, rev| {
|
||||
if rev {
|
||||
(page + 1) * page_size - byte
|
||||
} else {
|
||||
page * page_size + byte
|
||||
}
|
||||
};
|
||||
for &start_rev in [false, true].iter() {
|
||||
for &length_rev in [false, true].iter() {
|
||||
for start_page in 0..=2 {
|
||||
for length_page in 0..2 {
|
||||
for start_byte in 0..count {
|
||||
for length_byte in 0..count {
|
||||
let start = convert(start_page, start_byte, start_rev);
|
||||
let length = convert(length_page, length_byte, length_rev);
|
||||
ranges.push(start..start + length);
|
||||
let end = storage_length - start;
|
||||
let start = end - length;
|
||||
ranges.push(start..end);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
ranges
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn simple_usage() {
|
||||
let mut linear = new_linear();
|
||||
linear.write(3, b"hello").unwrap();
|
||||
assert_eq!(
|
||||
linear.read(0..10).unwrap(),
|
||||
&b"\xff\xff\xffhello\xff\xff"[..]
|
||||
);
|
||||
linear.write(5, b"y you").unwrap();
|
||||
assert_eq!(linear.read(0..10).unwrap(), &b"\xff\xff\xffhey you"[..]);
|
||||
linear.erase(6..10).unwrap();
|
||||
assert_eq!(
|
||||
linear.read(0..10).unwrap(),
|
||||
&b"\xff\xff\xffhey\xff\xff\xff\xff"[..]
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn round_trip() {
|
||||
let mut linear = new_linear();
|
||||
let pattern: Vec<u8> = (0..255).collect();
|
||||
for range in ranges(&linear) {
|
||||
// Check that writing and reading back gives the same value.
|
||||
let value = &pattern[..range.len()];
|
||||
assert_eq!(linear.write(range.start, value), Ok(()), "{:?}", range);
|
||||
match linear.read(range.clone()) {
|
||||
Ok(actual) => assert_eq!(actual, value, "{:?}", range),
|
||||
Err(error) => panic!("{:?} {:?}", error, range),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn out_of_bound() {
|
||||
let mut linear = new_linear();
|
||||
let length = linear.length();
|
||||
assert!(linear.read(length..length + 1).is_err());
|
||||
assert!(linear.read(length + 1..length + 5).is_err());
|
||||
assert!(linear.read(0..length + 1).is_err());
|
||||
assert!(linear.read(length - 10..length + 1).is_err());
|
||||
assert!(linear.write(length, &[0]).is_err());
|
||||
assert!(linear.write(length - 10, &[0; 11]).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn erase_before() {
|
||||
let mut linear = new_linear();
|
||||
let pattern: Vec<u8> = (0..255).collect();
|
||||
for mut range in ranges(&linear) {
|
||||
if range.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let value = &pattern[..range.len()];
|
||||
// We write the pattern.
|
||||
assert_eq!(linear.write(range.start, value), Ok(()), "{:?}", range);
|
||||
// We erase the pattern except for the last byte.
|
||||
range.end -= 1;
|
||||
assert_eq!(linear.erase(range.clone()), Ok(()), "{:?}", range);
|
||||
// We check that the pattern was erased except for the last byte.
|
||||
match linear.read(range.clone()) {
|
||||
Ok(actual) => assert_eq!(actual, vec![0xff; range.len()], "{:?}", range),
|
||||
Err(error) => panic!("{:?} {:?}", error, range),
|
||||
}
|
||||
// We check that the last byte is still there.
|
||||
range.start = range.end;
|
||||
range.end += 1;
|
||||
match linear.read(range.clone()) {
|
||||
Ok(actual) => assert_eq!(actual, &value[value.len() - 1..], "{:?}", range),
|
||||
Err(error) => panic!("{:?} {:?}", error, range),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn erase_after() {
|
||||
let mut linear = new_linear();
|
||||
let pattern: Vec<u8> = (0..255).collect();
|
||||
for mut range in ranges(&linear) {
|
||||
if range.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let value = &pattern[..range.len()];
|
||||
// We write the pattern.
|
||||
assert_eq!(linear.write(range.start, value), Ok(()), "{:?}", range);
|
||||
// We erase the pattern except for the first byte.
|
||||
range.start += 1;
|
||||
assert_eq!(linear.erase(range.clone()), Ok(()), "{:?}", range);
|
||||
// We check that the pattern was erased except for the first byte.
|
||||
match linear.read(range.clone()) {
|
||||
Ok(actual) => assert_eq!(actual, vec![0xff; range.len()], "{:?}", range),
|
||||
Err(error) => panic!("{:?} {:?}", error, range),
|
||||
}
|
||||
// We check that the first byte is still there.
|
||||
range.end = range.start;
|
||||
range.start -= 1;
|
||||
match linear.read(range.clone()) {
|
||||
Ok(actual) => assert_eq!(actual, &value[..1], "{:?}", range),
|
||||
Err(error) => panic!("{:?} {:?}", error, range),
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user