Overview

Module mrdb

• Description
• Data Types
• Function Index
• Function Details

Description

Mid-level access API for Mnesia-managed rocksdb tables

This module implements access functions for the mnesia_rocksdb backend plugin. The functions are designed to also support direct access to rocksdb with little overhead. Such direct access will maintain existing indexes, but not support replication.

Each table has a metadata structure stored as a persistent term for fast access. The structure of the metadata is as follows:

  #{ name       := <Logical table name>
   , db_ref     := <Rocksdb database Ref>
   , cf_handle  := <Rocksdb column family handle>
   , activity   := Ongoing batch or transaction, if any (map())
   , attr_pos   := #{AttrName := Pos}
   , mode       := <Set to 'mnesia' for mnesia access flows>
   , properties := <Mnesia table props in map format>
   , type       := column_family | standalone
   }

Helper functions like as_batch(Ref, fun(R) -> ... end) and with_iterator(Ref, fun(I) -> ... end) add some extra convenience on top of the rocksdb API.

Data Types

activity()

activity() = tx_activity() | batch_activity()

activity_type()

activity_type() = mrdb_activity_type() | mnesia_activity_type()

admin_tab()

admin_tab() = {admin, alias()}

alias()

alias() = atom()

attr_pos()

attr_pos() = #{atom() := pos()}

batch_activity()

batch_activity() = #{type := batch, handle := batch_handle()}

batch_handle()

batch_handle() = rocksdb:batch_handle()

cf_handle()

cf_handle() = rocksdb:cf_handle()

db_handle()

db_handle() = rocksdb:db_handle()

db_ref()

db_ref() = #{name => table(), alias => atom(), vsn => non_neg_integer(), db_ref := db_handle(), cf_handle := cf_handle(), semantics := semantics(), encoding := encoding(), attr_pos := attr_pos(), type := column_family | standalone, status := open | closed | pre_existing, properties := properties(), mode => mnesia, ix_vals_f => fun((tuple()) -> [any()]), activity => activity(), term() => term()}

encoding()

encoding() = raw | sext | term | {key_encoding(), val_encoding()}

error()

error() = {error, any()}

index()

index() = {tab_name(), index, any()}

index_position()

index_position() = atom() | pos()

inner()

inner() = non_neg_integer()

iterator_action()

iterator_action() = first | last | next | prev | binary() | {seek, binary()} | {seek_for_prev, binary()}

itr_handle()

itr_handle() = rocksdb:itr_handle()

key()

key() = any()

key_encoding()

key_encoding() = raw | sext | term

mnesia_activity_type()

mnesia_activity_type() = transaction | sync_transaction | async_dirty | sync_dirty

mrdb_activity_type()

mrdb_activity_type() = tx | {tx, tx_options()} | batch

mrdb_iterator()

mrdb_iterator() = #mrdb_iter{i = itr_handle(), ref = db_ref()}

obj()

obj() = tuple()

outer()

outer() = non_neg_integer()

pos()

pos() = non_neg_integer()

properties()

properties() = #{record_name := atom(), attributes := [atom()], index := [{pos(), bag | ordered}]}

read_options()

read_options() = [{verify_checksums, boolean()} | {fill_cache, boolean()} | {iterate_upper_bound, binary()} | {iterate_lower_bound, binary()} | {tailing, boolean()} | {total_order_seek, boolean()} | {prefix_same_as_start, boolean()} | {snapshot, snapshot_handle()}]

ref_or_tab()

ref_or_tab() = table() | db_ref()

retainer()

retainer() = {tab_name(), retainer, any()}

retries()

retries() = outer() | {inner(), outer()}

semantics()

semantics() = bag | set

snapshot_handle()

snapshot_handle() = rocksdb:snapshot_handle()

tab_name()

tab_name() = atom()

table()

table() = atom() | admin_tab() | index() | retainer()

tx_activity()

tx_activity() = #{type := tx, handle := tx_handle(), attempt := undefined | retries()}

tx_handle()

tx_handle() = rocksdb:transaction_handle()

tx_options()

tx_options() = #{retries => retries(), no_snapshot => boolean()}

val_encoding()

val_encoding() = {value | object, term | raw} | raw

write_options()

write_options() = [{sync, boolean()} | {disable_wal, boolean()} | {ignore_missing_column_families, boolean()} | {no_slowdown, boolean()} | {low_pri, boolean()}]

Function Index

Function Details

abort/1

Aborts an ongoing activity/2

activity/3

Run an activity (similar to //mnesia/mnesia:activity/2).

• transaction - An optimistic rocksdb transaction
• {tx, TxOpts} - A rocksdb transaction with sligth modifications
• batch - A rocksdb batch operation

By default, transactions are combined with a snapshot with 1 retry. The snapshot ensures that writes from concurrent transactions don't leak into the transaction context. A transaction will be retried if it detects that the commit set conflicts with recent changes. A mutex is used to ensure that only one of potentially conflicting mrdb transactions is run at a time. The re-run transaction may still fail, if new transactions, or non-transaction writes interfere with the commit set. It will then be re-run again, until the retry count is exhausted.

For finer-grained retries, it's possible to set retries => {Inner, Outer}. Setting the retries to a single number, Retries, is analogous to {0, Retries}`. Each outer retry requests amutex lock' by waiting in a FIFO queue. Once it receives the lock, it will try the activity once + as many retries as specified by Inner. If these fail, the activity again goes to the FIFO queue (ending up last in line) if there are outer retries remaining. When all retries are exhaused, the activity aborts with retry_limit. Note that transactions, being optimistic, do not request a lock on the first attempt, but only on outer retries (the first retry is always an outer retry).

Valid TxOpts are #{no_snapshot => boolean(), retries => retries()}.

alias_of/1

Returns the alias of a given table or table reference.

as_batch/2

Creates a rocksdb batch context and executes the fun F in it.

as_batch/3

as as_batch/2, but with the ability to pass Opts to rocksdb:write_batch/2

batch_write/2

batch_write/3

clear_table/1

current_context/0

delete/2

delete/3

delete_object/2

delete_object/3

ensure_ref/1

ensure_ref/2

first/1

first/2

fold/3

fold/4

fold/5

get_batch/1

get_ref/1

index_read/3

insert/2

insert/3

iterator/1

iterator/2

iterator_close/1

iterator_move/2

last/1

last/2

match_delete/2

new_tx/1

new_tx/2

next/2

next/3

prev/2

prev/3

rdb_delete/2

rdb_delete/3

rdb_fold/4

rdb_fold/5

rdb_get/2

rdb_get/3

rdb_iterator/1

rdb_iterator/2

rdb_iterator_move/2

rdb_put/3

rdb_put/4

read/2

read/3

read_info/1

read_info/2

release_snapshot/1

release a snapshot created by snapshot/1.

select/1

select/2

select/3

snapshot/1

Create a snapshot of the database instance associated with the table reference, table name or alias.

tx_commit/1

tx_ref/2

update_counter/3

update_counter/4

with_iterator/2

with_iterator/3

with_rdb_iterator/2

with_rdb_iterator/3

write_info/3

Overview

Generated by EDoc