valog

Trait Log

Source 
pub trait Log: Sealed {
    type Id;


Show 17 methods    // Required methods
    fn id(&self) -> &Self::Id;
    fn checksum(&self, bytes: &[u8]) -> u64;
    fn options(&self) -> &Options;

    // Provided methods
    fn magic_version(&self) -> u16 { ... }
    fn version(&self) -> u16 { ... }
    fn discarded(&self) -> u32 { ... }
    fn data_offset(&self) -> usize { ... }
    fn path(&self) -> Option<&<Self::Allocator as Allocator>::Path> { ... }
    fn in_memory(&self) -> bool { ... }
    fn on_disk(&self) -> bool { ... }
    fn is_map(&self) -> bool { ... }
    unsafe fn reserved_slice(&self) -> &[u8] ⓘ { ... }
    fn lock_exclusive(&self) -> Result<()> { ... }
    fn lock_shared(&self) -> Result<()> { ... }
    fn unlock(&self) -> Result<()> { ... }
    unsafe fn mlock(&self, offset: usize, len: usize) -> Result<()> { ... }
    unsafe fn munlock(&self, offset: usize, len: usize) -> Result<()> { ... }

}
Expand description

The abstraction for the common methods of log.

Required Associated Types§

Source

type Id

The identifier type (file ID) for the log.

Required Methods§

Source

fn id(&self) -> &Self::Id

Returns the identifier of the log.

§Example
use valog::{sync::ValueLog, Builder, Log};

let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

assert_eq!(log.id(), &1);
Source

fn checksum(&self, bytes: &[u8]) -> u64

Calculates the checksum of the given bytes.

§Example
use valog::{sync::ValueLog, Builder, Log, checksum::{Crc32, BuildChecksumer}};

let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

let bytes = b"Hello, valog!";
assert_eq!(log.checksum(bytes), Crc32::new().checksum_one(bytes));
Source

fn options(&self) -> &Options

Returns the options of the log.

§Example
use valog::{sync::ValueLog, Builder, Log};

let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

assert_eq!(log.options().capacity(), 100);

Provided Methods§

Source

fn magic_version(&self) -> u16

Returns the magic version of the log.

§Example
use valog::{sync::ValueLog, Builder, Log};

let log = Builder::new()
  .with_capacity(100)
  .with_magic_version(1)
  .alloc::<ValueLog>(1)
  .unwrap();

assert_eq!(log.magic_version(), 1);
Source

fn version(&self) -> u16

Returns the version of the log.

§Example
use valog::{sync::ValueLog, Builder, Log};

let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

assert_eq!(log.version(), 0);
Source

fn discarded(&self) -> u32

Returns the discarded bytes of the log.

§Example
use valog::{sync::ValueLog, Builder, Log, LogWriter};


let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

assert_eq!(log.discarded(), 0);

log.insert_tombstone(b"Hello, valog!").unwrap();
assert_eq!(log.discarded(), 13);
Source

fn data_offset(&self) -> usize

Returns the data offset of the log.

§Example
use valog::{sync::ValueLog, Builder, Log};

let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

assert_eq!(log.data_offset(), 9); // header size is 8, so data start at 9.

let log = Builder::new()
  .with_capacity(100)
  .with_reserved(8)
  .alloc::<ValueLog>(1)
  .unwrap();

assert_eq!(log.data_offset(), 17); // header size is 8, reserved is 8, so data start at 17.
Source

fn path(&self) -> Option<&<Self::Allocator as Allocator>::Path>

Available on crate feature memmap and non-target_family="wasm" only.

Returns the path of the log.

If the log is in memory, this method will return None.

§Example
use valog::{sync::ValueLog, Builder, Log};

let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

assert_eq!(log.path(), None);

let path = tempfile::NamedTempFile::new().unwrap().into_temp_path();
let log = unsafe {
  Builder::new()
    .with_capacity(100)
    .with_create(true)
    .with_write(true)
    .with_read(true)
    .map_mut::<ValueLog, _>(&path, 0)
    .unwrap()
};

assert_eq!(log.path().map(|p| p.as_path()), Some(path.as_ref()));
Source

fn in_memory(&self) -> bool

Returns true if the log is in memory.

§Example
use valog::{sync::ValueLog, Builder, Log};

let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

assert!(log.in_memory());

let path = tempfile::NamedTempFile::new().unwrap().into_temp_path();
let log = unsafe {
  Builder::new()
    .with_capacity(100)
    .with_create(true)
    .with_write(true)
    .with_read(true)
    .map_mut::<ValueLog, _>(&path, 0)
    .unwrap()
};
assert!(!log.in_memory());
Source

fn on_disk(&self) -> bool

Returns true if the log is on disk.

§Example
use valog::{sync::ValueLog, Builder, Log};

let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

assert!(!log.on_disk());

