Remote predicate calling utilities

Author(s): Arsen Kostenko.

RPR stands for Remote PRedicate calling. The basic functionality of a remote procedure (or predicate, in Prolog terms of Prolog) call is gathered here. Thus module contains predicates for the execution of remote calls and manipulation routines of the module-specific database.

Documentation on exports

PREDICATE
Sometimes information from remote nodes is received in the form of a node_id/2. In these cases a single argument predicate might be useful.

Usage:dht_rpr_register_node(NodeID)

Save node identity to module-specific DB.

  • The following properties should hold at call time:
    (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.

PREDICATE
General write interface to DB of physical nodes (those that have IP addresses). Information is re-written every time, so no old entries are expected to remain.

Usage:dht_rpr_register_node(Node,NodeIP)

dht_rpr_register_node/2 is responsible for the management of a module-specific database that stores information on node identifiers and IP addresses corresponding to them. Despite there is only one usage mode the behavior may differ depending on the state of module-specific database. For instance, if the database already contains information about a node, whose identifier is equal to the one supplied in Node, a newly supplied entry would be written over the old one. A new entry is added to the module-specific database otherwise.

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

PREDICATE
Just a convenient wrapper around module-specific data structures, which is used in combination with Ciao functional syntax.

Usage 1:dht_rpr_node_by_id(NodeID,Node)

Extract value of node from the node identifier NodeID.

  • The following properties should hold at call time:
    (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.
    (term_typing:var/1)Node is a free variable.
  • The following properties should hold upon exit:
    (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.
    (basic_props:gnd/1)Node is ground.

Usage 2:dht_rpr_node_by_id(NodeID,Node)

Check whether the value of the NodeID node identifier corresponds to the Node value.

  • The following properties should hold at call time:
    (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.
    (basic_props:gnd/1)Node is ground.
  • The following properties should hold upon exit:
    (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.
    (basic_props:gnd/1)Node is ground.

Usage 3:dht_rpr_node_by_id(NodeID,Node)

Return the node identifier associated to the exact node number.

  • The following properties should hold at call time:
    (term_typing:var/1)NodeID is a free variable.
    (basic_props:gnd/1)Node is ground.
  • The following properties should hold upon exit:
    (dht_rpr:dht_rpr_comp_node_addr/1)NodeID is a term of type node_id/2 with first argument as integer and second as free variable or IP/DNS address
    (basic_props:gnd/1)Node is ground.

Usage 4:dht_rpr_node_by_id(NodeID,Node)

This case is merely useless, however perfectly possible.

  • The following properties should hold at call time:
    (term_typing:var/1)NodeID is a free variable.
    (term_typing:var/1)Node is a free variable.

PREDICATE
Convenient wrapper around internal data structures, as well as dht_rpr_node_by_id/2, this predicate is usually used in combination with Ciao functional syntax.

Usage 1:dht_rpr_id_by_node(Node,NodeID)

Get node identity by it's number.

  • The following properties should hold at call time:
    (basic_props:int/1)Node is an integer.
    (term_typing:var/1)NodeID is a free variable.
  • The following properties should hold upon exit:
    (basic_props:int/1)Node is an integer.
    (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.

Usage 2:dht_rpr_id_by_node(Node,NodeID)

Lookup and fill ramaining id field.

  • The following properties should hold at call time:
    (basic_props:int/1)Node is an integer.
    (dht_rpr:dht_rpr_comp_node_id/1)NodeID is a term of type node_id/2 with first argument as free variable or integer and second an IP/DNS address
  • The following properties should hold upon exit:
    (basic_props:int/1)Node is an integer.
    (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.

Usage 3:dht_rpr_id_by_node(Node,NodeID)

Lookup and fill remainting address field.

  • The following properties should hold at call time:
    (basic_props:int/1)Node is an integer.
    (dht_rpr:dht_rpr_comp_node_addr/1)NodeID is a term of type node_id/2 with first argument as integer and second as free variable or IP/DNS address
  • The following properties should hold upon exit:
    (basic_props:int/1)Node is an integer.
    (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.

Usage 4:dht_rpr_id_by_node(Node,NodeID)

Check whether local database really has record about NodeID with Node as its node number.

  • The following properties should hold at call time:
    (basic_props:int/1)Node is an integer.
    (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.

REGTYPE

Usage:dht_rpr_node_id(NodeID)

NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.

    PREDICATE
    Compose identity structure out of arguments provided

    Usage 1:dht_rpr_compose_id(Node,NodeIP,NodeID)

    Compose an internal structure.

    • The following properties should hold at call time:
      (basic_props:int/1)Node is an integer.
      (basic_props:gnd/1)NodeIP is ground.
      (term_typing:var/1)NodeID is a free variable.
    • The following properties should hold upon exit:
      (basic_props:int/1)Node is an integer.
      (basic_props:gnd/1)NodeIP is ground.
      (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.

    Usage 2:dht_rpr_compose_id(Node,NodeIP,NodeID)

    Check whether arguments correspond to structure supplied.

    • The following properties should hold at call time:
      (basic_props:int/1)Node is an integer.
      (basic_props:gnd/1)NodeIP is ground.
      (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.
    • The following properties should hold upon exit:
      (basic_props:int/1)Node is an integer.
      (basic_props:gnd/1)NodeIP is ground.
      (dht_rpr:dht_rpr_node_id/1)NodeID is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.

    PREDICATE
    Write-interface (or more precisely, erase-interface) to DB of physical nodes (those that have IP-address). dht_rpr_clear_node is a dumb-wrapper around retraction operation over module-specific database. As usually, retraction may be performed when the argument is a free variable.

    Usage 1:dht_rpr_clear_by_node(Node)

    Erase any (possibly random) node information.

    • The following properties should hold at call time:
      (dht_rpr:dht_rpr_comp_node_addr/1)Node is a term of type node_id/2 with first argument as integer and second as free variable or IP/DNS address
    • The following properties should hold upon exit:
      (basic_props:gnd/1)Node is ground.

    Usage 2:dht_rpr_clear_by_node(Node)

    Erase exact node.

    • The following properties should hold at call time:
      (dht_rpr:dht_rpr_node_id/1)Node is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.
    • The following properties should hold upon exit:
      (basic_props:gnd/1)Node is ground.

    PREDICATE
    Generic read interface to DB of physical nodes.

    Usage 1:dht_rpr_node(Node)

    Checks for presence of any information on a node supplied as Node.

    • The following properties should hold at call time:
      (dht_rpr:dht_rpr_node_id/1)Node is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.

    Usage 2:dht_rpr_node(Node)

    Get node that matches given template.

    • The following properties should hold at call time:
      (dht_rpr:dht_rpr_comp_node/1)Node is a term of type node_id/2 with first argument is either a free variable or an integer and second is either a free variable or a IP/DNS address

    PREDICATE
    dht_rpr_call/2 execute a goal remotely. The platform for remote execution is specified by HostId. Goal might be a fully instantiated term as well as partially instantiated one (as used in any other goal).

    Usage 1:dht_rpr_call(HostId,Goal)

    Perform remote call of partially instantiated goal: e.g., a pattern search. Remote host for execution is specified via IP/DNS address of node identity, rest of identity is ignored

    • The following properties should hold at call time:
      (dht_rpr:dht_rpr_comp_node_id/1)HostId is a term of type node_id/2 with first argument as free variable or integer and second an IP/DNS address
      (term_typing:var/1)Goal is a free variable.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    • The following properties should hold upon exit:
      (dht_rpr:dht_rpr_comp_node_id/1)HostId is a term of type node_id/2 with first argument as free variable or integer and second an IP/DNS address
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.

    Usage 2:dht_rpr_call(HostId,Goal)

    Perform remote call of partially instantiated goal: e.g., a pattern search. Remote host for execution is specified via integer of node identity, IP/DNS address is searched through local database.

    • The following properties should hold at call time:
      (dht_rpr:dht_rpr_comp_node_addr/1)HostId is a term of type node_id/2 with first argument as integer and second as free variable or IP/DNS address
      (term_typing:var/1)Goal is a free variable.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    • The following properties should hold upon exit:
      (dht_rpr:dht_rpr_comp_node_addr/1)HostId is a term of type node_id/2 with first argument as integer and second as free variable or IP/DNS address
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.

    Usage 3:dht_rpr_call(HostId,Goal)

    Perform remote call of partially instantiated goal: e.g., a pattern search. Remote host for execution is specified via IP/DNS address of node identity, rest of identity is ignored

    • The following properties should hold at call time:
      (dht_rpr:dht_rpr_node_id/1)HostId is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.
      (term_typing:var/1)Goal is a free variable.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    • The following properties should hold upon exit:
      (dht_rpr:dht_rpr_node_id/1)HostId is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.

    Usage 4:dht_rpr_call(HostId,Goal)

    Perform remote call of partially instantiated goal: e.g., a pattern search.Remote host for execution is specified via integer, IP/DNS address is searched through local database using that integer as part of node identity.

    • The following properties should hold at call time:
      (basic_props:int/1)HostId is an integer.
      (term_typing:var/1)Goal is a free variable.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    • The following properties should hold upon exit:
      (basic_props:int/1)HostId is an integer.
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.

    Usage 5:dht_rpr_call(HostId,Goal)

    Perform remote call of partially instantiated goal: e.g., a pattern search. Finally make a try to use first argument as directly-specified IP/DNS address.

    • The following properties should hold at call time:
      (basic_props:atm/1)HostId is an atom.
      (term_typing:var/1)Goal is a free variable.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    • The following properties should hold upon exit:
      (basic_props:atm/1)HostId is an atom.
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.

    Usage 6:dht_rpr_call(HostId,Goal)

    Perform remote call of fully instantiated goal: e.g., a pattern search. Remote host for execution is specified via IP/DNS address of node identity, rest of identity is ignored

    • The following properties should hold at call time:
      (dht_rpr:dht_rpr_comp_node_id/1)HostId is a term of type node_id/2 with first argument as free variable or integer and second an IP/DNS address
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    • The following properties should hold upon exit:
      (dht_rpr:dht_rpr_comp_node_id/1)HostId is a term of type node_id/2 with first argument as free variable or integer and second an IP/DNS address
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.

    Usage 7:dht_rpr_call(HostId,Goal)

    Perform remote call of fully instantiated goal: e.g., a pattern search. Remote host for execution is specified via integer of node identity, IP/DNS address is searched through local database.

    • The following properties should hold at call time:
      (dht_rpr:dht_rpr_comp_node_addr/1)HostId is a term of type node_id/2 with first argument as integer and second as free variable or IP/DNS address
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    • The following properties should hold upon exit:
      (dht_rpr:dht_rpr_comp_node_addr/1)HostId is a term of type node_id/2 with first argument as integer and second as free variable or IP/DNS address
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.

    Usage 8:dht_rpr_call(HostId,Goal)

    Perform remote call of fully instantiated goal: e.g., a pattern search. Remote host for execution is specified via IP/DNS address of node identity, rest of identity is ignored

    • The following properties should hold at call time:
      (dht_rpr:dht_rpr_node_id/1)HostId is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    • The following properties should hold upon exit:
      (dht_rpr:dht_rpr_node_id/1)HostId is a term of type node_id/2 with first argument as integer value and second as IP/DNS address.
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.

    Usage 9:dht_rpr_call(HostId,Goal)

    Perform remote call of fully instantiated goal: e.g., a pattern search.Remote host for execution is specified via integer, IP/DNS address is searched through local database using that integer as part of node identity.

    • The following properties should hold at call time:
      (basic_props:int/1)HostId is an integer.
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    • The following properties should hold upon exit:
      (basic_props:int/1)HostId is an integer.
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.

    Usage 10:dht_rpr_call(HostId,Goal)

    Perform remote call of fully instantiated goal: e.g., a pattern search. Finally make a try to use first argument as directly-specified IP/DNS address.

    • The following properties should hold at call time:
      (basic_props:atm/1)HostId is an atom.
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.
    • The following properties should hold upon exit:
      (basic_props:atm/1)HostId is an atom.
      (basic_props:gnd/1)Goal is ground.
      (basic_props:callable/1)Goal is a term which represents a goal, i.e., an atom or a structure.

    PREDICATE
    The only difference this predicate has with dht_rpr_call/2 is debug-enabling switch. Third parameter is expected to be responsible for that. It takes one of two possible values 'debug' or 'nodebug'. The first one is default. If default value is used, the standard output stream is populated with various debugging information.

    Usage 1:dht_rpr_call(HostId,Goal,Debug)

    dht_rpr_call/3 executes a Goal remotely and prints some debugging information locally. The platform for the remote execution is specified by HostId.Debug variable must be bound to value 'debug' in order for this case to fire.

    • The following properties should hold at call time:
      (basic_props:int/1)HostId is an integer.
      (basic_props:term/1)Goal is any term.
      (basic_props:gnd/1)Debug is ground.

    Usage 2:dht_rpr_call(HostId,Term,Anything)

    dht_rpr_call/3 executes a Goal remotely without writing any information on the local output stream. The platform for the remote execution is specified by HostId.

    • The following properties should hold at call time:
      (basic_props:int/1)HostId is an integer.
      (basic_props:term/1)Term is any term.
      (term_typing:var/1)Anything is a free variable.

    PREDICATE
    node_id/2is an auxilary prediate for internal data structures hanling. The predicate is of type concurrent.