Module mnesia_ext

API for mnesia storage modules.

Description

API for mnesia storage modules.

Data Types

checkpoint_tab()

checkpoint_tab() = {atom(), any()}

Tables that are part of checkpoint retainers have tuple identifiers. Implementations should ensure there is no possible collision in (file) namespace between "regular" tables and checkpoint tables.

match_function()

match_function() = {match_head(), match_conditions(), match_body()}

match_head()

match_head() = match_variable() | '_' | [match_head_part()]

Basically a match spec with no conditions or body. Used for match_object and match_delete. A list has OR semantics.

match_head_part()

match_head_part() = any() | '_' | match_variable()

match_specification()

match_specification() = [match_function()]

For more information see http://www.erlang.org/doc/apps/erts/match_spec.html.

match_variable()

match_variable() = '$<number>'

A variable in a match specification, e.g., '$1', '$45'.

object()

object() = tuple()

Everything stored in a table is a tuple.

tabid()

tabid() = atom() | checkpoint_tab()

A table identifier.

Function Index

add_index/2Create an index on a given position.
behaviour_info/1
create_table/2Open an existing table, creating it if necessary.
delete/2Delete all the records associated with Key.
delete_index/2Delete an index on a given position.
delete_table/1Delete the table, including any associated persistent storage.
first/1Returns the first key stored in the table according to the table's internal order, or '$end_of_table' if the table is empty.
fixtable/2(Un)Fixes a table for safe traversal.
info/2At a minimum, your table must support the following Items: * size: total number of records * memory: total space usage.
init_index/2Initialize an index on a given position.
init_table/3Replaces the existing objects of the table with objects created by calling the input function InitFun, see below.
insert/2Insert one or more objects into the table.
last/1Returns the last key stored in the table according to the table's internal order, or '$end_of_table' if the table is empty.
lookup/2Lookup the object(s) associated with the key.
match_delete/2Delete all objects which match the pattern.
match_object/2Returns all the objects that match the given pattern.
next/2Returns the next key stored in the table according to the table's internal order, or '$end_of_table' if the table is empty.
prev/2Returns the previous key stored in the table according to the table's internal order, or '$end_of_table' if the table is empty.
select/1Return additional results from a continuation returned via select/1 or select/3.
select/2Select all the results that match a given specification.
select/3Return a limited number of results from a select, plus a continuation which can return more via select/1.
slot/2Not sure.
update_counter/3Update a counter (integer field) associated with the record associated with key.

Function Details

add_index/2

add_index(Tab::tabid(), Position::integer()) -> ok | {error, Reason}

Create an index on a given position. Indices in mnesia_ext are advisory; the low level calls routed to the storage layer are still match_object/2 and match_delete/2. Essentially users who create an index on a position expect that match patterns which only that position bound are still reasonably efficient to execute.

Thus, this function advises you that steps should be taken to make match patterns with only the given position bound efficient.

behaviour_info/1

behaviour_info() -> term()

create_table/2

create_table(Tab::tabid(), Cs::cstruct()) -> {ok, Tab::tabid()} | {error, Reason}

Open an existing table, creating it if necessary. If Tab is an atom, the table is a "normal" table. If Tab is a tuple, then the table is a "checkpointer retainer" table. You must ensure that the filesystem namespace used for checkpointer retainer tables is distinct from that used for normal tables; an easy way to ensure this is to use a different filename extension.

NB: The user_properties portion of cstruct can be useful for communicating driver-specific settings.

NB: mnesia_lib:dir/0 can be called to locate the mnesia directory where you should place files.

NB: The process which calls this function is as long-lived as the mnesia application; therefore ports, ets tables, and other per-process-deallocated entities can be safely owned by the calling process.

delete/2

delete(Tab::tabid(), Key::key()) -> ok | {error, Reason}

Delete all the records associated with Key.

delete_index/2

delete_index(Tab::tabid(), Position::integer()) -> ok | {error, Reason}

Delete an index on a given position.

delete_table/1

delete_table(Tab::tabid()) -> ok | {error, Reason}

Delete the table, including any associated persistent storage.

first/1

first(Tab::tabid()) -> Key::any() | '$end_of_table'

Returns the first key stored in the table according to the table's internal order, or '$end_of_table' if the table is empty. If you support ordered_set semantics, then "internal order" means erlang term order, otherwise, you are free to interpret as you like.

fixtable/2

fixtable(Tab::tabid(), Bool::bool()) -> true

(Un)Fixes a table for safe traversal. For ordered_set tables, this function is not required to do anything.

