3 Basic Operations and Examples

3.1 Global naming

There are two kinds of global names in Oz:

• Internal references, i.e., that can exist only within an Oz computation space. They are globally unique, even for references existing before connecting with another application. All data structures in Oz are addressed through these references; they correspond roughly to pointers and network pointers in mainstream languages, but they are protected from abuse (as in Java). See Section 2.1 for more information on the distribution semantics of these references. In most cases, you can ignore these references since they don't affect the language semantics. In this section we will not talk any more of these references.

• External references, i.e., that can exist anywhere, i.e., both inside and outside of an Oz computation space. They are also known as external global names. They are represented as character strings, and can therefore be stored and communicated on many different media, including Web pages, Oz computation spaces, etc. They are needed when a Mozart application wants to interact with the external world.

This section focuses on external global names. Oz recognizes three kinds, namely tickets, URLs, and hostnames:

• A ticket is a string that references any language entity inside a running application. Tickets are created within a running Oz application and can be used by active applications to connect together (see module Connection).

• A URL is a string that references a file across the network. The string follows the standard URL syntax. In Mozart the file can be a pickle, in which case it can hold any kind of stateless data--procedures, classes, functors, records, strings, and so forth (see module Pickle).

• A hostname is a string that refers to a host (another machine) across the network. The string follows the standard DNS syntax. An application can use the hostname to start up a Mozart process on the host (see module Remote).

For maximum flexibility, all three kinds can be represented as virtual strings inside Oz.

3.1.1 Connecting applications by means of tickets

Let's say Application 1 has a stream that it wants others to access. It can do this by creating a ticket that references the stream. Other applications then just need to know the ticket to get access to the stream. Tickets are implemented by the module Connection, which has the following three operations:

• {Connection.offerOnce X T} creates a ticket T for X, which can be any language entity. The ticket can be taken just once. Attempting to take a ticket more than once will raise an exception.

• {Connection.offerMany X T} creates a ticket T for X, which can be any language entity. The ticket can be taken any number of times.

• {Connection.take T X} creates a reference X when given a valid ticket in T. The X refers to exactly the same language entity as the original reference that was offered when the ticket was created. A ticket can be taken at any site. If taken at a different site than where the ticket was offered, then there is network communication between the two sites.

Application 1 first creates a ticket for the stream as follows:

declare Stream Tkt in 
{Connection.offerMany Stream Tkt}
{Show Tkt}

The ticket is returned in Tkt. Application 1 then publishes the value of Tkt somewhere so that other applications can access it. Our example uses Show to display the ticket in the emulator window. We will use copy and paste to communicate the ticket to another application. The ticket looks something like 'oz-ticket://130.104.228.81:9000/h9323679#42'. Don't worry about exactly what's inside this strange atom. Users don't normally see tickets: they are stored in files or passed across the network, e.g., in mail messages. Application 2 can use the ticket to get a reference to the stream:

declare Stream in 
{Connection.take  
   'oz-ticket://130.104.228.81:9000/h9323679#42' 
   Stream}
{Browse Stream}

If Application 1 binds the stream by doing Stream=a|b|c|_ then Application 2's browse window will show the bindings.

3.1.2 Persistent data structures by means of pickles

An application can save any stateless data structure in a file and load it again from a file. The loading may also be done from a URL, used as a file's global name. The module Pickle implements the saving and loading and the conversion between Oz data and a byte sequence.

For example, let's define a function and save it:

declare 
fun {Fact N}
   if N=<1 then 1 else N*{Fact N-1} end 
end 
 
{Pickle.save Fact "~pvr/public_html/fact"}

Since the function is in a public_html directory, anyone can load it by giving a URL that specifies the file:

declare 
Fact={Pickle.load "http://www.info.ucl.ac.be/~pvr/fact"}
 
{Browse {Fact 10}}

Anything stateless can be saved in a pickle, including functions, procedures, classes, functors, records, and atoms. Stateful entities, such as objects and variables, cannot be pickled.

3.1.3 Remote computations and functors

An application can start a computation on a remote host that uses the resources of that host and that continues to interact with the application. The computation is specified as a functor, which is the standard way to define computations with the resources they need. A functor is a module specification that makes explicit the resources that the module needs (see Section 2.3).

First we create a new Mozart process that is ready to accept new computations:

declare 
R={New Remote.manager init(host:"rainbow.info.ucl.ac.be")}

Let's make the process do some work. We define a functor that does the work when we evaluate it:

declare F M
F=functor export x:X define X={Fact 30} end  
 
M={R apply(F $)}
 
{Browse M.x}

The result X is returned to the client site in the module M, which is calculated on the remote site and returned to the application site. The module is a record and the result is at the field x, namely M.x. The module should not reference any resources. If it does, an exception will be raised in the thread doing the apply.

Any Oz statement S can be executed remotely by creating a functor:

F=functor import ResourceList export Results define S end

To evaluate this functor remotely, the client executes M={R apply(F $)}. The ResourceList must list all the resources used by S. If not all are listed then an exception will be raised in the thread doing the apply. The remote execution will use the resources of the remote site and return a module M that contains all the fields mentioned in Results. If S does not use any resources, then there is a slightly simpler way to do remote computations. The next section shows how by building a simple compute server.

