Most object-oriented programming languages provide a facility for declaring variables that are shared by all objects of a given class. In C++, these are called “static members” (and use the “static” keyword), and similarly Python has the notion of “class attributes”.

Let’s consider an example where this is useful. For instance, let’s say we want to define the notion of a block of text that is generated by expanding a template (perhaps after we replace some parameters in that template, as can be done with AWS’s templates parser, for instance). Once we have computed those parameters, we might want to generate multiple outputs (for instance HTML and CSV). Only the template needs to change, not the computation of the parameters.

Typically, such as in Python, the template could be implemented as a class attribute of the Text_Block class. We can then create templates that need the same information but have a different output simply by extending that class:

   class Text_Block(object):
       template = "somefile.txt"
       def render (self):
           # ... compute some parameters
           # Then do template expansion
           print "processing %s" % self.__class__.template

   class Html_Block(Text_Block):
       template = "otherfile.html"

In this example, we chose to use a class attribute rather than the usual instance attribute (self.template). This example comes from the implementation of GnatTracker: in the web server we create a new instance of Text_Block for every request we have to serve. For this, we use a registry that maps the URL to the class we need to create. It is thus easier to create a new instance without specifying the template name as a parameter, which would be required if the template name was stored in the instance. Another reason (though not really applicable here) is to save memory, which would be important in cases where there are thousands of instances of the class.

Of course, the approach proposed in this Gem is not the only way to solve the basic problem, but it serves as a nice example of one of the new Ada 2012 features.

C++, like Ada, does not provide a way to override a static class member, so it would use a similar solution as described below.

Since Ada has no notion of an overridable class attribute, we’ll model it using a subprogram instead (the only way to get dispatching in Ada). The important point here is that we want to be able to override the template name in child classes, so we cannot use a simple constant in the package spec or body.

   type Text_Block is tagged null record;
   function Template (Self : Text_Block) return String;
   function Render (Self : Text_Block) return String;

   function Template (Self : Text_Block) return String is
      pragma Unreferenced (Self);
   begin
      return "file_name.txt";
   end Template;

The parameter Self is only used for dispatching (so that children of Text_Block can override this function). Since we prefer to compile with “-gnatwu” to get a warning on unused entities, we indicate to the compiler that it is expected that Self is unreferenced.

We could make the function Template inlinable, which might be useful in a few cases (for instance if called from Render in a nondispatching call), but in general there will be no benefit because Template will be a dispatching call, which requires an indirect call and thus wouldn’t benefit from inlining.

And that’s it. We have the Ada equivalent of a Python class member.

