pub struct Directory<P: Platform> { /* private fields */ }Expand description
A directory of small objects, each replaced atomically.
Implementations§
Source§impl<P: Platform> Directory<P>
impl<P: Platform> Directory<P>
Sourcepub const DEFAULT_MAX_OBJECT: u64
pub const DEFAULT_MAX_OBJECT: u64
The largest object a handle writes or reads by default
(Self::with_max_object): 16 MiB.
Sourcepub fn open(
platform: P,
path: &Path,
create: bool,
trust: Trust,
) -> Result<Self, Error>
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.
Sourcepub fn with_max_object(self, max: u64) -> Self
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).
Sourcepub fn max_object(&self) -> u64
pub fn max_object(&self) -> u64
The largest object this handle writes or reads.
Sourcepub fn class(&self) -> Option<DurabilityClass>
pub fn class(&self) -> Option<DurabilityClass>
The durability class of the directory’s device, once a file has been opened through this handle.
Sourcepub fn decision(&self) -> Option<&ClassDecision>
pub fn decision(&self) -> Option<&ClassDecision>
The class decision (evidence, reasons, label), once probed.
Sourcepub fn replace(&self, name: &str, data: &[u8]) -> Result<(), Error>
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.
Sourcepub fn read(&self, name: &str) -> Result<Vec<u8>, Error>
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.
Sourcepub fn remove(&self, name: &str) -> Result<(), Error>
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.