Struct cannyls::storage::Storage

pub struct Storage<N> where
    N: NonVolatileMemory,  { /* fields omitted */ }

Lumpを格納するためのストレージ.

基本的には、Storageインスタンスの構築後はDevice経由で操作することが想定されている.

ストレージのフォーマットに関してはストレージフォーマット(v1.0)を参照のこと.

Methods

impl<N> Storage<N> where
    N: NonVolatileMemory, 

pub fn create(nvm: N) -> Result<Self>

デフォルト設定で、新規にストレージを生成する.

pub fn open(nvm: N) -> Result<Self>

デフォルト設定で、既に存在するストレージをオープンする.

pub fn header(&self) -> &StorageHeader

ストレージのヘッダ情報を返す.

pub fn metrics(&self) -> &StorageMetrics

ストレージのメトリクスを返す.

pub fn usage_range(&self, range: Range<LumpId>) -> StorageUsage

ストレージに保存されている中で、指定された範囲が占有するバイト数を返す.

pub fn get(&mut self, lump_id: &LumpId) -> Result<Option<LumpData>>

指定されたIDのlumpを取得する.

Error Handlings

このメソッドがエラーを返した場合には、 不整合ないしI/O周りで致命的な問題が発生している可能性があるので、 以後はこのインスタンスの使用を中止するのが望ましい (更新系操作とは異なり、何度かリトライを試みても問題はない).

pub fn head(&self, lump_id: &LumpId) -> Option<LumpHeader>

指定されたIDのlumpのヘッダ情報を取得する.

pub fn list(&self) -> Vec<LumpId>

保存されているlumpのID一覧を返す.

結果は昇順にソートされている.

注意

例えば巨大なHDDを使用している場合には、lumpの数が数百万以上になることもあるため、 このメソッドは呼び出す際には注意が必要.

pub fn list_range(&mut self, range: Range<LumpId>) -> Vec<LumpId>

ストレージに保存されている中で、指定された範囲に含まれるLumpIdの一覧を返す.

pub fn put(&mut self, lump_id: &LumpId, data: &LumpData) -> Result<bool>

lumpを保存する.

既に同じIDのlumpが存在する場合にはデータが上書きされる.

新規追加の場合にはOk(true)が、上書きの場合にはOk(false)が返される.

Error Handlings

このメソッドがErrorKind::{Full, InvalidInput}以外のエラーを返した場合には、 不整合ないしI/O周りで致命的な問題が発生している可能性があるので、 以後はこのインスタンスの使用を中止するのが望ましい.

性能上の注意

引数に渡されるLumpDataが、LumpData::new関数経由で生成されている場合には、 NVMへの書き込み前に、データをブロック境界にアライメントするためのメモリコピーが余分に発生してしまう. それを避けたい場合には、Storage::allocate_lump_dataメソッドを使用してLumpDataを生成すると良い.

pub fn delete(&mut self, lump_id: &LumpId) -> Result<bool>

指定されたIDのlumpを削除する.

削除が行われた場合にはOk(true)が、存在しないlumpが指定された場合にはOk(false)が、返される.

Error Handlings

このメソッドがエラーを返した場合には、 不整合ないしI/O周りで致命的な問題が発生している可能性があるので、 以後はこのインスタンスの使用を中止するのが望ましい.

pub fn delete_range(&mut self, range: Range<LumpId>) -> Result<Vec<LumpId>>

LumpIdのrange [start..end) を用いて、これに含まれるLumpIdを全て削除する。

返り値がOk(vec)の場合、このvecは実際に削除したlump id全体となっている。 （注意: rangeには、lusf上にないlump idが一般には含まれている）

Error Handlings

このメソッドがエラーを返した場合には、 不整合ないしI/O周りで致命的な問題が発生している可能性があるので、 以後はこのインスタンスの使用を中止するのが望ましい.

注意

rangeが大量の要素を含む場合には、 このメソッドは巨大なLumpIdの配列を返しうることに注意されたい。

pub fn allocate_lump_data(&self, size: usize) -> Result<LumpData>

ストレージのブロック境界にアライメントされたメモリ領域を保持するLumpDataインスタンスを返す.

LumpData::new関数に比べて、このメソッドが返したLumpDataインスタンスは、 事前に適切なアライメントが行われているため、Storage::putによる保存時に余計なメモリコピーが 発生することがなく、より効率的となる.

注意

このストレージが返したLumpDataインスタンスを、別の(ブロックサイズが異なる)ストレージに 保存しようとした場合には、エラーが発生する.

Errors

指定されたサイズがMAX_SIZEを超えている場合は、ErrorKind::InvalidInputエラーが返される.

pub fn allocate_lump_data_with_bytes(&self, bytes: &[u8]) -> Result<LumpData>

allocate_lump_dataメソッドにデータの初期化を加えたメソッド.

このメソッドの呼び出しは、以下のコードと等価となる:

let mut data = track!(self.allocate_lump_data(bytes.len()))?;
data.as_bytes_mut().copy_from_slice(bytes);

詳細な挙動に関してはallocate_lump_dataのドキュメントを参照のこと.

pub fn run_side_job_once(&mut self) -> Result<()>

補助的な処理を一単位実行する.

このメソッドを呼ばなくても動作上は問題はないが、 リソースが空いているタイミングで実行することによって、 全体的な性能を改善できる可能性がある.

pub fn journal_sync(&mut self) -> Result<()>

メモリにバッファされているジャーナルをディスクに書き出す。 副作用として、バッファはクリアされる。

pub fn journal_gc(&mut self) -> Result<()>

ジャーナル領域に対するGCを実行する。

ここで実行するGCは、ジャーナル領域のHEADからTAILの間の値を全て検査し、 journal_gc を呼び出した段階で破棄できる全エントリを削除する。

通常のstorageの使用では、各エントリをジャーナルに追加する際に、 小規模のGCが走る（正確には JournalRegion::gc_once）ので、 このGCを手動で呼び出す必要はない。

pub fn journal_snapshot(&mut self) -> Result<JournalSnapshot>

ジャーナル領域のスナップショットを取得する。

Trait Implementations

impl<N: Debug> Debug for Storage<N> where
    N: NonVolatileMemory, 

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

Formats the value using the given formatter.