◄►The Ciao System » PART X - Contributed libraries » Ciao DHT Implementation » Top-level interface to a DHT server » DHT-related logics »

Underlying data-storage module

Author(s): Arsen Kostenko.

This module contains very low-level utilities of data storage specific to a single node. Neither data sharing nor remote invocation is performed at this level. Note that no dedicated data manipulation is performed neither on this level. Also keep in mind that concept of Key should always meet the same constraints as the second argument of functor/3 predicate. Important decision taken at this point is representation of all information stored in the DHT as usual Prolog facts. This behavior is implemented by representing relations of form Key -> Value in form of Key(Value) facts.

Usage and interface

Documentation on exports

PREDICATE
dht_store/3:
This predicate stores information into the local (module-local) database. The three arguments stand for key, value, and value of hash-function, when applied to the key. The third argument is needed for auxiliary database, which is used by reverse lookup.

Usage:dht_store(Key,KeyHash,Value)

The value provided in Value is stored under a key given as Key.

  • The following properties should hold at call time:
    (basic_props:atm/1)Key is an atom.
    (basic_props:int/1)KeyHash is an integer.
    (basic_props:gnd/1)Value is ground.

PREDICATE
dht_extract_b/2:
Looks up local database for fact of following type Key/1, that takes Value as argument. The pair is extracted from the database if there is at lease one match. Otherwise call is blocking once the fact is not found instantly.

Usage 1:dht_extract_b(Key,Value)

Search for exact fact.

  • The following properties should hold at call time:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.

Usage 2:dht_extract_b(Key,Value)

Search for fact matching pattern. Pattern is supplied as Value.

  • The following properties should hold at call time:
    (basic_props:atm/1)Key is an atom.
    (term_typing:var/1)Value is a free variable.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.

PREDICATE
dht_extract_nb/2:
Looks up the local database for a fact of type Key/1 that takes Value as argument. If a corresponding fact is found in database, it is extracted from it. With respect to behavior of dht_extract_b/2, this predicated has a useful difference - it does not block while searching.

Usage 1:dht_extract_nb(Key,Value)

Check that combination of Key/Value appears in database.

  • The following properties should hold at call time:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.

Usage 2:dht_extract_nb(Key,Value)

Search for combination of Key/Value matching pattern. Pattern is supplied as Value.

  • The following properties should hold at call time:
    (basic_props:atm/1)Key is an atom.
    (term_typing:var/1)Value is a free variable.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.

PREDICATE
dht_consult_b/2:
Looks up local database for combination of Key/Value of following type Key/1 that takes Value as argument. The combination of Key/Value is only looked up. If there is no corresponding combination of Key/Value in local database, dht_consult_b/2 blocks until such fact is inserted. Nothing is done neither to combination of Key/Value nor to local database.

Usage 1:dht_consult_b(Key,Value)

Search for exact combination of Key/Value.

  • The following properties should hold at call time:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.

Usage 2:dht_consult_b(Key,Value)

Search for combination of Key/Value matching pattern. Pattern is supplied as Value.

  • The following properties should hold at call time:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.

PREDICATE
dht_consult_nb/2:
Looks up local database for combination of Key/Value of following type Key/1 that takes Value as argument. The combination of Key/Value is only looked up - no modifications are done in any case (whether a match was found or not). As in case with dht_extract_nb/2, this predicate does not block while searching for matching values.

Usage 1:dht_consult_nb(Key,Value)

Search for exact combination of Key/Value.

  • The following properties should hold at call time:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.

Usage 2:dht_consult_nb(Key,Value)

Search for combination of Key/Value matching pattern. Pattern is supplied as Value.

  • The following properties should hold at call time:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Key is an atom.
    (basic_props:gnd/1)Value is ground.

PREDICATE
dht_key_hash/2:
A general read-interface to auxiliary database, in order to perform reverse search: 'get set of keys by corresponding value of hash function'.

Usage 1:dht_key_hash(Key,KeyHash)

The most general case (when both arguments are free) is searching for any key-hash pair stored in auxiliary database.

  • The following properties should hold at call time:
    (term_typing:var/1)Key is a free variable.
    (term_typing:var/1)KeyHash is a free variable.
  • The following properties should hold upon exit:
    (basic_props:gnd/1)Key is ground.
    (basic_props:int/1)KeyHash is an integer.

Usage 2:dht_key_hash(Key,KeyHash)

Here Key is ground, which in turn leads to search for information on concrete predicate.

  • The following properties should hold at call time:
    (basic_props:gnd/1)Key is ground.
    (term_typing:var/1)KeyHash is a free variable.
  • The following properties should hold upon exit:
    (basic_props:gnd/1)Key is ground.
    (basic_props:int/1)KeyHash is an integer.

Usage 3:dht_key_hash(Key,KeyHash)

On the contrary to previous example, this one has only second argument KeyHash ground. Therefore, this type of call would search for keys, that where mapped into given value of hash-function.

  • The following properties should hold at call time:
    (term_typing:var/1)Key is a free variable.
    (basic_props:int/1)KeyHash is an integer.
  • The following properties should hold upon exit:
    (basic_props:gnd/1)Key is ground.
    (basic_props:int/1)KeyHash is an integer.

Usage 4:dht_key_hash(Key,KeyHash)

Finally, calling dht_key_hash with both arguments ground is similar to straight-forward check on auxiliary database, or to asking a question: “Does auxiliary database has any information on this key, which is mapped into that hash value?”

  • The following properties should hold at call time:
    (basic_props:gnd/1)Key is ground.
    (basic_props:int/1)KeyHash is an integer.

Module Sections

Global Links

Indices

◄► 
Generated with LPdoc using Ciao