# Module db_dht

- Description
- Data Types
- Function Index
- Function Details

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

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

## 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, Feb 29 2016, 16:12:18.