Top-level user interface to DHT

Author(s): Arsen Kostenko.

This module contains just a top-level interface to the utilities provided by the DHT system in Ciao. The 'philosophy' of the current approach is that most details are hidden behind simple read/write primitives and that the handler is exposed to the client for a concrete DHT. By doing things this way we expect to preserve the simplicity of DHT usage while providing the freedom of being able to switch between various instances of the Ciao DHT system

Usage and interface

Documentation on exports

PREDICATE
Connect to the DHT specified by Server (IP address).

Usage: dht_connect(Server,Connection)

  • Description: Perform a straightforward connection from the client-side of a DHT node. The information about DHT node to connect to is supplied as Server. It could equally be a DNS name or an IP address.
  • The following properties should hold at call time:
    (basic_props:atm/1)Server is an atom.
    (term_typing:var/1)Connection is a free variable.
  • The following properties should hold upon exit:
    (basic_props:gnd/1)Server is ground.
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1

PREDICATE
Connect to the DHT specified by Server (IP address).

Usage: dht_connect(Server,Port,Connection)

  • Description: Perform a straightforward connection from the client-side of a DHT node. The information about DHT node to connect to is supplied as combination of Server and Port, if a non standart port is used for server-to-client communication. It could equally be a DNS name or an IP address.
  • The following properties should hold at call time:
    (basic_props:atm/1)Server is an atom.
    (basic_props:int/1)Port is an integer.
    (term_typing:var/1)Connection is a free variable.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Server is an atom.
    (basic_props:int/1)Port is an integer.
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1

PREDICATE
Disconnect from DHT, identified by special supplied connection.

Usage: dht_disconnect(Connection)

  • Description: Issues 'end_of_file' token to the stream supplied as Connection and closes it without delay.
  • The following properties should hold at call time:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1

PREDICATE
Look either for exact predicate or predicate matching the pattern in DHT.

Usage: dht_consult_b(Conn,Key,Value,Resp)

  • Description: dht_consult/4 performs a lookup in the DHT represented by Conn (see dht_connect/2) and searches for Value previously associated with the Key. Value may be partially instantiated in which case matching against the tuples stored in DHT is performed.
  • The following properties should hold at call time:
    (dht_client:dht_connection_type/1)Conn is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:atm/1)Key is an atom.
    (basic_props:term/1)Value is any term.
    (term_typing:var/1)Resp is a free variable.
  • The following properties should hold upon exit:
    (dht_client:dht_connection_type/1)Conn is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:atm/1)Key is an atom.
    (basic_props:term/1)Value is any term.
    (basic_props:gnd/1)Resp is ground.

PREDICATE

Usage: dht_consult_nb(Connection,Key,Value,Response)

  • Description: dht_consult/4 performs a lookup in the DHT represented by Conn (see dht_connect/2) and searches for Value previously associated with the Key. Value may be partially instantiated in which case matching against the tuples stored in DHT is performed.
  • The following properties should hold at call time:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:atm/1)Key is an atom.
    (basic_props:term/1)Value is any term.
    (term_typing:var/1)Response is a free variable.
  • The following properties should hold upon exit:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:atm/1)Key is an atom.
    (basic_props:term/1)Value is any term.
    (basic_props:gnd/1)Response is ground.

PREDICATE
Extract from DHT an exact predicate of type Key(Value) or one that matches given pattern.

Usage: dht_extract_b(Connection,Key,Value,Response)

  • Description: This predicate extracts information from the DHT connected to by Connection, that is stored under key Key if it matches the pattern supplied as Value
  • The following properties should hold at call time:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:atm/1)Key is an atom.
    (basic_props:term/1)Value is any term.
    (term_typing:var/1)Response is a free variable.
  • The following properties should hold upon exit:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:atm/1)Key is an atom.
    (basic_props:term/1)Value is any term.
    (basic_props:gnd/1)Response is ground.

PREDICATE
Extract from DHT an exact predicate of type Key(Value) or one that matches given pattern.

Usage: dht_extract_nb(Connection,Key,Value,Response)

  • Description: This predicate extracts information from the DHT connected to by Connection, that is stored under key Key if it matches the pattern supplied as Value
  • The following properties should hold at call time:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:atm/1)Key is an atom.
    (basic_props:term/1)Value is any term.
    (basic_props:gnd/1)Response is ground.

PREDICATE
Store data to DHT in form of Key(Value) predicate. No free variables are allowed in predicate.

Usage: dht_store(Connection,Key,Value,Response)

  • Description: The value provided in Value is stored under a key given as Key inside the DHT mentioned as Connection
  • The following properties should hold at call time:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:atm/1)Key is an atom.
    (basic_props:term/1)Value is any term.
    (term_typing:var/1)Response is a free variable.
  • The following properties should hold upon exit:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:atm/1)Key is an atom.
    (basic_props:term/1)Value is any term.
    (basic_props:gnd/1)Response is ground.

PREDICATE
Get value of hash function for a given term.

Usage 1: dht_hash(Connection,Value,Hash)

  • Description: Get (in Hash) the hash of Value as determined by the DHT pointed to by Connection. Implemented mostly for testing purposes.
  • The following properties should hold at call time:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:term/1)Value is any term.
    (term_typing:var/1)Hash is a free variable.
  • The following properties should hold upon exit:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:term/1)Value is any term.
    (basic_props:int/1)Hash is an integer.

Usage 2: dht_hash(Connection,Value,Hash)

  • Description: Check whether Hash is equal to the hash of Value as determined by the DHT pointed to by Connection. Implemented mostly for testing purposes.
  • The following properties should hold at call time:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:term/1)Value is any term.
    (basic_props:int/1)Hash is an integer.
  • The following properties should hold upon exit:
    (dht_client:dht_connection_type/1)Connection is a predicate of type dht_connection/2, where first argument is of type atm/1 and second of type streams_basic:stream/1
    (basic_props:term/1)Value is any term.
    (basic_props:int/1)Hash is an integer.