Struct jammdb::OpenOptions

pub struct OpenOptions { /* private fields */ }

Options to configure how a DB is opened.

This struct acts as a builder for a DB and allows you to specify the initial pagesize and number of pages you want to allocate for a new database file.

Examples

use jammdb::{DB, OpenOptions};

let db = OpenOptions::new()
    .pagesize(4096)
    .num_pages(32)
    .open("my.db")?;

// do whatever you want with the DB

Implementations

impl OpenOptions

pub fn new() -> Self

Returns a new OpenOptions, with the default values.

pub fn pagesize(self, pagesize: u64) -> Self

Sets the pagesize for the database

By default, your OS’s pagesize is used as the database’s pagesize, but if the file is moved across systems with different page sizes, it is necessary to set the correct value. Trying to open an existing database with the incorrect page size will result in a panic.

Panics

Will panic if you try to set the pagesize < 1024 bytes.

pub fn num_pages(self, num_pages: usize) -> Self

Sets the number of pages to allocate for a new database file.

The default num_pages is set to 32, so if your pagesize is 4096 bytes (4kb), then 131,072 bytes (128kb) will be allocated for the initial file. Setting num_pages when opening an existing database has no effect.

Panics

Since a minimum of four pages are required for the database, this function will panic if you provide a value < 4.

pub fn strict_mode(self, strict_mode: bool) -> Self

Enables or disables “Strict Mode”, where each transaction will check the database for errors before finalizing a write.

The default is false, but you may enable this if you want an extra degree of safety for your data at the cost of slower writes.

pub fn mmap_populate(self, mmap_populate: bool) -> Self

Enables or disables the MAP_POPULATE flag for the mmap call, which will cause Linux to eagerly load pages into memory.

The default is false, but you may enable this if your database file will stay smaller than your available memory. It is not recommended to enable this unless you know what you are doing.

This setting only works on Linux, and is a no-op on other platforms.

pub fn direct_writes(self, direct_writes: bool) -> Self

Enables or disables the O_DIRECT flag when opening the database file. This gives a hint to Linux to bypass any operarating system caches when writing to this file.

The default is false, but you may enable this if your database is much larger than your available memory to avoid throttling the page cache. It is not recommended to enable this unless you know what you are doing.

This setting only works on Linux, and is a no-op on other platforms.

pub fn open<P: AsRef<Path>>(self, path: P) -> Result<DB, Error>

Opens the database with the current options.

If the file does not exist, it will initialize an empty database with a size of (num_pages * pagesize) bytes. If it does exist, the file is opened with both read and write permissions, and we attempt to create an exclusive lock on the file. Getting the file lock will block until the lock is released to prevent you from having two processes modifying the file at the same time. This lock is not foolproof though, so it is up to the user to make sure only one process has access to the database at a time (unless it is read-only).

Errors

Will return an error if there are issues creating a new file, opening an existing file, obtaining the file lock, or creating the memory map.

Panics

Will panic if the pagesize the database is opened with is not the same as the pagesize it was created with.

Trait Implementations

impl Default for OpenOptions

fn default() -> Self

Returns the “default value” for a type.