GLADE user manual

Contents

• Introduction
• How to Use Gnatdist to Configure a Distributed Application
• Gnatdist Command Line Options
• Gnatdist Behind the Scenes
• The Configuration Language
• Remote Shell Notes
• Warnings
• Filtering
• Trace/Replay Debugging
• Restrictions

Introduction

A partition is a set of compilation units which are linked together to produce an executable binary. A distributed program comprises two or more communicating partitions.

The distributed systems annex does not describe how a distributed application should be configured. It is up to the user to define what are the partitions in his program and on which machines they should be executed.

The tool gnatdist and its configuration language have been purposely designed to allow you to partition your program and specify the machines where the individual partitions are to execute on.

gnatdist reads a configuration file (whose syntax is described below) and builds several executables, one for each partition. It also takes care of launching the different partitions (default) and to pass arguments specific to each partition.

How to Use Gnatdist to Configure a Distributed Application

1. Write a non-distributed Ada application. Use the categorization pragmas to specify the packages that can be called remotely. The Shared_Passive categorization pragma is not yet implemented. The Remote_Call_Interface and Remote_Types categorization pragmas are.

2. When this non-distributed application is working, write a configuration file that maps your categorized packages onto partitions. Don't forget to specify the main procedure of your distributed application (see below).

3. Type `gnatdist configuration-file'.

4. Start your distributed application by invoking the start-up shell script or Ada program (depending on the "pragma Starter" option, see below).

Gnatdist Command Line Options

   gnatdist [switches] configuration-file [list-of-partitions]

All configuration files should end with the `.cfg' suffix. There may be several configuration files for the same distributed application, as you may want to use different distributed configurations according to your computing environment.

If a list of partitions is provided on the command line, only these partitions will be build. In the following configuration example, you can type : gnatdist configuration partition_2 partition_3.

Gnatdist Behind the Scenes

1. Each compilation unit in the program is compiled into an object module (as in non distributed applications). This is achieved by calling gnatmake on the sources of the various partitions. This step can be skipped by using the -n option.

2. Stubs are generated and compiled into object modules (a stub is the software that allows a partition running on machine A to communicate with a partition running on machine B). Several timestamp checks are performed to avoid useless recompilation.

3. gnatdist performs a number of consistency checks, for instance it checks that all packages marked as remote call interfaces (RCI, see LRM annex E) are mapped onto partitions. It also checks that an RCI package is mapped onto only one partition.

4. Finally, the executables for each partition in the program are created. The code to launch partitions is embedded in the main partition except if another option has been specified (pragma Starter). In this case, a shell script (or nothing) is generated to start the partitions on the appropriate machines. This is specially useful when one wants to write client / server applications where the number of instances of the partition is unknown.

The Configuration Language

Every keyword and construct defined in the configuration language have been used in the following sample configuration file.

