Trait ShadowStore 

pub trait ShadowStore {
    // Required methods
    fn read_row(
        &mut self,
        root: u32,
        rowid: i64,
    ) -> DbResult<Option<Vec<Value<'static>>>>;
    fn write_row(
        &mut self,
        root: u32,
        rowid: i64,
        values: &[Value<'static>],
    ) -> DbResult<()>;
    fn delete_row(&mut self, root: u32, rowid: i64) -> DbResult<()>;
    fn max_rowid(&mut self, root: u32) -> DbResult<i64>;
    fn scan(
        &mut self,
        root: u32,
        body: &mut dyn FnMut(i64, &[Value<'static>]) -> DbResult<bool>,
    ) -> DbResult<()>;
    fn read_keyed(
        &mut self,
        root: u32,
        key: &[Value<'static>],
        columns: usize,
    ) -> DbResult<Option<Vec<Value<'static>>>>;
    fn write_keyed(
        &mut self,
        root: u32,
        key_columns: usize,
        values: &[Value<'static>],
    ) -> DbResult<()>;
    fn delete_keyed(
        &mut self,
        root: u32,
        key: &[Value<'static>],
    ) -> DbResult<()>;
    fn scan_keyed(
        &mut self,
        root: u32,
        key_columns: usize,
        body: &mut dyn FnMut(&[Value<'static>]) -> DbResult<bool>,
    ) -> DbResult<()>;

    // Provided methods
    fn scan_from(
        &mut self,
        root: u32,
        from: i64,
        body: &mut dyn FnMut(i64, &[Value<'static>]) -> DbResult<bool>,
    ) -> DbResult<()> { ... }
    fn scan_keyed_from(
        &mut self,
        root: u32,
        key_columns: usize,
        from: &[Value<'static>],
        body: &mut dyn FnMut(&[Value<'static>]) -> DbResult<bool>,
    ) -> DbResult<()> { ... }
}

The rows of a module’s shadow tables, whatever engine holds them.

This is the seam the TDD’s “shadow tables become ordinary trees” needs. FTS5 and the R-Tree keep their whole state in shadow tables and reach them only through ShadowTables, so the modules themselves say nothing about pages, cursors or b-trees - which is what lets the same module code run over the old engine’s sqlite_master b-trees and the new engine’s PAX trees. A module that had reached a pager directly would have to be written twice.

Every method names a root, because a module is handed the roots of its own shadow tables and nothing else. There is no name resolution here and no catalog: a module that wanted to read somebody else’s table would have to be given it.

The rowid methods are for a rowid table, where the first value of a row is its rowid; the keyed ones are for a WITHOUT ROWID table, whose whole row is its key. FTS5 uses both.

Required Methods

fn read_row( &mut self, root: u32, rowid: i64, ) -> DbResult<Option<Vec<Value<'static>>>>

Reads one row by rowid, or nothing when there is not one.

@param root - the shadow table’s root @param rowid - the row’s key

fn write_row( &mut self, root: u32, rowid: i64, values: &[Value<'static>], ) -> DbResult<()>

Writes one row by rowid, replacing whatever was there.

@param root - the shadow table’s root @param rowid - the row’s key @param values - the row, its rowid first

fn delete_row(&mut self, root: u32, rowid: i64) -> DbResult<()>

Removes one row by rowid, reporting nothing when there was not one.

@param root - the shadow table’s root @param rowid - the row’s key

fn max_rowid(&mut self, root: u32) -> DbResult<i64>

Returns the largest rowid one shadow table holds.

@param root - the shadow table’s root

fn scan( &mut self, root: u32, body: &mut dyn FnMut(i64, &[Value<'static>]) -> DbResult<bool>, ) -> DbResult<()>

Runs a body over every row, in rowid order, stopping when it says so.

@param root - the shadow table’s root @param body - what to do with each row

fn read_keyed( &mut self, root: u32, key: &[Value<'static>], columns: usize, ) -> DbResult<Option<Vec<Value<'static>>>>

Reads one row of a keyed shadow table, or nothing when there is not one.

@param root - the shadow table’s root @param key - the leading columns that identify it @param columns - how many columns to return, usize::MAX for all

fn write_keyed( &mut self, root: u32, key_columns: usize, values: &[Value<'static>], ) -> DbResult<()>

Writes one row of a keyed shadow table, replacing whatever was there.

@param root - the shadow table’s root @param key_columns - how many leading columns form the key @param values - the whole row

fn delete_keyed(&mut self, root: u32, key: &[Value<'static>]) -> DbResult<()>

Removes one row of a keyed shadow table.

@param root - the shadow table’s root @param key - the leading columns that identify it

fn scan_keyed( &mut self, root: u32, key_columns: usize, body: &mut dyn FnMut(&[Value<'static>]) -> DbResult<bool>, ) -> DbResult<()>

Runs a body over every row of a keyed shadow table, in key order.

@param root - the shadow table’s root @param key_columns - how many leading columns form the key @param body - what to do with each row

Provided Methods

fn scan_from( &mut self, root: u32, from: i64, body: &mut dyn FnMut(i64, &[Value<'static>]) -> DbResult<bool>, ) -> DbResult<()>

Runs a body over every row whose rowid is at least from, in rowid order, stopping when it says so.

A seek, not a scan with a filter, when an implementor has one. A rowid table’s rows are already in key order, so a caller that only wants what is above a watermark - a delta log’s deltas_above, chief among them - does not need every row below it decoded and thrown away; it needs the store to descend to from once and walk right from there.

The default is correct rather than fast, and that is deliberate. It is Self::scan with a callback that skips what is below from, which costs the whole table exactly as a hand-written filter would - so an implementor with no cheap way to position by key is still right by doing nothing, and one that can descend directly to a key overrides this with that descent. Every rowid tree the new engine keeps can; the retired engine’s b-trees, reached only from the differential suites that still exercise it, are left on the default because a seek there is not worth building for a store on its way out.

@param root - the shadow table’s root @param from - the smallest rowid to visit @param body - what to do with each row

fn scan_keyed_from( &mut self, root: u32, key_columns: usize, from: &[Value<'static>], body: &mut dyn FnMut(&[Value<'static>]) -> DbResult<bool>, ) -> DbResult<()>

Runs a body over every row of a keyed shadow table whose key sorts at or after from, in key order, stopping when it says so.

The keyed twin of Self::scan_from, for a key of more than one column. FTS5’s %_idx is keyed (segid, term), so a caller that wants one segment’s terms starting at a prefix - a term-major seek to (segid, prefix), once per live segment - needs to position by a key that is not the whole row, the same shape a rowid seek already had and a single-column keyed seek would not need a new method for.

The default is correct rather than fast, and that is deliberate, for the reason Self::scan_from’s default is: it is Self::scan_keyed with a callback that skips whatever sorts below from, so an implementor with no cheap way to position by key is still right by doing nothing, and one that can descend directly to a key overrides this with that descent.

@param root - the shadow table’s root @param key_columns - how many leading columns form the key @param from - the key to start at, compared column by column @param body - what to do with each row

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors