signature REMOTE structure Remote : REMOTE
This structure provides support for the implementation of distributed applications. This includes exporting values from and importing values into sites, performing remote function application and starting a new site. See the distribution overview for an introduction to the distribution facilities provided by Alice.
Communication between sites is performed by cloning data structures. Cloning is defined by pickling.
The current implementation uses HTTP as the transport protocol. Accordingly, tickets are URLs using the http scheme.
See also: COMPONENT_MANAGER, Url, Pickle
import structure Remote from "x-alice:/lib/distribution/Remote" import signature REMOTE from "x-alice:/lib/distribution/REMOTE-sig"
signature REMOTE = sig type ticket = string exception Proxy of exn exception SitedArgument exception SitedResult exception Protocol of string exception Ticket val proxy : ('a -> 'b) -> ('a -> 'b) val offer : package -> ticket val take : ticket -> package functor Offer (signature S structure X : S) : (val ticket : ticket) functor Take (val ticket : ticket signature S) : S functor Execute (val host : string signature RESULT functor Start (ComponentManager : COMPONENT_MANAGER) : RESULT) : RESULT end
The type of tickets representing offered values. Tickets are short strings suitable for communication, for instance, over voice lines or by email. Tickets are suitable for parsing as URLs.
indicates that a ticket was not well-formed or referred to a site or value that could not be accessed.
indicates that a call through a proxy has failed. The argument exception describes the specific cause of failure.
the former two exceptions indicate that the argument or result of a call to a proxy contained a sited value. The third exception indicates an internal protocol error during execution of a proxy call, where the string describes the error condition in text form. These exception are never raised directly, but occurs only as the argument of a Proxy exception.
returns a proxy for f. The proxy differs from f in that:
the argument to the proxy is cloned before f is applied to it; it may not contain sited values;
the result of f (either a value or an exception) is cloned before it is delivered to the caller; it may not contain sited values;
whenever the proxy itself is cloned, only a reference to the running site is cloned which does not contain a clone of f;
when the proxy is applied, no matter on which site, this causes f to be applied on the site on which the proxy was created, if necessary by transferring argument and result between the sites.
The cloning performed when applying proxies implies that any future in the argument value or result is requested. That may raise an exception due to a failed future, which then becomes the result of the call. In either case, this is considered regular execution of the proxy call.
But proxy calls may also fail, for a number of reasons. In each case, the exception Proxy is raised to indicate failed execution of the call, with the actual cause as an argument. The following causes are possible:
The argument to the proxy contains a sited value. In that case, Proxy(SitedArgument) will be raised.
The result of applying f (a value or raised exception) contains a sited value, or it contains a failed future that carries an exception with a sited value or another failed future. In all cases, Proxy(SitedResult) will be raised. (Secondary failed futures are captured to prevent divergence in the case of circular data structures.)
The process in which the proxy was created has terminated. In this case, Proxy(Ticket) will be raised.
A protocol failure occurs in the lower communication layers. In this case, Proxy(Protocol s) will be raised, with s describing the error condition.
An I/O problem occurs in the lower communication layers. In this case, Proxy(Io args) will be raised, with args carrying further information.
Other causes for raising Proxy are possible.
makes package available to other sites for taking. Returns a ticket suitable for take or Take. An offered package can be taken any number of times. If the package contains mutable data, then each take will return a clone of a snapshot of the package made when offer is executed.
imports the data structure denoted by ticket, which must have been created by offer or Offer. Raises Ticket if the ticket is invalid or the site on which it was created no longer exists. Raises IO.Io if retrieving the package fails for other reasons.
makes module X available to other sites for taking with signature S. Returns a ticket suitable for take or Take. Equivalent to
(val ticket = offer (pack X :> S))
imports the module denoted by ticket, which must have been created by offer or Offer, under a sub-signature of S. Raises Ticket if the ticket is invalid or the site on which it was created no longer exists. Raises Package.Mismatch if the module was not exported with a signature matching S. Raises IO.Io if retrieving the module fails for other reasons. Equivalent to
unpack (take ticket) : S
creates a new site on host using ssh, transfers a clone of Start to the new site, on which it is applied to the local component manager. A clone of the resulting structure is transferred back to the caller of Execute and returned as the resulting structure.