A second solution is to use a functor with an external reference:

declare F M X in 
F=functor define {Fact 30 X} end 
 
M={R apply(F $)}
{Browse X}

This functor is not stateless, but it's all right since we are not pickling the functor. In fact, it's quite possible for functors to have external references. Such functors are called computed functors. They can only be pickled if the external references are to stateless entities.

A third solution is for the functor itself to install the compute server on the remote site. This is a more general solution: it separates the distribution aspect (setting up the remote site to do the right thing) from the particular computations that we want to do. We give this solution later in the tutorial.

3.2 Servers

A server is a long-lived computation that provides a service to clients. We will show progressively how to build different kinds of servers.

3.2.1 The hello server

Let's build a basic server that returns the string "Hello world" to clients. The first step is to create the server. Let's do this and also make the server available through a URL.

% Create server
declare Str Prt Srv in 
{NewPort Str Prt}
thread  
   {ForAll Str proc {$ S} S="Hello world" end}
end 
proc {Srv X}
   {Send Prt X}
end 
 
% Make server available through a URL:
% (by using a filename that is also accessible by URL)
{Pickle.save {Connection.offerMany Srv}  
             "/usr/staff/pvr/public_html/hw"}

All the above must be executed on the server site. Later on we will show how a client can create a server remotely.

Any client that knows the URL can access the server:

declare Srv in 
Srv={Connection.take {Pickle.load "http://www.info.ucl.ac.be/~pvr/hw"}}
 
local X in 
   {Srv X}
   {Browse X}
end

This will show "Hello world" in the browser window.

By taking the connection, the client gets a reference to the server. This conceptually merges the client and server computation spaces into a single computation space. The client and server can then communicate as if they were in the same process. Later on, when the client forgets the server reference, the computation spaces become separate again.

3.2.2 The hello server with stationary objects

The previous section shows how to build a basic server using a port to collect messages. There is in fact a much simpler way, namely by using stationary objects. Here's how to create the server:

declare 
class HelloWorld 
   meth hw(X) X="Hello world" end 
end 
 
Srv={NewStat HelloWorld hw(_)} % Requires an initial method

The client calls the server as {Srv hw(X)}. The class HelloWorld can be replaced by any class. The only difference between this and creating a centralized object is that New is replaced by NewStat. This specifies the distributed semantics of the object independently of the object's class.

3.2.6 A compute server with functors

The solution of the previous section is reasonable when the client and server are independent computations that connect. Let's now see how the client itself can start up a compute server on a remote site. The client first creates a new Mozart process:

declare 
R={New Remote.manager init(host:"rainbow.info.ucl.ac.be")}

Then the client sends a functor to this process that, when evaluated, creates a compute server:

declare F C
F=functor  
  export cs:CS
  define  
     class ComputeServer 
        meth init skip end 
        meth run(P) {P} end 
     end 
     CS={NewStat ComputeServer init}
  end 
 
C={R apply(F $)}.cs  % Set up the compute server

The client can use the compute server as before:

local F in 
   {C run(proc {$} F={Fibo 30} end)}
   {Browse F}
end

3.2.7 A dynamically-extensible server

Sometimes a server has to be upgraded, for example to add extra functionality or to fix a bug. We show how to upgrade a server without stopping it. This cannot be done in Java. In Mozart, the upgrade can even be done interactively. A person sits down at a terminal anywhere in the world, starts up an interactive Mozart session, and upgrades the server while it is running.

Let's first define a generic upgradable server:

declare 
proc {NewUpgradableStat Class Init ?Upg ?Srv}
   Obj={New Class Init}
   C={NewCell Obj}
in 
   Srv={MakeStat  
          proc {$ M} {@C M} end}
   Upg={MakeStat
          proc {$ Class2#Init2} C := {New Class2 Init2} end}
end

This definition must be executed on the server site. It returns a server Srv and a stationary procedure Upg used for upgrading the server. The server is upgradable because it does all object calls indirectly through the cell C.

A client creates an upgradable compute server almost exactly as it creates a fixed compute server, by executing the following on the server site:

declare Srv Upg in 
Srv={NewUpgradableStat ComputeServer init Upg}

Let's now upgrade the compute server while it is running. We first define a new class CComputeServer and then we upgrade the server with an object of the new class:

declare 
class CComputeServer from ComputeServer 
   meth run(P Prio<=medium)
      thread 
         {Thread.setThisPriority Prio}
         ComputeServer,run(P)
      end 
   end 
end 
 
Srv2={Upg CComputeServer#init}

That's all there is to it. The upgraded compute server overrides the run method with a new method that has a default. The new method supports the original call run(P) and adds a new call run(P Prio), where Prio sets the priority of the thread doing computation P.

The compute server can be upgraded indefinitely since garbage collection will remove any unused old compute server code. For example, it would be nice if the client could find out how many active computations there are on the compute server before deciding whether or not to do a computation there. We leave it to the reader to upgrade the server to add a new method that returns the number of active computations at each priority level.