Trait tantivy::Directory

source · [−]

pub trait Directory: DirectoryClone + Debug + Send + Sync + 'static {
    fn get_file_handle(
        &self, 
        path: &Path
    ) -> Result<Box<dyn FileHandle>, OpenReadError>;
    fn delete(&self, path: &Path) -> Result<(), DeleteError>;
    fn exists(&self, path: &Path) -> Result<bool, OpenReadError>;
    fn open_write(&self, path: &Path) -> Result<WritePtr, OpenWriteError>;
    fn atomic_read(&self, path: &Path) -> Result<Vec<u8>, OpenReadError>;
    fn atomic_write(&self, path: &Path, data: &[u8]) -> Result<()>;
    fn sync_directory(&self) -> Result<()>;
    fn watch(&self, watch_callback: WatchCallback) -> Result<WatchHandle>;

    fn open_read(&self, path: &Path) -> Result<FileSlice, OpenReadError> { ... }
    fn acquire_lock(&self, lock: &Lock) -> Result<DirectoryLock, LockError> { ... }
}

Expand description

Write-once read many (WORM) abstraction for where tantivy’s data should be stored.

There are currently two implementations of Directory

The MMapDirectory, this should be your default choice.
The RamDirectory, which should be used mostly for tests.

Required Methods

source

fn get_file_handle(
&self,
path: &Path
) -> Result<Box<dyn FileHandle>, OpenReadError>

Opens a file and returns a boxed FileHandle.

Users of Directory should typically call Directory::open_read(...), while Directory implementor should implement get_file_handle().

source

fn delete(&self, path: &Path) -> Result<(), DeleteError>

Removes a file

Removing a file will not affect an eventual existing FileSlice pointing to it.

Removing a nonexistent file, yields a DeleteError::DoesNotExist.

source

fn exists(&self, path: &Path) -> Result<bool, OpenReadError>

Returns true if and only if the file exists

source

fn open_write(&self, path: &Path) -> Result<WritePtr, OpenWriteError>

Opens a writer for the virtual file associated with a Path.

Right after this call, for the span of the execution of the program the file should be created and any subsequent call to open_read for the same path should return a FileSlice.

However, depending on the directory implementation, it might be required to call sync_directory to ensure that the file is durably created. (The semantics here are the same when dealing with a posix filesystem.)

Write operations may be aggressively buffered. The client of this trait is responsible for calling flush to ensure that subsequent read operations will take into account preceding write operations.

Flush operation should also be persistent.

The user shall not rely on Drop triggering flush. Note that RamDirectory will panic! if flush was not called.

The file may not previously exist.

source

fn atomic_read(&self, path: &Path) -> Result<Vec<u8>, OpenReadError>

Reads the full content file that has been written using atomic_write.

This should only be used for small files.

You should only use this to read files create with Directory::atomic_write.

source

fn atomic_write(&self, path: &Path, data: &[u8 ]) -> Result<()>

Atomically replace the content of a file with data.

This calls ensure that reads can never observe a partially written file.

The file may or may not previously exist.

source

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

Sync the directory.

This call is required to ensure that newly created files are effectively stored durably.

source

fn watch(&self, watch_callback: WatchCallback) -> Result<WatchHandle>

Registers a callback that will be called whenever a change on the meta.json using the atomic_write API is detected.

The behavior when using .watch() on a file using Directory::open_write is, on the other hand, undefined.

The file will be watched for the lifetime of the returned WatchHandle. The caller is required to keep it. It does not override previous callbacks. When the file is modified, all callback that are registered (and whose WatchHandle is still alive) are triggered.

Internally, tantivy only uses this API to detect new commits to implement the OnCommit ReloadPolicy. Not implementing watch in a Directory only prevents the OnCommit ReloadPolicy to work properly.