PolyORB User’s Guide: A Complete Example

8.5.4.27 A Complete Example

Almost every keyword and construct defined in the configuration language has been used in the following sample configuration file.


configuration MyConfig is                                          

  Partition_1 : Partition := ();
  procedure Master_Procedure is in Partition_1;                    

  Partition_2, Partition_3 : Partition;

  for Partition_2'Host use "foo.bar.com";                          

  function Best_Node (Partition_Name : String) return String;
  pragma Import (Shell, Best_Node, "best-node");
  for Partition_3'Host use Best_Node;                              

  Partition_4 : Partition := (RCI_B5);                             

  for Partition_1'Directory use "/usr/you/test/bin";             
  for Partition'Directory use "bin";                             

  procedure Another_Main;
  for Partition_3'Main use Another_Main;                           

  for Partition_3'Reconnection use Block_Until_Restart;          
  for Partition_4'Command_Line use "-v";                           
  for Partition_4'Termination use Local_Termination;               

  pragma Starter (Convention => Ada);                                  

  pragma Boot_Server
    (Protocol_Name => "tcp",
     Protocol_Data => "`hostname`:`unused-port`");                 

  pragma Version (False);                                          

begin                                                              
   Partition_2 := (RCI_B2, RCI_B4, Normal);                        
   Partition_3 := (RCI_B3);                                        
end MyConfig;

Line 01 Typically, after having created the following configuration file the user types:
```
po_gnatdist myconfig.cfg
```
If the user wants to build only some partitions then he will list the partitions to build on the po_gnatdist command line as follows:
```
po_gnatdist myconfig.cfg partition_2 partition_3
```
The name of the file prefix must be the same as the name of the configuration unit, in this example myconfig.cfg. The file suffix must be cfg. For a given distributed application the user can have as many different configuration files as desired.
Line 04 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, because a partition has to contain at least one library unit.
po_gnatdist produces an executable with the name of Master_Procedure which will start the various partitions on their host machines in the background. The main partition is launched in foreground. Note that by killing this main procedure the whole distributed application is terminated.
Line 08 Specify the host on which to run partition 2.
Line 12 Use the value returned by 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.
Line 14 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.
Line 16 Specify the directory in which the executable of partition partition_1 will be stored.
Line 17 Specify the directory in which all the partition executables will be stored (except partition_1, see Pragmas and Representation Clauses). Default is the current directory.
Line 20 Specify the partition main subprogram to use in a given partition.
Line 22 Specify a reconnection policy in case of a crash of Partition_3. Any attempt to reconnect to Partition_3 when this partition is dead will be blocked until Partition_3 restarts. By default, any restart is rejected (Reject_On_Restart). Another policy is to raise Communication_Error on any reconnection attempt until Partition_3 has been restarted.
Line 23 Specify additional arguments to pass on the command line when a given partition is launched.
Line 24 Specify a termination mechanism for partition_4. The default is to compute a global distributed termination. When Local_Termination is specified a partition terminates as soon as local termination is detected (standard Ada termination).
Line 26 Specify the kind of startup method the user wants. 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 the user must 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).
Line 30 Specify the use of a particular boot server.
Line 32 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 an RCI library unit than the one 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.
Line 34 The configuration body is optional. The user may have fully described his configuration in the declaration part.
Line 35 Partition 2 contains two RCI packages RCI_B2 and RCI_B4 and a normal package. A normal package is not categorized.
Line 36 Partition 3 contains one RCI package RCI_B3