Module db_dht

DB back-end for DHTs storing db_entry:entry() objects.

Copyright © 2009-2015 Zuse Institute Berlin,

Version: $Id$

Authors: Florian Schintke (schintke@zib.de), Nico Kruber (kruber@zib.de), Jan Fajerski (fajerski@zib.de).

Description

DB back-end for DHTs storing db_entry:entry() objects.

Data Types

client_version()

client_version() = non_neg_integer()

db()

db() = 
    {KeyValueDB :: term(),
     Subscribers :: db_ets:db(),
     SnaphotInfo ::
         {term() | false,
          LiveLockCount :: non_neg_integer(),
          SnapLockCount :: non_neg_integer()}}

db_as_list()

db_as_list() = [db_entry:entry()]

value()

value() = rdht_tx:encoded_value()

version()

version() = client_version()

Function Index

new/1Initializes a new database.
close/1Closes the given DB (it may be recoverable using open/1 depending on the DB back-end).
close_and_delete/1Closes the given DB and deletes all contents (this DB can thus not be re-opened using open/1).
get_load/1Returns the number of stored keys.
get_load/2Returns the number of stored keys in the given interval.
get_data/1Returns all (including empty, but not null) DB entries.
get_data/3
get_entry/2Gets an entry from the DB.
set_entry/2
set_entry/4
delete_entry/2Removes all values with the given entry's key from the DB.
delete_entry_at_key/2
update_entry/2Updates an existing (!) entry in the DB.
read/2Reads the version and value of a key.
write/4Updates the value of the given key.
delete/2Deletes the key.
get_chunk/4Returns all key-value pairs of the given DB which are in the given interval but at most ChunkSize elements.
get_chunk/6
get_split_key/5Returns the key that would remove not more than TargetLoad entries from the DB when starting at the key directly after Begin in case of forward searches and directly at Begin in case of backward searches, respectively.
split_data/2Splits the database into a database (first element) which contains all keys in MyNewInterval and a list of the other values (second element).
add_data/2Adds all db_entry objects in the Data list.
get_entries/2Gets (non-empty) db_entry objects in the given range.
get_entries/3Gets all custom objects (created by ValueFun(DBEntry)) from the DB for which FilterFun returns true.
record_changes/2Adds the new interval to the interval to record changes for.
stop_record_changes/1Stops recording changes and removes all entries from the table of changed keys.
stop_record_changes/2Stops recording changes in the given interval and removes all such entries from the table of changed keys.
get_changes/1Gets all db_entry objects which have (potentially) been changed or deleted (might return objects that have not changed but have been touched by one of the DB setters).
get_changes/2Gets all db_entry objects in the given interval which have (potentially) been changed or deleted (might return objects that have not changed but have been touched by one of the DB setters).
delete_entries/2Deletes all objects in the given Range or (if a function is provided) for which the FilterFun returns true from the DB.
snapshot_is_running/1
add_snapshot_data/2
get_snapshot_data/2Returns snapshot data as is for a specific interval.
init_snapshot/1
delete_snapshot/1
join_snapshot_data/1Join snapshot and primary db such that all tuples in the primary db are replaced if there is a matching tuple available in the snapshot set.
snapshot_is_lockfree/1
get_live_lc/1
get_snap_lc/1
get_snapshot_data/1Returns snapshot data as is for whole interval.
set_snapshot_entry/2
get_snapshot_entry/2
delete_snapshot_entry/2Removes all values with the given entry's key from the Snapshot DB.
delete_snapshot_entry_at_key/2
check_db/1Checks whether all entries in the DB are valid, i.e.
copy_value_to_snapshot_table/2Copy existing entry to snapshot table.
update_entries/4Updates all (existing or non-existing) non-locked entries from NewEntries for which Pred(OldEntry, NewEntry) returns true with UpdateFun(OldEntry, NewEntry).

Function Details

new/1

new(DBName :: nonempty_string() | atom()) -> db()

Initializes a new database.

close/1

close(State :: db()) -> true

Closes the given DB (it may be recoverable using open/1 depending on the DB back-end).

close_and_delete/1

close_and_delete(State :: db()) -> true

Closes the given DB and deletes all contents (this DB can thus not be re-opened using open/1).

get_load/1

get_load(DB :: db()) -> Load :: non_neg_integer()

Returns the number of stored keys.

get_load/2

get_load(DB :: db(), Interval :: intervals:interval()) ->
            Load :: integer()

Returns the number of stored keys in the given interval.

get_data/1