But so far there is nothing new here, and this approach is rather heavy to write. For instance, the body of Render could contain code like:

   pragma Ada95;

   function Render (Self : Text_Block) return String is
      T : constant String := Template (Text_Block'Class (Self));
   begin
      ..  prepare the parameters for template expansion
      ..  substitute in the template and return it
   end Render;

Fortunately, Ada 2012 provides an easier way to write this, using the new feature of expression functions. Since Template is a function that returns a constant, we can declare that directly in the spec, and remove the body altogether. The spec will thus look like:

   pragma Ada_2012;

   type Text_Block is tagged null record;
   function Template (Self : Text_Block) return String
      is ("filename.txt");
   function Render (Self : Text_Block) return String;

This is a much lighter syntax, and much closer to how one would do it in Python (except we use a function instead of a variable to represent a class member). A child of Text_Block would override Template using the same notation:

   type Html_Block is new Text_Block with null record;
   overriding function Template (Self : Text_Block) return String
      is ("otherfile.html");

Compared to Python, this is in fact more powerful, because some of the children could provide a more complex body for Template, so we are not limited to using the value of a simple variable as in Python. In fact, we can do this in the spec itself, by using a conditional expression (another new feature of Ada 2012):

   pragma Ada_2012;

   type Text_Block is tagged null record;
   function Template (Self : Text_Block) return String
       is (if Self.Blah then "filename.html" else "file2.json");
   function Render (Self : Text_Block) return String;

Finally, we can also make the body of Render slightly more familiar (in terms of object-oriented notation) using the dotted notation introduced in Ada 2005:

   function Render (Self : Text_Block) return String is
      T : constant String := Text_Block'Class (Self).Template;
   begin
      ..  prepare the parameters for template expansion
      ..  substitute in the template and return it
   end Render;

Now the call to Template looks closer to how it would appear in those languages that provide overridable class members. Some will argue that this doesn’t look like a function call and thus is less readable, since we don’t know that we are calling a function. This is a matter of taste, but at least we have the choice.

There is one thing we have lost, temporarily, in the declaration of Template. If we compile with -gnatwu, the compiler will complain that Self is unreferenced. There is currently no way to add a pragma Unreferenced within an expression function. This has generated a discussion here at AdaCore and the issue is not resolved yet. The current two proposals are either to always omit the unused parameter warning when a function has a single parameter and it controls dispatching (precisely to facilitate this class member pattern), or else to use an Ada 2012 aspect for this, as in the following:

   function Template (Self : Text_Block) return String
      is ("filename.html")
   with Unreferenced => Self;

Note also that the use of expression functions in this Gem requires a very recent version of GNAT: the expression function feature wasn’t available in older versions, and the initial implementation had some limitations.

So we’ve decided to have some fun and are building an application that combines Ada and C++. So far, so good. We used the C++ to Ada binding generator to bind the C++ classes directly to Ada, and extend them. However, there’s something that needs to be considered carefully –- what would happen if an exception were thrown/raised by C++ vs. Ada code? Let’s try it out:

Step 1 — The C++ code

We’re going to write some very simple C++ code, just two classes, one inheriting from the other, and overriding a “compute” primitive:

class COperation {
  public:
  virtual int compute (int a, int b);
  COperation ();
};

class CDivision : public COperation {
  public:
  virtual int compute (int a, int b);
  CDivision ();
};

int CDivision::compute (int a, int b) {
  if (b == 0) {
    throw new Problem ("Division by 0 in C++!");
  } else {
    return a / b;
  }
}

In the computation of CDivision, we’ll raise a C++ exception if a divide-by-zero occurs. Let’s add a second subprogram doing a dynamic dispatch:

void cpp_main (COperation & op) {
  try {
     cout << op.compute (1, 0);
  } catch (...) {
    cout << "Unknown exception caught, rethrowing..." << "\n";
    throw;
  }
}

This function calls the compute operation, catches the exception to display a message, and then rethrows it.

We’re now going to bind this to Ada. Assuming all specifications are in a file base.hh, a simple call to gcc will do it:

g++ -fdump-ada-spec base.hh

Step 2 — Extending the C++ code in Ada

There is an implementation of CDivision in C++. After the binding phase, let’s implement the same code in Ada:

type Ada_Division is new base_hh.Class_COperation.COperation with
     null record;

function Compute
  (this : access Ada_Division;
   a : int;
   b : int) return int is
begin
   if b = 0 then
      raise Constraint_Error with "Division by 0 in Ada!";
   end if;
   return a / b;
end Compute;

We now have three classes in the application. One root C++ class, one pure C++ child, and one mixed Ada/C++ child. Let’s see how things how things work from there.

Step 3 — Catching a C++ exception in Ada

C++ exceptions do not have a known name once they reach the Ada world. They act just as if they were declared in the body of a package, so the only way to catch them is to use a general exception handler. Consider the following code:

   T_Cpp : aliased base_hh.Class_CDivision.CDivision;
   X : Interfaces.C.Int;
begin 
   X :=  T_Cpp.compute (1, 0);
exception
   when others =>
      Put_Line ("[1] Exception caught...");
end;

This will print “[1] Exception caught…” on the screen.

Step 4 — Handling exceptions across languages

Now let’s be a little bit more ambitious. We’re going to call the cpp_main function with an object coming from Ada:

   T_Ada : aliased Base_Ada.Ada_Division;
begin
   base_hh.cpp_main (T_Ada'Access);
exception
   when Constraint_Error =>
      Put_Line ("[2] Constraint_Error caught...");
   when others =>
      Put_Line ("[2] Exception caught...");
end;

Now, looking back at the cpp_main implementation, we call compute with (1, 0) as the arguments. This will trigger an exception from the Ada implementation, which is going to be caught first by the C++ code, printing “Unknown exception caught, rethrowing…” on the screen. The same exception is then rethrown by the C++ side, ending up back in the Ada code above, printing “[2] Constraint_Error caught…”.

The Mindstorms NXT “brick” contains both a 32-bit ARM processor and an 8-bit AVR processor. The ARM executes the application code, while the AVR is responsible for the lower-level device functionality, including controlling outputs, gathering sensor inputs, and even shutting down the brick itself.

The two processors coordinate by sending an unending stream of messages to each other. Upon initialization, the AVR begins sending messages containing information such as the current buttons pressed, if any, and the battery status, among other data. The ARM sends messages back to the AVR, for example to set power levels on outputs for motors or to command an analog-to-digital conversion to take place. The messages go back and forth continually at a fixed rate. In other words, they are not event-driven, although their content certainly reflects external events and internally generated commands. Look in the “drivers” directory for the package body of NXT.AVR if you want to see how these messages are sent and received. The one task declared in the entire API is located in that package body for that purpose.

The timing constraints on message handling are fixed by the hardware and are very strict. It is therefore possible for messages to be lost or garbled occasionally. A checksum is calculated to detect these errors, resulting in the problematic message being discarded.

The Ada API hides all these details behind high-level abstract data types for the sensors and motors, and procedural interfaces for the other lower-level facilities such as the A/D converter and discrete I/O capabilities of the ports. Nonetheless, application code must be written with some of the above architecture in mind. Specifically, incoming data are not available until the AVR has been initialized and has sent at least one message to the ARM. Although the AVR is initialized automatically by the Ada drivers, the application programmer must still await receipt of that message. For example, the current voltage of the battery is stored in a variable declared in the NXT.AVR package. The value of that variable is dependent upon arrival of a message from the AVR and is undefined beforehand. The accessor functions that decode the voltage representation simply process the variable as if the value is already defined. (There are ways to mitigate use of the undefined value, of course, but none are ideal.) Other values, such as the raw button readings, are also stored as variables that are set by the decoded AVR messages.

Therefore, the NXT.AVR package provides a procedure that awaits AVR initialization and initial message receipt. That procedure is named Await_Data_Available. A call to this procedure should typically be the first thing done by the application.

Another procedure is provided to power down the brick for those applications that are intended to complete (unlike, say, embedded control systems that only stop when external power is removed). This is procedure Power_Down, also found in the NXT.AVR package declaration. The AVR is responsible for actually shutting down the power, so the procedure injects an appropriate message to the AVR into the message stream. However, as mentioned, messages can be lost or garbled, so the power-down request can be lost. As a result, it is best to use an infinite loop that calls Power_Down repeatedly. In effect, the loop “exits” when the AVR disconnects power to the brick. For example:

   loop
      NXT.AVR.Power_Down;
      delay until Clock + Seconds (1);
   end loop;

The absolute delay statement emulates a relative delay (as the Ravenscar subset doesn’t include relative delays) by calling the Ada.Real_Time.Clock function and adding an interval to it. The duration of the interval is arbitrary and need not be one second.

Note that the NXT.AVR package also detects the situation in which the Power button on the brick is held down for an interval, and will shut down the brick automatically in response.

In summary, although the API goes to some lengths to hide the gory details of the ARM/AVR interactions, ramifications of the message-based architecture remain visible.

In the next Gem in this series we will explore the high-level abstract data types representing the sensors and motors.

When we write applications, we often add Put_Line statements to help debug the initial version of the code. Once that code works, we remove the Put_Line and move on to some other feature of the code. The problem is that when a bug occurs again in that part of the code (and especially when this is reported by a user and you can’t debug on his machine), the output would still be useful, but it’s no longer present in the executable.

The solution, of course, is to output the traces to some “log” file, and keep the traces forever in the code. The log file will eventually become very large if you have lots of traces, and finding information there might not be so easy. So, a better solution is to split the traces into various groups, and have a capability to display only some of the groups, so as to limit the amount of information to look at.

The GNAT Components Collection includes a package GNATCOLL.Traces that provides support for this. This package is used in various AdaCore products, in particular GPS.

The first thing to do is to initialize the module. The traces are configured via an external file, which by default is called “.gnatdebug”, and is searched for in the current directory.

   with GNATCOLL.Traces;   use GNATCOLL.Traces;
   with User;
   procedure Main is
   begin
      Parse_Config_File;   --  parses default ./.gnatdebug
      User.Proc;
   end Main;

The simplest way to compile this code is to use a project file. For instance:

with "gnatcoll";
project Default is
    for Main use ("main.adb");
end Default;

gprbuild -Pdefault.gpr

In the rest of the code we can create a stream. All log messages are sent to a stream, and you are free to create as many as you want. A log message will always be prefixed by the name of its stream, as a way to organize traces in the log file. Here is what the Ada code would look like:

package User is
   Stream1 : constant Trace_Handle := Create ("Stream1");

   procedure Proc is
   begin
      Trace (Stream1, "Some trace");
   end Proc;
end User;

If you compile this code and run it, there will in fact be nothing logged. That’s because the trace streams are disabled by default. We thus need to create a configuration file. Its format is very simple. The following example demonstrates a number of its features:

+
> log
TRACE1=yes
TRACE2=no
TRACE3=yes > log2
DEBUG.COLORS=yes

The first line (“+”) indicates that we would like to activate all the streams by default. So a file with only that line would already show the output in our Ada example.

The second line (“>log”) indicates where the output of the streams should go by default. If this isn’t specified, the output goes to stdout. Otherwise, you can specify a file name. Advanced usage allow you to define other types of redirection. For instance, GNATCOLL comes by default with support for redirecting to syslog on Unix systems. It would be relatively simple to add support for custom outputs, like a socket, a database, etc.

The next three lines configure specific streams and show how to activate or disable them. The fifth line, in particular, redirects one of the streams to another log file.

The last line in the example activates one of the extra features of GNATCOLL.Traces. Activating “DEBUG.COLORS” will output the stream using different colors for the various information that is output on each line.

Other facilities are available. For instance, if you activate “DEBUG.ABSOLUTE_TIME”, each line in the log file will include the time of the message. More powerfully, you can activate “DEBUG.STACK_TRACE” to get a stack trace for each message (note that the trace needs to be converted via addr2line). Another useful one is “DEBUG.COUNT”, which will add the number of messages output so far in total and for the specific stream.

Here is what the log file will look like:

[STREAM1] 1/1 Some Trace (09:05:32.323)
[STREAM4] 1/2 Some Other Trace (09:05:33.125)

As we have seen in the example, text is output using the Trace function. There are two versions of it: the one we saw that is used to output a simple message, and another version that takes an exception occurrence as a parameter and outputs information about that exception. There is also a procedure called Assert that will output an error message if a Condition is False. The error will be displayed in red if the colors were activated, thus making it easy to locate in the log file.

Preparing the text for a message might be expensive (for instance, if the text should contain the result of a function call, or requires a lot of string concatenation). For this, the recommended coding pattern is:

   if Active (Stream1) then
      Trace (Stream1, "Function result was " & Func(...));
   end if;

The log file might still be hard to read when it gets big. GNATCOLL.Traces provides a facility for indenting the traces. Here is a full example of code computing Fibonacci numbers recursively:

pragma Ada_05;
with Ada.Text_IO;       use Ada.Text_IO;
with GNATCOLL.Traces;   use GNATCOLL.Traces;

procedure Fibo is
   Me : constant Trace_Handle := Create ("FIBO");

   function Recurse (Num : Positive) return Positive is
      Result : Integer;
   begin
      if Num = 1 or else Num = 2 then
         return 1;
      end if;

      Increase_Indent (Me, "Computing" & Num'Img);
      Result := Recurse (Num - 1) + Recurse (Num - 2);
      Decrease_Indent (Me, "Done =>" & Result'Img);
      return Result;
   end Recurse;

begin
   Parse_Config_File;
   Put_Line (Recurse (5)'Img);
end Fibo;

The code should be compiled with a project file, as shown earlier. The current directory should also contain a file called “.gnatdebug” with a single line that contains “+”. The output on stdout is:

[FIBO] 1/1 Computing 5
   [FIBO] 2/2 Computing 4
      [FIBO] 3/3 Computing 3
      [FIBO] 4/4 Done => 2
   [FIBO] 5/5 Done => 3
   [FIBO] 6/6 Computing 3
   [FIBO] 7/7 Done => 2
[FIBO] 8/8 Done => 5
 5

which shows the indentation that is increased for each recursive call.

GNATCOLL.Traces uses object-oriented code. It provides a number of hooks through which you can add your own extra data each time some line is output to the log file. For this, you should override the Pre_Decorator or Post_Decorator primitive operations.

Imagine that you have a UML model and you want to generate code from it. A convenient approach is to have a “code generator” object, which has a set of subprograms to handle each kind of UML element (one that generates code for a class, one that generates code for an operation, etc.).

One way to implement this is by using a big series of if statements, of the form if Obj in CClass’Class then, which is rather inelegant and inefficient.

Another approach is to use discriminated types. A case statement on the discriminant is then efficient, and Ada will check that all discriminant values are covered. The problem is that then you would need to use case statements for all clients of the types in your application. Here, we prefer to use tagged types, to take advantage of Ada’s OOP capabilities, so the case statement cannot be used.

Let’s consider a specific example. Again, taking the UML example, assume we have the following types. These are only very roughly similar to the actual UML metamodel, but will be sufficient for our purposes. In practice, these types would be automatically generated from the description of the UML metamodel.

   type NamedElement is tagged private;
   type CClass is new NamedElement with private;
   type PPackage is new NamedElement with private;

In addition, a visitor class is declared, which will be overridden by the user code, for instance, to provide a code generator, a model checker, and so on:

   type Visitor is abstract tagged null record;

   procedure Visit_NamedElement
      (Self : in out Visitor; Obj : NamedElement'Class) is null;
   --  No parent type, do nothing

   procedure Visit_CClass (Self : in out Visitor; Obj : CClass'Class) is
   begin
      --  In UML, a "Class" inherits from a "NamedElement".
      --  Concrete implementations of the visitor might want to work at the
      --  "NamedElement" level (so that their code applies to both a Class
      --  and a Package, for instance), rather than duplicate the work for each
      --  child of NamedElement. The default implementation here is to call the
      --  parent type's operation.
   
      Self.Visit_NamedElement (Obj);
   end Visit_Class;

   procedure Visit_PPackage (Self : in out Visitor; Obj : PPackage'Class) is
   begin
      Self.Visit_NamedElement (Obj);
   end Visit_PPackage;

We then need to add one primitive Visit operation to each of the types created from the UML metamodel:

   procedure Visit (Self : NamedElement; V : in out Visitor'Class) is
   begin
      --  First dispatching was on "Self" (done by the compiler).
      --  Second dispatching is simulated here by calling the right
      --  primitive operation of V.

      V.Visit_NamedElement (Self);
   end Visit;

   overriding procedure Visit (Self : CClass; V : in out Visitor'Class) is
   begin
      V.Visit_CClass (Self);
   end Visit;

   overriding procedure Visit (Self : PPackage; V : in out Visitor'Class) is
   begin
      V.Visit_PPackage (Self);
   end Visit;

All of the code described above is completely systematic, and as such could and should be generated automatically as much as possible. The “Visit” primitive operations should never be overridden in user code in the usual case. On the other hand, the “Visit_…” primitives of the visitor itself should be overridden when it makes sense. The default implementation is provided just so the user has the choice at which level do to the overriding.

Now let’s see what a code generator would look like. We’ll assume that we are only interested, initially, in doing code generation for classes. Other types of elements (such as operations) will call the default implementation for their visitor (Visit_Operation, for instance), which then calls the visitor for its parent (Visit_NamedElement) and so on, until we end up calling a Visit operation with a null body. So nothing happens for those, and we don’t need to deal with them explicitly.

The code would be something like the following:

   type CodeGen is new Visitor with private;

   overriding procedure Visit_CClass
      (Self : in out Codegen; Obj : CClass'Class) is
   begin
       ...;  --  Do some code generation
   end Visit_CClass;

   procedure Main is
      Gen : CodeGen;
   begin
      for Element in All_Model_Elements loop  --  Pseudo code
          Element.Visit (Gen);   --  Double dispatching
      end loop;
   end Main;

If we wanted to do model checking, we would create a type Model_Checker, derived from Visitor, that overrides some of the Visit_* operations. The body of Main would not change, except for the type of Gen.

When using this in practice, there are a few issues to resolve. For instance, the UML types need access to the Visitor type (because it appears as a parameter in their operations). But a visitor also needs to see the UML types for the same reason. One possibility is to put all the types in the same package. Another is to use “limited with” to give visibility on access types, and then pass an access to Visitor’Class as a parameter to Visit.

Here is a full example. This example must be compiled with the “-gnat05″ switch since it uses Ada 2005 features such as the limited with clause and prefixed call notation.

with UML;         use UML;
with Visitors;    use Visitors;
with Ada.Text_IO; use Ada.Text_IO;

procedure Main is
   type Code_Generator is new Visitor with null record;

   overriding procedure Visit_CClass
      (Self : in out Code_Generator; Obj : in out CClass'Class) is
   begin
      Put_Line ("Visiting CClass");
   end Visit_CClass;

   Tmp1 : NamedElement;
   Tmp2 : CClass;
   Tmp3 : PPackage;

   Gen  : aliased Code_Generator;

begin
   Tmp1.Visit (Gen'Access);  --  No output
   Tmp2.Visit (Gen'Access);  --  Outputs "Visiting CClass"
   Tmp3.Visit (Gen'Access);  --  No output
end Main;


limited with Visitors;
package UML is
   type NamedElement is tagged null record;
   procedure Visit
      (Self        : in out NamedElement;
       The_Visitor : access Visitors.Visitor'Class);

   type CClass is new NamedElement with null record;
   overriding procedure Visit
      (Self        : in out CClass;
       The_Visitor : access Visitors.Visitor'Class);

   type PPackage is new NamedElement with null record;
   overriding procedure Visit
      (Self        : in out PPackage;
       The_Visitor : access Visitors.Visitor'Class);
end UML;


with Visitors;  use Visitors;
package body UML is

   procedure Visit
      (Self        : in out NamedElement;
       The_Visitor : access Visitors.Visitor'Class) is
   begin
      The_Visitor.Visit_NamedElement (Self);
   end Visit;

   overriding procedure Visit
      (Self        : in out CClass;
       The_Visitor : access Visitors.Visitor'Class) is
   begin
      The_Visitor.Visit_CClass (Self);
   end Visit;

   overriding procedure Visit
      (Self        : in out PPackage;
       The_Visitor : access Visitors.Visitor'Class) is
   begin
      The_Visitor.Visit_PPackage (Self);
   end Visit;

end UML;


with UML;  use UML;

package Visitors is
   type Visitor is abstract tagged null record;

   procedure Visit_NamedElement
      (Self : in out Visitor; Obj : in out NamedElement'Class);
   procedure Visit_CClass
      (Self : in out Visitor; Obj : in out CClass'Class);
   procedure Visit_PPackage
      (Self : in out Visitor; Obj : in out PPackage'Class);

end Visitors;


package body Visitors is

   procedure Visit_NamedElement
      (Self : in out Visitor; Obj : in out NamedElement'Class) is
   begin
      null;
   end Visit_NamedElement;

   procedure Visit_CClass
      (Self : in out Visitor; Obj : in out CClass'Class) is
   begin
      Self.Visit_NamedElement (Obj);
   end Visit_CClass;

   procedure Visit_PPackage
      (Self : in out Visitor; Obj : in out PPackage'Class) is
   begin
      Self.Visit_NamedElement (Obj);
   end Visit_PPackage;

end Visitors;

The Lego Mindstorms processor has limited storage available, certainly not enough for a nontrivial application and a complete run-time library. Therefore, the GNAT tool-chain does not implement the full Ada language for this platform. A considerable number of language capabilities are still included, especially the Ravenscar tasking profile, but the entire language is not available.

For example, full exception semantics are not implemented. Programmers may raise user-defined and language-defined exceptions, and may handle them locally, but unhandled (and reraised) exceptions do not propagate dynamically up the call chain as they do in full Ada. Instead, an unhandled exception results in a call to a single global routine referred to as the “last chance handler,” so called because it does not return to the application. Developers may define application-specific last chance handler replacements for the default implementation.

The default implementation shipped with this compiler simply shuts down the Mindstorms processor. However, the Ada interfaces define an alternative that displays the file name and line number corresponding to the location of the exception, using the LCD on the Mindstorms “brick.” The routine also briefly buzzes the speaker to get the user’s attention. It then goes into an infinite loop so that the user can note the location of the exception. This implementation is declared in the NXT.Last_Chance package, shown below.

with System;
package NXT.Last_Chance is

   procedure Last_Chance_Handler
     (Source_Location : System.Address;
      Line            : Integer);
   pragma Export (C, Last_Chance_Handler, "__gnat_last_chance_handler");

end NXT.Last_Chance;

Note the pragma exporting the name as “__gnat_last_chance_handler”, the routine name invoked by the run-time library when an unhandled exception is raised. Applications do not call this routine themselves, since it does not return to the caller and shuts down the system. Instead, they override the symbol and have the linker include their version of the routine in the executable so that the run-time library can call it if necessary. In the case of the Mindstorms interfaces, the user specifies the package NXT.Last_Chance in a with-clause, typically in the main program.

with NXT.Last_Chance;
...
procedure ...

You can see the source for the body of the procedure, indeed the sources for all the interfaces, in the “drivers” directory under your installation root. By default this would be:

C:\GNAT\2011\lib\mindstorms-nxt\drivers

Although not a very large or complicated procedure, in such a memory-constrained environment every byte may be precious, so you should take the size of the code into account. The procedure uses the audio interface to buzz the speaker, for example, and the LCD display package is also pulled in. If you were not otherwise using those packages (and their dependents), this could make a difference. However, there is no requirement for you to use this version of the last chance handler, so you can simply comment out or remove the with-clause if you don’t want the fancier handler and associated code included.

In the first installment in this series of DSA Gems, we used an application managing a public bulletin board as a good example of a client-server design. We used the following configuration:

configuration Dist_App is
   pragma Starter (None);
   -- User starts each partition manually

   ServerP : Partition := (Bulletin_Board);
   --  RCI package Bulletin_Board is on partition ServerP

   ClientP : Partition := ();
   --  Partition ClientP has no RCI packages

   for ClientP'Termination use Local_Termination;
   --  No global termination

   procedure Display_Messages is in ServerP;
   --  Main subprogram of master partition

   procedure Post_Message;
   for ClientP'Main use Post_Message;
   --  Main subprogram of slave partition
end Dist_App;

and we obtained two executables, one for each partition (serverp and clientp), by issuing the following command:

po_gnatdist dist_app

With the above po_gnatdist configuration, running the application requires three steps:

• Start po_cos_naming, the PolyORB name server. On startup, an object reference is displayed, which must be passed to all partitions in the environment variable POLYORB_DSA_NAME_SERVICE or through a PolyORB configuration file.
• Start serverp, the server partition, which will register its RCI package (Bulletin_Board) with the name server.
• Start clientp, the client partition, which will query the name server for the location of the RCI.

Simplifying the process

To make this whole process easier, you can instead direct po_gnatdist to embed the name server within the main partition (serverp). This is achieved by saying:

   pragma Name_Server (Embedded);

in the configuration file.

You can then start serverp without an external name server: it is now included within the partition. You still need to convey the location of the name server to clients. From within the server partition, this information can be retrieved by querying the PolyORB run-time parameters:

   Put_Line ("ServerP started, embedded name server is at:");
   Put_Line (PolyORB.Parameters.Get_Conf ("dsa", "name_service", ""));

This outputs a string of the form:

IOR:<…long series of hex digits>

which encodes all required information. You can then start the client partition by specifying this value in the POLYORB_DSA_NAME_SERVICE environment variable. In Bourne shell syntax, this translates to:

POLYORB_DSA_NAME_SERVICE=IOR:<…> ./clientp

Using the Windows cmd shell, this would be:

set POLYORB_DSA_NAME_SERVICE=IOR:<…>
client

Passing the name server information in a file

POLYORB_DSA_NAME_SERVICE can also indicate a file name, prefixed with the string “file:”. So, if you modify serverp to output the name service reference to a file “ns.txt”, you can start the client using

POLYORB_NAME_SERVICE=file:ns.txt ./clientp

Using a well-known port

Note: this requires the latest development version of PolyORB.

It is sometimes inconvenient to have to transport a string value or a file from the server to the client, and to have to update it each time the server is restarted. Using appropriate PolyORB run-time configuration directives, you can force the server to listen for network connections at a fixed location.

The following configuration forces the server to listen on port 8889:

[iiop]
polyorb.protocols.iiop.default_port=8889

Once this is set for the server, you can direct the client to that location by setting POLYORB_DSA_NAME_SERVICE to:

corbaloc:iiop:1.2@<hostname>:8889/_NameService

The included start_server and start_client scripts provide a demonstration of this facility.

In the first part of this two-part series we saw that stand-alone shared libraries have the required properties to be used as dynamic plug-ins. In this Gem we explore how to load and unload code dynamically within an Ada application. In essence, the dynamically loaded code is compiled into a shared library, and when this shared library is modified it is reloaded automatically.

To accomplish this we need three modules:

• Registry — A module handles plug-in loading, unloading, and service registration
• Computer — A plug-in doing a simple computation using two integers and returning the result
• Main — The main application that uses the computer plug-in

Registry

Each plug-in will inherit from a common type named Any. The associated access type Ref is used to record all loaded plug-ins in a hashed map:

package Plugins is   
   type Any is abstract tagged null record;
   type Ref is access all Any'Class;
   --  A reference to any loaded plug-in
end Plugins;

Our Computer plug-in is described by:

package Plugins.Computer is
   
   Service_Name : constant String := "COMPUTER";
   --  Name of the service provided by this plug-in

   type Handle is abstract new Any with null record;
   type Ref is access all Handle'Class;
   
   function Call
     (H : not null access Handle; A, B : Integer) return Integer is abstract;   

end Plugins.Computer;

Note that this is only an abstract view that is shared by all the modules. This view describes all the routines supported by the plug-in. A concrete implementation of the computer plug-in will be given in the computer module.

The Registry spec is:

with Plugins;
package Registry is
   
   procedure Discover_Plugins;
   
   procedure Register
     (Service_Name : String; Handle : not null access Plugins.Any'Class);
   
   procedure Unregister (Service_Name : String);
   
   function Get (Service_Name : String) return access Plugins.Any'Class;
   
end Registry;

The Register, Unregister, and Get routines are trivial. The reference to the plug-in service is recorded in a hashed map by Register, removed by Unregister, and retrieved by Get. This part does not need further discussion.

The Discover_Plugins routine is the tricky one. Here is how it works. This routine scans the plug-ins directory for shared libraries prefixed by “libplugin_”. If such a name is found, it is renamed by removing the “plugin” substring and loaded by the dynamic linker (see Shared_Lib.Load routine in the registry sources of the Gem’s zip file). When the shared library is loaded, the elaboration code is used to register itself (that is, register the service name associated with the object reference) in the registry.

At this point the service is available and can be used by the main application.

Note that a map with all loaded shared libraries is kept. If a shared library is found to be loaded already, it is unloaded first. This calls the finalization code, which is used by the plug-in to unregister itself.

   procedure Discover_Plugins is
      
      function Plugin_Name (Name : String) return String is
         K : Integer := Strings.Fixed.Index (Name, "plugin_");
      begin
         return Name (Name'First .. K - 1) & Name (K + 7 .. Name'Last);
      end Plugin_Name;
      
      use Directories;
      use type Calendar.Time;
      
      S          : Search_Type;
      D          : Directory_Entry_Type;
      Only_Files : constant Filter_Type :=
                     (Ordinary_File => True, others => False);
      Any_Plugin : constant String :=
                     "libplugin_*." & Shared_Lib.File_Extension;
   begin
      Start_Search (S, "plugins/", Any_Plugin, Only_Files);

      while More_Entries (S) loop
         Get_Next_Entry (S, D);
         
         declare
            P     : Shared_Lib.Handle;
            Name  : constant String := Simple_Name (D);
            Fname : constant String := Full_Name (D);
            Pname : constant String := Plugin_Name (Fname);
         begin
            --  Proceed if plug-in file is older than 5 seconds (we do not want to try
            --  loading a plug-in not yet fully compiled/linked).

            if Modification_Time (D) < Calendar.Clock - 5.0 then
               Text_IO.Put_Line ("Plug-in " & Name);

               if Loaded_Plugins.Contains (Pname) then
                  Text_IO.Put_Line ("... already loaded, unload now");
                  P := Loaded_Plugins.Element (Pname);
                  Shared_Lib.Unload (P);
               end if;

               --  Rename plug-in (first removing any existing plug-in)

               if Exists (Pname) then
                  Delete_File (Pname);
               end if;

               Rename (Fname, Pname);

               --  Load it

               P := Shared_Lib.Load (Pname);
               Loaded_Plugins.Include (Pname, P);
            end if;
         end;
      end loop;
   end Discover_Plugins;

The Shared_Lib spec comes with two bodies, one for Windows and one for GNU/Linux. The proper body is selected automatically.

Note that the renaming of the plug-in is required on Windows, as it is not possible to write to a shared library which is in use.

Computer

Here is the specification of the Computer module that is an implementation of the abstract type described above:

with Plugins.Computer;
package Computer is

   type Handle is new Plugins.Computer.Handle with null record;

   overriding function Call 
     (H : not null access Handle; A, B : Integer) return Integer;

end Computer;

The body is straightforward. The Life_Controller is used to control the Computer object’s life. The Initialize procedure (called when the plug-in is loaded) registers the service name and the Finalize procedure (called when the plug-in is unloaded) unregisters the service name.

with Ada.Finalization;
with Registry;
package body Computer is
   
   use Ada;
   
   type Life_Controller is new Finalization.Limited_Controlled with null record;
   overriding procedure Initialize (LC : in out Life_Controller);
   overriding procedure Finalize (LC : in out Life_Controller);
   
   H : aliased Handle;
   
   overriding function Call 
     (H : not null access Handle; A, B : Integer) return Integer is
   begin
      return A + B;
   end Call;
   
   overriding procedure Finalize (LC : in out Life_Controller) is
   begin
      Registry.Unregister (Plugins.Computer.Service_Name);
   end Finalize;
   
   overriding procedure Initialize (LC : in out Life_Controller) is
   begin
      Registry.Register (Plugins.Computer.Service_Name, H'Access);
   end Initialize;

   LC : Life_Controller;
   
end Computer;

Main

The main is the easy part. We just loop and once every second we discover plug-ins and call the Computer service if found.

with Ada.Text_IO;
with Plugins.Computer;
with Registry;
procedure Run is

   use Ada;
   use type Plugins.Ref;
   
   H      : Plugins.Ref;
   Result : Integer;
   
begin
   loop
      Text_IO.Put_Line ("loop...");
      Registry.Discover_Plugins;
      H := Plugins.Ref (Registry.Get (Plugins.Computer.Service_Name));
      if H /= null then
         Result := Plugins.Computer.Ref (H).Call (5, 7);
         Text_IO.Put_Line ("Result : " & Integer'Image (Result));
      end if;
      delay 1.0;
   end loop;
end Run;

To build and run the program, unpack the zip file attached to this Gem and execute the following commands:

$ gnat make -p -Pmain

$ gnat make -p -Pcomputer

$ ./run

Now, while the application is running, edit computer.adb and replace the addition in Call by a multiplication. Then recompile the computer plug-in:

$ gnat make -p -Pcomputer

After some time you’ll see that the new plug-in code has been loaded automatically.

Note that an extended example illustrating dynamic loading and unloading is included as part of the GNAT examples.

This is the first part of a two-part Gem about Ada plug-ins. In this Gem, we discuss the way shared libraries are supported by GNAT and the interactions between shared libraries and the Ada run-time system. This is essential to fully understanding how to build Ada plug-ins, which are discussed in the second part.

In modern operating systems it is rare to have fully self-contained applications, that is, executables that require no external support from the operating system. Such applications occur mostly in the embedded world. In other domains, an application is built on top of other services that are accessible from libraries.

There are two basic kinds of libraries: static and dynamic. A static library is a simple container for object code that will be included in the final application’s executable. This is done by the linker as the last step of creating an executable. That’s why such libraries are called static (statically linked, with the library code embedded in the executable). Without static libraries we would need to link against many object files, so this simplifies linking. The other benefit of static libraries organized as archives of object files is to allow selective linking, so that only the necessary objects from the library are linked into the final executable.

A static library can be built with GNAT by using project files. For example:

library project MyLib is
    for Source_Dirs use ("src");
    for Object_Dir use "obj";
    for Library_Dir use "lib";
    for Library_Name use "mylib";
    for Library_Kind use "static";
end MyLib;

Dynamic libraries are quite a different story: they allow splitting the image of an executable into several pieces, some of which can be shared among different executables. Dynamic libraries offer two main advantages: 1) sharing code among executables, thus diminishing global memory usage, and 2) allowing modular maintainance of an application by having the capability of replacing a chunk of an application without having to regenerate or even interrupt the complete application. It is also important to note that dynamic libraries require direct support from the operating system.

Linking with a shared library is done in two steps. The first step occurs at link time, when the linker generates a table in the executable that contains the name of the shared library and all of the symbols that must be imported from the shared library. The second step occurs at load time using the dynamic linker.

The dynamic linker is part of the operating system and is in charge of finalizing the linking of the application. This step is quite complex, but let’s summarize as follows. The dynamic linker:

1. Loads all shared libraries referenced by the executable.

2. Creates the executable-specific shared libraries’ data sections (only code is shared between executables, not data).

3. Fills in the executable’s corresponding shared library table with the actual addresses of the referenced symbols (variables and routines).

4. Calls the initialization routines (if any) defined in the just-loaded shared libraries.

At this point the application is ready to be run. Of course, shared libraries can reference other shared libraries; the dynamic linker is recursively doing the same job in this case. A very important point to understand is that whenever we have an Ada shared library used by an Ada application, both will be referencing the very same Ada run-time system. What is important in our context is that the elaboration is controlled by the executable and computed at bind time. This ensures proper Ada semantics as required by the standard.

A shared library can be built using a project file by setting the Library_Kind attribute to relocatable.

For plug-in support, the same piece of code may be loaded and unloaded several times and thus requires initialization to happen at load time and to be tied to the library itself; it cannot depend on the one-time global elaboration of the application.

GNAT has support for stand-alone shared libraries, and these are exactly the right kind of libraries to use in this context. A stand-alone library is a library that contains the necessary code to elaborate the Ada units that are included in the library and all the units it depends upon, recursively. Since many libraries may need to elaborate the same external units, the initialization code must be protected against multiple initializations of the same data objects.

Note that these libraries do not exactly conform to Ada semantics, since elaboration is supposed to happen only at program start and not in the middle when a plug-in is loaded. But such libraries are suitable for use with executables that are written in other languages or as plug-in libraries.

Declaring a library to be stand-alone is easy using GNAT Project files: it just requires adding an additional attribute in the library project file:

This attribute declares the units that are visible from outside the library, and thus offers a hiding mechanism (for all units not in the interface), complementing the one offered by Ada: any unit not in the interface cannot be called from outside. This means, in particular, that changing the implementation of such units can be done without having to recompile, rebind, or relink the rest of the application.

In the second part of this series we will see how to set up an Ada plug-in framework based on stand-alone libraries.