let path = tempfile::NamedTempFile::new().unwrap().into_temp_path();
let log = unsafe {
  Builder::new()
    .with_capacity(100)
    .with_create(true)
    .with_write(true)
    .with_read(true)
    .map_mut::<ValueLog, _>(&path, 0)
    .unwrap()
};
assert!(log.on_disk());
Source

fn is_map(&self) -> bool

Available on crate feature memmap and non-target_family="wasm" only.

Returns true if the log is using a memory map backend.

§Example
use valog::{sync::ValueLog, Builder, Log};

let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

assert!(!log.is_map());

let log = Builder::new()
  .with_capacity(100)
  .map_anon::<ValueLog>(0)
  .unwrap();

assert!(log.is_map());

let path = tempfile::NamedTempFile::new().unwrap().into_temp_path();
let log = unsafe {
  Builder::new()
    .with_capacity(100)
    .with_create(true)
    .with_write(true)
    .with_read(true)
    .map_mut::<ValueLog, _>(&path, 0)
    .unwrap()
};
assert!(log.is_map());
Source

unsafe fn reserved_slice(&self) -> &[u8] ⓘ

Returns the reserved space in the WAL.

§Safety
  • The writer must ensure that the returned slice is not modified.
  • This method is not thread-safe, so be careful when using it.
§Example
use valog::{sync::ValueLog, Builder, Log};

let log = Builder::new()
  .with_capacity(100)
  .alloc::<ValueLog>(1)
  .unwrap();

let reserved = unsafe { log.reserved_slice() };
assert!(reserved.is_empty());

let log = Builder::new()
  .with_capacity(100)
  .with_reserved(8)
  .alloc::<ValueLog>(1)
  .unwrap();

let reserved = unsafe { log.reserved_slice() };
assert_eq!(reserved.len(), 8);
Source

fn lock_exclusive(&self) -> Result<()>

Available on crate feature memmap and non-target_family="wasm" only.

Locks the underlying file for exclusive access, only works on mmap with a file backend.

§Example
use valog::{sync::ValueLog, Builder, Log};
/// Create a new file without automatic syncing.
let log = unsafe {
  Builder::new()
    .with_sync(false)
    .with_create(true)
    .with_read(true)
    .with_write(true)
    .with_capacity(100)
    .map_mut::<ValueLog, _>(&path, 0).unwrap()
};

log.lock_exclusive().unwrap();
Source

fn lock_shared(&self) -> Result<()>

Available on crate feature memmap and non-target_family="wasm" only.

Locks the underlying file for shared access, only works on mmap with a file backend.

§Example
use valog::{sync::ValueLog, Builder, Log};
/// Create a new file without automatic syncing.
let log = unsafe {
  Builder::new()
    .with_sync(false)
    .with_create(true)
    .with_read(true)
    .with_write(true)
    .with_capacity(100)
    .map_mut::<ValueLog, _>(&path, 0).unwrap()
};

log.lock_shared().unwrap();
Source

fn unlock(&self) -> Result<()>

Available on crate feature memmap and non-target_family="wasm" only.

Unlocks the underlying file, only works on mmap with a file backend.

§Example
use valog::{sync::ValueLog, Builder, Log};
/// Create a new file without automatic syncing.
let log = unsafe {
  Builder::new()
    .with_sync(false)
    .with_create(true)
    .with_read(true)
    .with_write(true)
    .with_capacity(100)
    .map_mut::<ValueLog, _>(&path, 0).unwrap()
};

log.lock_exclusive().unwrap();

log.unlock().unwrap();
Source

unsafe fn mlock(&self, offset: usize, len: usize) -> Result<()>

Available on crate feature memmap and non-target_family="wasm" only.

mlock(ptr, len)—Lock memory into RAM.

§Safety

This function operates on raw pointers, but it should only be used on memory which the caller owns. Technically, locking memory shouldn’t violate any invariants, but since unlocking it can violate invariants, this function is also unsafe for symmetry.

Some implementations implicitly round the memory region out to the nearest page boundaries, so this function may lock more memory than explicitly requested if the memory isn’t page-aligned. Other implementations fail if the memory isn’t page-aligned.

§References
Source

unsafe fn munlock(&self, offset: usize, len: usize) -> Result<()>

Available on crate feature memmap and non-target_family="wasm" only.

munlock(ptr, len)—Unlock memory.

§Safety

This function operates on raw pointers, but it should only be used on memory which the caller owns, to avoid compromising the mlock invariants of other unrelated code in the process.

Some implementations implicitly round the memory region out to the nearest page boundaries, so this function may unlock more memory than explicitly requested if the memory isn’t page-aligned.

§References

Implementors§

Source§

impl<I, A, C> Log for ImmutableValueLog<I, A, C>
where C: BuildChecksumer, A: Allocator,

Source§

type Id = I

Source§

impl<I, A, C> Log for ValueLog<I, A, C>
where A: Allocator, C: BuildChecksumer,

Source§

type Id = I

Source§

impl<L> Log for L
where L: AsLog, L::Log: Log,

Source§

type Id = <<L as AsLog>::Log as Log>::Id