alice
library
manual.

Alice Project

The Remote structure


________ Synopsis ____________________________________________________

    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 ______________________________________________________

    import structure Remote from "x-alice:/lib/distribution/Remote"
    import signature REMOTE from "x-alice:/lib/distribution/REMOTE-sig"

________ Interface ___________________________________________________

    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

________ Description _________________________________________________

type ticket = string

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.

exception Ticket

indicates that a ticket was not well-formed or referred to a site or value that could not be accessed.

exception Proxy of exn

indicates that a call through a proxy has failed. The argument exception describes the specific cause of failure.

exception SitedArgument
exception SitedResult
exception Protocol of string

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.

proxy f

returns a proxy for f. The proxy differs from f in that:

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:

Other causes for raising Proxy are possible.

offer package

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.

take ticket

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.

Offer (signature S = S structure X = X)

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))
Take (val ticket = ticket signature S = 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
Execute (val host = host signature RESULT = S functor Start = F)

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.



last modified 1970/01/01 01:00