---------------------------
--  File `my_config.cfg' --
---------------------------

--  Typically after having created the following configuration file
--  you would type
--
--      gnatdist my_config.cfg
--
--  If you wish to build only certain partitions then list the partitions
--  to build on the gnatdist command line as follows:
--
--      gnatdist my_config.cfg   partition_2 partition_3

configuration My_Config is
  --  The name of the file prefix must be the same as the name of
  --  the configuration unit, in this example `my_config'. The file
  --  suffix must be `cfg'. For a given distributed application
  --  you can have as many configuration files as you wish.

  Partition_1 : Partition := ();
  procedure Master_Procedure is in Partition_1;
  --  Partition 1 contains no RCI package.
  --  However, it will contain the main procedure of the distributed
  --  application, called `Master_Procedure' in this example. If the
  --  line `procedure Master_Procedure is in Partition_1;' was missing
  --  Partition 1 would be completely empty. This is forbidden, a
  --  partition has to contain at least one library unit.
  --  
  --  gnatdist produces an executable with the name of Master_Procedure
  --  which will starts the various partitions on their host machines
  --  in the background.  The main partition is launched in the foreground.
  --  Note that by killing this main procedure the whole distributed
  --  application is halted. 

  Partition_2, Partition_3 : Partition;

  for Partition_2'Host use "foo.bar.com";
  --  Specify the host on which to run partition 2.

  function Best_Node (Partition_Name : String) return String;
  pragma Import (Shell, Best_Node, "best-node");
  for Partition_3'Host use Best_Node;
  --  Use the value returned by an a program to figure out at execution time
  --  the name of the host on which partition 3 should execute.
  --  For instance, execute the shell script `best-node' which takes
  --  the partition name as parameter and returns a string giving the name of
  --  the machine on which partition_3 should be launched.

  Partition_4 : Partition := (RCI_B5);
  --  Partition 4 contains one RCI package RCI_B5
  --  No host is specified for this partition. The startup script
  --  will ask for it interactively when it is executed.

  for Partition_1'Storage_Dir use "/usr/you/test/bin";
  --  Specify the directory in which the executables in each partition
  --  will be stored.

  for Partition'Storage_Dir use "bin";
  --  Specify the directory in which all the partition executables
  --  will be stored. Default is the current directory.

  procedure Another_Main;
  for Partition_3'Main use Another_Main;
  --  Specify the partition main subprogram to use in a given
  --  partition.

  for Partition_4'Command_Line use "-v";
  --  Specify additional arguments to pass on the command line when a 
  --  given partition is launched.

  pragma Starter (Method => Ada);
  --  Specify the kind of startup method you would like. There are 3
  --  possibilities: Shell, Ada and None. Specifying `Shell' builds a shell
  --  script. All the partitions will be launched from a shell script.
  --  If `Ada' is chosen, then the main Ada procedure itself is used to launch
  --  the various partitions. If method `None' is chosen, then
  --  no launch method is used and you have to start each partition
  --  manually. 
  --
  --  If no starter is given, then an Ada starter will be used.
  --
  --  In this example, Partition_2, Partitions_3 and Partition_4 will be
  --  started from Partition_1 (ie from the Ada procedure Master_Procedure).

  pragma Boot_Server
    (Protocol_Name => "tcp", Protocol_Data => "`hostname`:`unused-port`");
  --  Specify the use of a particular boot server. It is especially
  --  useful when the default port 5555 used by GARLIC is already assigned.

  pragma Version (False);
  --  It is a bounded error to elaborate a partition of a distributed
  --  program that contains a compilation unit that depends on a
  --  different version of the declaration of RCI library unit than
  --  that included in the partition to which the RCI library unit was
  --  assigned. When the pragma Version is set to False, no
  --  consistency check is performed.

  Channel_1 : Channel := (Partition_1, Partition_4);
  Channel_2 : Channel := (Partition_2, Partition_3);
  --  Declare two channels. Other channels between partitions remain unknown.

  for Channel_1'Filter use "ZIP";
  --  Use transparent compression/decompression for the arguments and results
  --  of any remote calls on channel "Channel_1", i.e. between "Partition_1"
  --  and "Partition_4".

  for Channel_2'Filter use "My_Own_Filter";
  --  Use filter "My_Own_Filter" on "Channel_2". This filter must be imple-
  --  mented in a package "System.Garlic.Filters.My_Own_Filter".

  for Partition_3'Filter use "ZIP";
  --  For all data exchanged with "Partition_3", use the filter "ZIP". (I.e.
  --  for both arriving remote calls as well as for calls made by this parti-
  --  tion.) Only for calls on "Channel_2" (i.e. for communication between
  --  "Partition_2" and "Partition_3"), the filter "My_Own_Filter" is used.

  pragma Registration_Filter ("Some_Filter");
  --  "Some_Filter" will be used to exchange a filter's parameters between
  --  two partitions. "Some_Filter" itself must be an algorithm that doesn't
  --  need its own parameters to be filtered again!

  --  On all other channels (i.e., for remote calls between partitions where
  --  no channel was declared), filtering is not used.

begin
  --  The configuration body is optional. You may have fully described your
  --  configuration in the declaration part.

  Partition_2 := (RCI_B2, RCI_B4, Normal);
  --  Partition 2 contains two RCI packages RCI_B2 and RCI_B4
  --  and a normal package. A normal package is not categorized.

  Partition_3 := (RCI_B3);
  --  Partition 3 contains one RCI package RCI_B3

end My_Config;

Remote Shell Notes

remote-machine your-username

1. Open a session on each machine listed in your configuration file.

2. If MAIN_PART is the partition that includes the main procedure and if you want to start MAIN_PART on host MAIN_HOST:
   1. Choose a TCP port number PORT_NUM (gnatdist default is 5555 when using a shell starter, randomly chosen when using an Ada starter).

   2. Then for each partition PART, start manually the corresponding executable on the corresponding host as follows

              % PART [--nolaunch] [--slave] --boot_server tcp://MAIN_HOST:PORT_NUM
      

      The --nolaunch parameter must be included for the main partition, it means that this partition is not in charge of launching others. The --slave parameter must be included for other partitions, meaning that in no case the name server is located on them.

3. If you want to kill the distributed application before it terminates, kill MAIN_PART.

Warnings

Filtering

With GLADE, it is no longer necessary that the application take care of such transformations. Instead, users can write their own data transformations and hook them into GLADE so that they are automatically and transparently applied depending on the configuration of the distributed application.

Configuring filtering

The configuration language not only knows about partitions, it also knows about the connections between them. Such a connection is called a "Channel" and represents a bi-directional link between two partitions. In order to define filtering, one must first declare the channels between the partitions of an application:

       A_Channel : Channel := (Partition_1, Partition_2);

Now that this channel is known, the data transformation that is to be applied on all data sent through it can be defined:

       for A_Channel'Filter use "ZIP";

Some filtering algorithms require that some parameters must be sent to the receiver first to enable it to correctly de-filter the data. If this is the case, it may be necessary to filter these parameters again. For such purposes, it is possible to install a global filter for all partitions, which then will be used to filter the parameters of other filters. This filter is called the "registration filter". It can be set by a pragma:

       pragma Registration_Filter ("Filter_Name");

It may also be useful to specify that a partition use a certain filter for all remote calls, regardless of the channel (i.e., regardless of the partition that'll receive the remote call). This can be specified using the attribute 'Filter on a partition:

      for Partition_1'Filter use "ZIP";

      for Partition'Filter use "ZIP";

     My_Channel : Channel := (Partition_1, Partition_2);

     for My_Channel'Filter  use "ZIP";
     for Partition_1'Filter use "Some_Other_Filter";

Gnatdist takes care of consistency checking of a filter definition. By default, no filtering is done. Filtering is only active if specified explicitly in the configuration file.

Implementing your own Filters

For more information on how to write your own filter packages see the sample implementation of a ZIP filter in files 's-gafizi.ad[bs]' in the distribution. You might also want to look at the example in the 'Filtering' directory of the GLADE distribution.

Trace/Replay Debugging

To get a partition to generate a trace file, it has to be passed the command line argument "--trace". This is most easily done by using the "for Partition'Command_Line use..." construct (described above) in the configuration file to add "--trace" to the command lines of the partitions whose executions are to be replayed. When the application has been built, starting it using the starter, as usual, will then result in the trace files being generated.

By default, the file name of the trace file is the name of the partition's executable (i.e. the string returned by the standard procedure Ada.Command_Line.Command_Name) with a trailing ".trace". This can be changed with the "--trace_file othername" command line argument. Note that since the remote partitions are launched with rsh under Unix, the current directory during execution will be the user's home directory. This is no problem when using the default trace file name, because the executable's name will include the absolute path. When using the "--trace_file" option, on the other hand, if you don't want the trace file to be created/read in the home directory, the absolute path will have to be included in the desired name.

In order to replay a partition whose execution has been previously traced, the command line argument "--replay" is required. In addition, the special boot server location "replay://" has to be specified, i.e. by using the "--boot_server replay://" command line argument.

Example: To replay a traced execution of partition whose executable is named PART, you would start it with the command

        % PART [--nolaunch] [--slave] --replay --boot_server replay://

Since the exact contents of the messages received is recorded, differences in input from external sources (such as standard input) during replay will most likely give unexpected results. Also, replay of applications whose behavior is inherently non-deterministic will be problematic.

N.B. It is important that the same executable is used for replay as when the trace file was generated, otherwise strange behavior can be expected.

Restrictions

Remote access to subprogram have not yet been implemented.

Pragma All_Calls_Remote has not yet been implemented.

Shared passive packages and generic RCI packages are also unimplemented.

Language-defined exceptions propagate well through different partitions.

For the time being, gnatdist is only able to build distributed applications for a pool of homogeneous or heterogeneous machines using TCP/IP as a common network protocol.