Skip to main content

Directory

Struct Directory 

Source
pub struct Directory<P: Platform> { /* private fields */ }
Expand description

A directory of small objects, each replaced atomically.

Implementations§

Source§

impl<P: Platform> Directory<P>

Source

pub const DEFAULT_MAX_OBJECT: u64

The largest object a handle writes or reads by default (Self::with_max_object): 16 MiB.

Source

pub fn open( platform: P, path: &Path, create: bool, trust: Trust, ) -> Result<Self, Error>

Opens the directory at path, creating it (and syncing its parent) when create is true. trust is applied when the device is probed. It also tries a directory flush: if that fails, the handle still reads, but every replace, remove and sync is refused before any write, since no change could be made durable.

§Errors

NotFound if it does not exist and create is false; Io.

Source

pub fn with_max_object(self, max: u64) -> Self

The handle with max as its largest object, written or read (default Self::DEFAULT_MAX_OBJECT): a larger replace is refused before anything is written, and a file found larger is refused by read before anything is allocated (a damaged, replaced or sparse file of any length costs its reader nothing then).

Source

pub fn max_object(&self) -> u64

The largest object this handle writes or reads.

Source

pub fn class(&self) -> Option<DurabilityClass>

The durability class of the directory’s device, once a file has been opened through this handle.

Source

pub fn decision(&self) -> Option<&ClassDecision>

The class decision (evidence, reasons, label), once probed.

Source

pub fn replace(&self, name: &str, data: &[u8]) -> Result<(), Error>

Replaces the file name with data, atomically and durably: after any crash the file holds exactly the old or exactly the new bytes, and once this returns, exactly the new ones. One replace runs at a time in the directory: while another handle or process is replacing, this fails Locked with nothing written (the caller retries). Every writer must take the lock for that to hold: a process of a version before 0.5 does not. The lock is the file .sio-lock in the directory, created on first use and kept; delete it only while no Directory is open on the directory (an open handle keeps locking the file it opened, so a new one beside it splits the writers).

§Errors

Locked while another handle or process replaces in the directory; Io(Lock) if the file system cannot lock at all. NotWritten(InvalidName) for a name that could resolve to another file: longer than 247 bytes; shaped like a Windows short name (~ and digits) or a Windows device name; and, compared as a case-insensitive file system compares names (case folded, ignorable code points dropped), empty, ending in . or a space, or the directory’s own .sio-lock or a name ending in .sio-tmp. Unsupported(DirectoryFlush) or Io(SyncDir) when the directory cannot be flushed (found at open; nothing is written). NotWritten(TooLarge) for data longer than Self::max_object. NotWritten, UnsafeDevice, Unverified, NoSpace or Io before anything reached the device (the target is untouched). DurabilityUnknown if a write, the length update or the flush of the new bytes failed (the target is untouched) or anything from the rename on failed (the directory may name either version); the handle is then poisoned and later changes fail with Poisoned.

Source

pub fn read(&self, name: &str) -> Result<Vec<u8>, Error>

Reads the whole file name (direct I/O: never the OS page cache).

§Errors

NotFound; Corruption(MediaError) for an unreadable range; NotWritten(InvalidName) as for Self::replace; NotWritten(TooLarge) for a file longer than Self::max_object (nothing allocated); Io.

Source

pub fn remove(&self, name: &str) -> Result<(), Error>

Removes the file name durably (unlink, then flush the directory).

§Errors

Unsupported(DirectoryFlush) or Io(SyncDir) when the directory cannot be flushed (nothing changed); NotFound (nothing changed); DurabilityUnknown if the unlink or the directory flush failed (the handle is poisoned); Poisoned; NotWritten(InvalidName) as for Self::replace. A remove takes no lock: it touches no temporary file, and a replace and a remove of one name racing each other end in either order.

Source

pub fn sync(&self) -> Result<(), Error>

Flushes the directory: every create, rename and unlink in it so far becomes durable.

§Errors

Unsupported(DirectoryFlush) or Io(SyncDir) when the directory cannot be flushed; DurabilityUnknown (the handle is poisoned); Poisoned.

Trait Implementations§

Source§

impl<P: Platform> Debug for Directory<P>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<P> !Freeze for Directory<P>

§

impl<P> Forget for Directory<P>

§

impl<P> Move for Directory<P>

§

impl<P> RefUnwindSafe for Directory<P>

§

impl<P> Send for Directory<P>
where <P as Platform>::Dir: Send, QueueSet<<P as Platform>::Queue>: Send, OnceLock<<P as Platform>::File>: Send,

§

impl<P> Sync for Directory<P>
where <P as Platform>::Dir: Sync, QueueSet<<P as Platform>::Queue>: Sync, OnceLock<<P as Platform>::File>: Sync,

§

impl<P> Unpin for Directory<P>
where P: Unpin, <P as Platform>::Dir: Unpin, QueueSet<<P as Platform>::Queue>: Unpin, OnceLock<<P as Platform>::File>: Unpin,

§

impl<P> UnsafeUnpin for Directory<P>
where P: UnsafeUnpin, <P as Platform>::Dir: UnsafeUnpin, QueueSet<<P as Platform>::Queue>: UnsafeUnpin, OnceLock<<P as Platform>::File>: UnsafeUnpin,

§

impl<P> UnwindSafe for Directory<P>
where P: UnwindSafe, <P as Platform>::Dir: UnwindSafe, QueueSet<<P as Platform>::Queue>: UnwindSafe, OnceLock<<P as Platform>::File>: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.