For other tables types, when a table is fixed, a sequence of first/1 and next/2 calls are guaranteed to succeed and each object in the table will only be returned once, even if objects are removed or inserted during the traversal. The keys for new objects inserted during the traversal may be returned by next/2 (it depends on the internal ordering of the keys).

info/2

info(Tab::tabid(), What::any()) -> Value::any() | undefined

At a minimum, your table must support the following Items: * size: total number of records * memory: total space usage. it's up to you to decide whether ram or disk (or something else) is the measured space.

init_index/2

init_index(Tab::tabid(), Position::integer()) -> ok | {error, Reason}

Initialize an index on a given position. This index will already have been added by add_index/2 at some point in the past (not necessarily during the lifetime of the current Erlang node).

Essentially this function advises you to load whatever structures are necessary to utilize a particular index.

init_table/3

init_table(Tab::tabid(), InitFun::initfun(), Options::[option()]) -> ok | {error, Reason}

Replaces the existing objects of the table with objects created by calling the input function InitFun, see below.

When called with the argument read the function InitFun is assumed to return end_of_input when there is no more input, or { Objects, Fun }, where Objects is a list of objects and Fun is a new input function. Any other value Value is returned as an error { error, { init_fun, Value } }. Each input function will be called exactly once, and should an error occur, the last function is called with the argument close, the reply of which is ignored.

If the type of the table is ordered_set and there is more than one object with a given key, one of the objects is chosen. This is not necessarily the last object with the given key in the sequence of objects returned by the input functions. Extra objects should be avoided, or the file will be unnecessarily fragmented. This holds also for duplicated objects stored in tables of type bag.

The Options argument is a list of { Key, Val } tuples where the following values are allowed:

* { format, Format }. Specifies the format of the objects returned by the function InitFun. If Format is term (the default), InitFun is assumed to return a list of tuples. If Format is bchunk, InitFun is assumed to return Data as returned by bchunk/2.

insert/2

insert(Tab::tabid(), Objects::objects()) -> ok | {error, Reason}

Insert one or more objects into the table.

last/1

last(Tab::tabid()) -> Key::any() | '$end_of_table'

Returns the last key stored in the table according to the table's internal order, or '$end_of_table' if the table is empty. If you support ordered_set semantics, then "internal order" means erlang term order, otherwise, you are free to interpret as you like.

lookup/2

lookup(Tab::tabid(), Key::any()) -> [object()] | {error, Reason}

Lookup the object(s) associated with the key.

match_delete/2

match_delete(Tab::tabid(), Pattern::match_head()) -> N::integer() | {error, Reason}

Delete all objects which match the pattern. Returns the number of objects deleted.

match_object/2

match_object(Tab::tabid(), Pattern::match_head()) -> ok | {error, Reason}

Returns all the objects that match the given pattern.

next/2

next(Tab::tabid(), Key::any()) -> NextKey::any() | '$end_of_table'

Returns the next key stored in the table according to the table's internal order, or '$end_of_table' if the table is empty. If you support ordered_set semantics, then "internal order" means erlang term order, otherwise, you are free to interpret as you like.

prev/2

prev(Tab::tabid(), Key::any()) -> NextKey::any() | '$end_of_table'

Returns the previous key stored in the table according to the table's internal order, or '$end_of_table' if the table is empty. If you support ordered_set semantics, then "internal order" means erlang term order, otherwise, you are free to interpret as you like.

select/1

select(Continuation::select_continuation()) -> {[Match::object()], More::select_continuation()} | '$end_of_table' | {error, Reason}

Return additional results from a continuation returned via select/1 or select/3.

select/2

select(Tab::tabid(), MatchSpec::match_specification()) -> [Match::object()] | {error, Reason}

Select all the results that match a given specification.

select/3

select(Tab::tabid(), MatchSpec::match_specification(), Limit::integer()) -> {[Match::object()], More::select_continuation()} | '$end_of_table' | {error, Reason}

Return a limited number of results from a select, plus a continuation which can return more via select/1. You should attempt to honor the limit field, but the mnesia specification already says the limit is not guaranteed.

slot/2

slot(Tab::tabid(), N::integer()) -> [object()] | '$end_of_table' | {error, Reason}

Not sure.

update_counter/3

update_counter(Tab::tabid(), Key::any(), Increment::increment()) -> integer()

Update a counter (integer field) associated with the record associated with key. Only valid for set type tables. It is supposed to be implemented atomically at the table driver level.


Generated by EDoc, Jul 14 2008, 15:00:02.