get_data(DB :: db()) -> db_as_list()

Returns all (including empty, but not null) DB entries.

get_data/3

get_data(DB :: db(),
         FilterFun :: fun((db_entry:entry()) -> boolean()),
         ValueFun :: fun((db_entry:entry()) -> V)) ->
            [V]

get_entry/2

get_entry(X1 :: db(), Key :: rt_chord:key()) -> db_entry:entry()

Gets an entry from the DB. If there is no entry with the given key, an empty entry will be returned.

set_entry/2

set_entry(DB :: db(), Entry :: db_entry:entry()) -> db()

set_entry/4

set_entry(State :: db(),
          Entry :: db_entry:entry(),
          TLogSnapNo :: non_neg_integer(),
          OwnSnapNo :: non_neg_integer()) ->
             db()

delete_entry/2

delete_entry(DB :: db(), Entry :: db_entry:entry()) ->
                NewDB :: db()

Removes all values with the given entry's key from the DB.

delete_entry_at_key/2

delete_entry_at_key(DB :: db(), Key :: rt_chord:key()) ->
                       NewDB :: db()

update_entry/2

update_entry(DB :: db(), Entry :: db_entry:entry()) ->
                NewDB :: db()

Updates an existing (!) entry in the DB.

read/2

read(DB :: db(), Key :: rt_chord:key()) ->
        {ok, Value :: value(), Version :: version()} |
        {ok, empty_val, -1}

Reads the version and value of a key.

write/4

write(DB :: db(),
      Key :: rt_chord:key(),
      Value :: value(),
      Version :: version()) ->
         NewDB :: db()

Updates the value of the given key.

delete/2

delete(DB :: db(), Key :: rt_chord:key()) ->
          {NewDB :: db(), Status :: ok | locks_set | undef}

Deletes the key. Returns {DB, undef} if the key does not exist in the DB, {DB, locks_set} if read or write locks are still set and {DB, ok} if the operation was successfully performed.

get_chunk/4

get_chunk(DB :: db(),
          StartId :: rt_chord:key(),
          Interval :: intervals:interval(),
          ChunkSize :: pos_integer() | all) ->
             {intervals:interval(), db_as_list()}

Returns all key-value pairs of the given DB which are in the given interval but at most ChunkSize elements. Assumes the ets-table is an ordered_set, may return data from "both ends" of the DB-range if the interval is ""wrapping around", i.e. its begin is larger than its end. Returns the chunk and the remaining interval for which the DB may still have data (a subset of I). Precond: Interval is a subset of the range of the dht_node and continuous!

get_chunk/6

get_chunk(DB :: db(),
          StartId :: rt_chord:key(),
          Interval :: intervals:interval(),
          FilterFun :: fun((db_entry:entry()) -> boolean()),
          ValueFun :: fun((db_entry:entry()) -> V),
          ChunkSize :: pos_integer() | all) ->
             {intervals:interval(), [V]}

get_split_key/5

get_split_key(DB :: db(),
              Begin :: rt_chord:key(),
              End :: rt_chord:key(),
              TargetLoad :: pos_integer(),
              X5 :: forward | backward) ->
                 {rt_chord:key(), TakenLoad :: non_neg_integer()}

Returns the key that would remove not more than TargetLoad entries from the DB when starting at the key directly after Begin in case of forward searches and directly at Begin in case of backward searches, respectively. Precond: a load larger than 0 Note: similar to get_chunk/2.

split_data/2

split_data(DB :: db(), MyNewInterval :: intervals:interval()) ->
              {NewDB :: db(), db_as_list()}

Splits the database into a database (first element) which contains all keys in MyNewInterval and a list of the other values (second element). Note: removes all keys not in MyNewInterval from the list of changed keys!

add_data/2

add_data(DB :: db(), Data :: db_as_list()) -> NewDB :: db()

Adds all db_entry objects in the Data list.

get_entries/2

get_entries(DB :: db(), Range :: intervals:interval()) ->
               db_as_list()

Gets (non-empty) db_entry objects in the given range.

get_entries/3

get_entries(DB :: db(),
            FilterFun ::
                fun((DBEntry :: db_entry:entry()) -> boolean()),
            ValueFun ::
                fun((DBEntry :: db_entry:entry()) -> Value)) ->
               [Value]

Gets all custom objects (created by ValueFun(DBEntry)) from the DB for which FilterFun returns true. TODO only for legacy compatability; get_chunk should be used

record_changes/2

record_changes(OldDB :: db(), NewInterval :: intervals:interval()) ->
                  NewDB :: db()

