☰

Distribution protocol for active modules

Author(s): The Ciao Development Team, Jose F. Morales.

This is the code that handles setting up nodes in a distributed environment, and sending and receiving messages (see mailbox) between active module instances.

The current distribution protocol provide no means for security. The application must take care of this.

This includes:

  • Low-level TCP/IP socket connection between nodes
  • Publishing/locating ActRef names in a registry
  • Sending/receiving messages

A node is an OS process (currently identified by its Hostname:Port). Each node may contain many active module instances. The distributed protocol requires a mapping between the active module instance identifiers and the precise location of the node on the network (its address).

This mapping is maintained by a registry of addresses of active module instances. We allow differerent registry protocols to publish and locate these addresses (see Registry protocols).

The current implementation for communication between active modules is based on TCP/IP sockets (thus, the address of an active module instance is an IP socket address in a particular machine).

Requests to execute goals in a module are sent as messages through the mailbox. When the mailbox corresponds to a remote active module instance, the messages are send over TCP/IP socket connection between the local and remote nodes. Similary, response messages that encode the answers are retrieved through sockets into local mailboxes.

Distributed nodes

When using the dist_node directive, the executable serves as a for distributed active modules. It accepts following command-line options:

-p Port                     Port number for listening connection
-a Address                  Address for listening connection
--reg-protocol RegProtocol  Registry protocol
--reg-addr Address Port     Registry address (optional)
--reg-dir Path              Registry directory (optional)
--name Name                 Publish name for the (default) active module instance

Some of them can be controlled through the following environment variables:

ACTMOD_HOSTNAME        Address for listening connection

Other declarations:

  • :- dist_start(G): specify a default starting goal to be executed once the node is ready to accept connections.
  • :- actmod_reg_protocol(<RegProtocol>): default registry protocol used in the context of the current active module

Registry protocols

The implementation currently uses the experimental traits package (similar to multifile predicates but with better control on the hooks interface).

A registry protocol implements the predicates to publish and locate addresses of active module instances. By convention, the implementation of a registry protocol RP is encoded in a module with name regp_<RP>.

The publish part of the protocol must implement the actmod_publish trait, defining the save_addr/5 predicate. This predicate publishes the current active module address.

The locate part of the protocol must implement the actmod_locate trait, defining the remote_address/3 predicate. This predicate locates the address of the specified active module.

For efficiency, the locate methods maintain a cache of addresses, so that the server information only needs to be read from the file system the first time the active module is accessed.

The available implementations are:


Documentation on exports

PREDICATEdist_init/3

Usage:dist_init(RegProtocol,Mod,Opts)

Initialize a node for distributed active modules (registry protocol RegProtocol, initial module Mod, options Opts).

    PREDICATEdist_init_args/3

    Usage:dist_init_args(RegProtocol,Mod,Args)

    Like dist_init/3 but parses options from command-line arguments Args.

      PREDICATEget_addr_stream/2
      No further documentation available for this predicate.

      PREDICATEdist_send/2
      No further documentation available for this predicate.

      PREDICATEdist_get_reg_protocol/1
      No further documentation available for this predicate.

      PREDICATEdist_set_reg_protocol/1
      No further documentation available for this predicate.

      PREDICATEactI_alloc_named/2
      No further documentation available for this predicate.

      REGTYPEactref/1

      Usage:actref(X)

      Reference to an active module instance

        REGTYPEactchn/1

        Usage:actchn(X)

        Channel for active module instance communication

          PREDICATEchn_actref/2
          No further documentation available for this predicate.

          PREDICATEactchn_send/2
          No further documentation available for this predicate.

          PREDICATEactref_to_actchn/2
          No further documentation available for this predicate.

          PREDICATEactchn_watch_response/2
          No further documentation available for this predicate.

          PREDICATEactchn_unwatch_response/1
          No further documentation available for this predicate.

          PREDICATEterm_to_atom/2
          No further documentation available for this predicate.

          PREDICATEatom_to_term/2
          No further documentation available for this predicate.

          Documentation on multifiles

          PREDICATE$curr_mod/1
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEfnct.decl_at_mod/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEfnct.prop/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$fnct_stub_rename/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$handle_stream/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$current_msg/3
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEgsusp.guard/4
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEgsusp.run/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEasync.ftypes/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEasync.run/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$fiber_susp_hook/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEtransient.decl/1
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEactmod_publish.save_addr/6
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEactmod_locate.remote_address/4
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEactmod_locate.cleanup_actI/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$dist_addr_retry/1
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$dmod_reg_protocol/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$dmod_src/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$dmod_prop/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$local_actmod/1
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$static_named_actRef/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$dmod_proxy/2
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATE$actmod_exe/3
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEqprot.collect/3
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEqprot.dec/4
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEqprot.enc/3
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEqprot.prepare_query/4
          No further documentation available for this predicate. The predicate is multifile.

          PREDICATEqprot.join_answers/7
          No further documentation available for this predicate. The predicate is multifile.

          Documentation on imports

          This module has the following direct dependencies:
          Generated with LPdoc using Ciao