# Aleph Toolkit User's Guide

## Introduction

This document describes how to install and run the Aleph Toolkit, a collection of Javatm packages implementing a simple, platform-independent distributed shared object system. For information about the Toolkit packages themselves, please see the tutorial.

# Installation

The Aleph toolkit encompasses a top-level `aleph` directory, along with the following subdirectories:

`bench` | simple benchmarks
`bin` | Unixtm shell scripts
`comm` | communication managers
`dir` | directory managers
`doc` | javadoc and other documentation
`event` | event managers
`examples` | some simple applications
`gui` | user interface classes
`meter` | metering and instrumentation
`logs` | logging and debugging files
`tools` | create, destroy, and monitor computations
`thread` | thread-related classes
`trans` | transaction managers

## The Aleph Run-Time System

Logically, the Aleph run-time system consists of a collection of Java Virtual Machines called PEs (for Processing Elements). A method executing at one PE can start a thread at another PE, and methods executing at distinct PEs can share data objects, send messages to one another, and synchronize on shared events.

Physically, each PE runs on a machine (usually a workstation), called a host. Multiple PEs can run at a single host. Each host that runs an Aleph Toolkit application must also run the Aleph Server program. The server's job is simply to create new PEs as requested by applications. The server is itself a Java program, which must be started at each host before running any applications.

The user interacts with the Aleph run-time system through a program called the Aleph Console. The Console provides the ability to launch applications, to view their results, and to control system parameters such as host identities.

## Installing Aleph

The easiest way to use Aleph is simply for each user to create a private copy of the Aleph directory tree. Only one file needs to be modified in a site-specific way: `Config.java` in the top-level directory. Each host has its own `Config.java` file, and the values of the entries may well change from host to host (particularly if the hosts run different operating systems). The following entries are the most likely to change from one installation to another.

`int PORT` | This integer, between 1024 and 65535, is the port number for all servers running on behalf of your application. You must choose a port number distinct from that of any other application running at the same time.
`String[] hosts` | An array of host names for hosts that might be running an Aleph Server. When the Aleph console starts up, it queries these hosts to see which ones are running an Aleph server listening on your `PORT` number.
`String pathJava` | This host's path name for the Java interpreter.

The remaining fields all have sensible default values, and can be changed after perusing the documentation.

## Tools

All tools in this section follow the following simple convention. If no host names are specified, the tool applies to servers running at the hosts in `Config.hosts.` If an integer n is specified, the tool applies to the first n hosts in `Config.hosts`. If explicit host names are specified, it applies to them.

### Starting Servers

The simplest way to start an Aleph server is to log in to a host, connect to the desired directory, and explicitly start the server. Assuming your `CLASSPATH` points to the root of your Aleph directory tree, start the server with: `java aleph.comm.Server` Any PEs created by that server will have the same privileges as the server, so if you want your application to access files in your directory, you should start the server from your account.

If you are running on a system of mutually-trusting Unixtm workstations, then the `bin` directory contains a `startServers` shell script that uses `rsh` to start up servers at the indicated hosts in your current working directory. (Make sure that `Config.pathRsh` is set to the correct pathname.)

### Shutting Down Servers

To shut down servers in an orderly way, use

> `java aleph.tools.KillServers`

The `bin` directory also contains a `killServers` shell script. You can also use the Exit & Shut Down Hosts entry in the console's File menu (described below).

### Detecting Servers

To discover where servers are running, use `java aleph.tools.PingServers` The `bin` directory contains a `pingServers` shell script. You can also use the refresh item in the console's Hosts menu (described below).

## The Aleph Console

Once your servers are up and running, you can control your applications using the Aleph console . `java <switches> aleph.Aleph <args>` If you are running a Unix shell, you can use the `aleph` shell script.

The console consists of two text areas and various buttons and menu items. The File menu lets you shut down the console together with all known servers, or shut down the console only. The hosts menu is a tear-off menu that keeps a checkbox for each host in `Config.hosts`. When the server starts up, it queries each of the hosts, and sets the checkbox for each one that appears to be running a server. If you turn the checkbox off, then the console will not use that host (although the server will keep running). Refresh rechecks all the hosts for running servers, and Add allows you to enter a new host where a server is already running. Help shows current settings for System Properties and Aleph Properties.

The upper text field contains the name of your application program (as it would appear as an argument to `java`) together with its arguments. You can start your application by hitting enter, or by the green Start button. The red Stop button will do its best to stop a computation in progress. The Clear button clears all text fields.

The Verbosity switch controls the number of diagnostic messages produced. You can test it at run-time by calling `Aleph.getVerbosity()`. Number PEs controls how many PEs the computation will start. PEs are started at hosts in round-robin order. The Output switch controls where your aplication's output appears. The JIT compiler switch controls the choice of JIT. You can add new JITs to `Config,compilers`.

If the Profiling checkbox is set, each PE will dump profiling information into a file. If Use java_g is set, stack traces will probably display more useful information. If Log console is set, all output text will be logged to a file. Setting any of these checkboxes may slow your computation. All files are created by default in the `logs` subdirectory. The default may be changed using `Config.logDir`.

Aleph rebinds your application's `System.out` and `System.err` streams o display in the lower text field.

The bottom line of choices control the Communication, Directory, Event, and Transaction managers. New managers can be added by changing the `Config` file.

# Batch Operation

Aleph can also be run without a console (particularly useful for shell scripts).

> `aleph -Daleph.batch=true aleph.Aleph <args>`

will immediately start up the specificed application without opening the console. You can use aleph properties to control various options, for example:

> `aleph -Daleph.batch=true -Daleph.numPEs=2 aleph.Aleph <args>`

will start your application at two PEs.

# Documentation

We recommend running javadoc on the source tree. On most Unix shells,

> `make javadoc`

should have the desired effect.