Adds the new interval to the interval to record changes for. Entries which have (potentially) changed can then be gathered by get_changes/1.

stop_record_changes/1

stop_record_changes(OldDB :: db()) -> NewDB :: db()

Stops recording changes and removes all entries from the table of changed keys.

stop_record_changes/2

stop_record_changes(OldDB :: db(),
                    Interval :: intervals:interval()) ->
                       NewDB :: db()

Stops recording changes in the given interval and removes all such entries from the table of changed keys.

get_changes/1

get_changes(DB :: db()) ->
               {Changed :: db_as_list(),
                Deleted :: [rt_chord:key()]}

Gets all db_entry objects which have (potentially) been changed or deleted (might return objects that have not changed but have been touched by one of the DB setters).

get_changes/2

get_changes(DB :: db(), Interval :: intervals:interval()) ->
               {Changed :: db_as_list(),
                Deleted :: [rt_chord:key()]}

Gets all db_entry objects in the given interval which have (potentially) been changed or deleted (might return objects that have not changed but have been touched by one of the DB setters).

delete_entries/2

delete_entries(DB :: db(),
               RangeOrFun ::
                   intervals:interval() |
                   fun((DBEntry :: db_entry:entry()) -> boolean())) ->
                  NewDB :: db()

Deletes all objects in the given Range or (if a function is provided) for which the FilterFun returns true from the DB.

snapshot_is_running/1

snapshot_is_running(DB :: db()) -> boolean()

add_snapshot_data/2

add_snapshot_data(DB :: db(), Entries :: db_as_list()) ->
                     NewDB :: db()

get_snapshot_data/2

get_snapshot_data(DB :: db(), Interval :: intervals:interval()) ->
                     db_as_list()

Returns snapshot data as is for a specific interval

init_snapshot/1

init_snapshot(DB :: db()) -> NewDB :: db()

delete_snapshot/1

delete_snapshot(DB :: db()) -> NewDB :: db()

join_snapshot_data/1

join_snapshot_data(DB :: db()) -> db_as_list()

Join snapshot and primary db such that all tuples in the primary db are replaced if there is a matching tuple available in the snapshot set. The other tuples are returned as is.

snapshot_is_lockfree/1

snapshot_is_lockfree(DB :: db()) -> boolean()

get_live_lc/1

get_live_lc(DB :: db()) -> non_neg_integer()

get_snap_lc/1

get_snap_lc(DB :: db()) -> non_neg_integer()

get_snapshot_data/1

get_snapshot_data(DB :: db()) -> db_as_list()

Returns snapshot data as is for whole interval

set_snapshot_entry/2

set_snapshot_entry(DB :: db(), Entry :: db_entry:entry()) ->
                      NewDB :: db()

get_snapshot_entry/2

get_snapshot_entry(DB :: db(), Key :: rt_chord:key()) ->
                      db_entry:entry()

delete_snapshot_entry/2

delete_snapshot_entry(DB :: db(), Entry :: db_entry:entry()) ->
                         NewDB :: db()

Removes all values with the given entry's key from the Snapshot DB.

delete_snapshot_entry_at_key/2

delete_snapshot_entry_at_key(DB :: db(), Key :: rt_chord:key()) ->
                                NewDB :: db()

check_db/1

check_db(DB :: db()) ->
            {true, []} | {false, InvalidEntries :: db_as_list()}

Checks whether all entries in the DB are valid, i.e. - no writelocks and readlocks at the same time - no empty_val values (these should only be in the DB temporarily) - version is greater than or equal to 0 Returns the result of the check and a list of invalid entries. Used in unittests.

copy_value_to_snapshot_table/2

copy_value_to_snapshot_table(DB :: db(), Key :: rt_chord:key()) ->
                                NewDB :: db()

Copy existing entry to snapshot table

update_entries/4

update_entries(DB :: db(),
               Values :: [db_entry:entry()],
               Pred ::
                   fun((OldEntry :: db_entry:entry(),
                        NewEntry :: db_entry:entry()) ->
                           boolean()),
               UpdateFun ::
                   fun((OldEntry :: db_entry:entry(),
                        NewEntry :: db_entry:entry()) ->
                           UpdatedEntry :: db_entry:entry())) ->
                  NewDB :: db()

Updates all (existing or non-existing) non-locked entries from NewEntries for which Pred(OldEntry, NewEntry) returns true with UpdateFun(OldEntry, NewEntry).


Generated by EDoc, Aug 2 2016, 13:43:28.