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…”.

A new film added every Monday. To view all the films we’ve added to date, please visit the Ada Lecture Series.

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.

A new film added every Monday. To view all the films we’ve added to date, please visit the Ada Lecture Series.

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.

A new film added every Monday. To view all the films we’ve added to date, please visit the Ada Lecture Series.

UPDATE: View slides from the seminar.

AdaCore, from time to time, organizes seminars in the Paris/NY offices. If you are interested in a particular talk, please send email to events@adacore.com.

A new film added every Monday. To view all the films we’ve added to date, please visit the Ada Lecture Series.