redFOX User Guide

redFOX

Programmer's Manual

Version 0.93

12 November, 2005

1 Introduction: What is redFOX?

6 The Node Manager and Routing

13 Limitations and Known Bugs

1 Introduction: What is redFOX?

redFOX is a high performance, lightweight, distributed object technology for embedded systems. It is designed from the ground up for real-time systems requiring fast and predictable communication between objects on different processors. It provides a fast, efficient implementation of the distributed object paradigm from which to build high performance, but flexible, distributed applications.

redFOX makes C++ objects remotely accessible by generating middleware directly from C++ class definitions. No Interface Definition Language (IDL) is needed. It runs remote invocations at consistent priorities across multiple processors and Operating Systems. It runs on heterogeneous processors, operating systems and message transports.

redFOX minimizes software overhead of remote invocation to match the performance of hand coded message passing. It brings the abstraction benefits of the distributed object paradigm without a performance penalty.

Local object invocation has the overhead of a virtual function call. This makes it practical to build a distributed application from many small, reusable objects, rather a few large, inflexible objects. It allows system partitioning to be deferred until the application behavior and the target environment are well known. It also makes it easier to port the application to a new environment.

This manual is for software developers using redFOX. It describes installation, using the object model and system configuration.

2 Installation

A redFOX distribution package contains all the components required to use redFOX distributed objects on one development platform and one target system. For this release of redFOX, two systems, Linux and Cygwin (on MS Windows) are supported and in each case the development and the target platforms are the same.

The installed system supplies a modified version of the GCC preprocessor which is called via a new command, rcc, and a link library, redfox.a, which is required by all programs which use redFOX. Sample prorgrams and documentation in the form of a manual (this document) and a set of HTML pages which document the redFOX API are also installed.

2.1 Pre-requisites

To build applications with redFOX, you will need a suitably configured Linux or Microsoft Windows development platform. In the case of Windows, cygwin and g++ are also needed. The following table shows what software is needed for the different target platforms supported by redFOX.

Software	Description	Version(s)	From	Linux Target	OSE Target	Windows Target
Microsoft Windows¹	Operating System	2000, XP	www.microsoft.com		X	X
Red Hat Linux	Operating System	7.2+	www.redhat.com	X
Fedora Core Linux	Operating System	2+	fedora.redhat.com	X
OSE ²	Real Time Operating System Development Kit	5.1+	www.enea.com		X
Cygwin	GNU sub-system for MS Windows	1.1.0+	www.cygwin.com		X	X
GCC g++	C++ Compiler	3.2+	included with Cygwin, Linux and OSE	X	X	X
Boost	C++ Class Library	1.30.2+	www.boost.org, included with recent versions of Linux.	X	X	X

1This release of redFOX requires the Cygwin GNU environment for development.

2 Enea OSE is not supported in this release.

2.2 Distribution Files

redFOX is distributed as a single tar file which can be down downloaded from www.redplain.com. Tw o versions of the file are available:

Windows/Cygwin: redplain_?_??_cygwin-ia32.tar.gz
Linux/Fedora Core: redplain_?_??_linux-ia32.tar.gz

(where ?_?? represents the version number)

Both files have the same internal structure and are installed in the same way. Each file contains the following files:

File	Purpose	Shared Root
INSTALL	An installation script which performs all tasks needed to install redFOX
License.txt	Text of the redFOX license agreement
Gccxml-*	A tar file containing the GCCXML utility which is required by redFOX.	/usr/local /usr/local/share
runtime_folders*	A tar file containing the essential redFOX components	/usr/local
share_folders*	A tar file containing the program samples and the documentation	/usr/local/share

2.3 Installation Procedure

Download the distribution file and save it in a directory (eg /tmp) which will become the parent of the temporary installation folder.

The installation can be "shared" which means that it will be available in a standard system-wide location for all users or it can be "personal" which means that it will be installed in a location of the users choosing. The first case normally requires root or administrator privilege while the second is available to any user with write access to at least one directory.

The first step is to unpack the distribution:

$ cd /tmp

$ tar -xzf redplain_0_92_linux-ia32.tar.gz

This creates a new installation folder called redplain_redFOX_0_92. Change to this directory:

$ cd redplain_redFOX_0_92

Now execute the INSTALL script which will guide you through the remaining steps:

$ ./INSTALL

The questions posed by the script can be answered in most cases with a single keystroke such as "y" for "yes", etc. The license text can be viewed with the less viewer if available.

The script will offer you a choice of installation locations (as noted above). Select the one which suits your requirements.

This is an annotated example of an installation

$ ./INSTALL

=================================================================

Redplain Technology Ltd - RedFOX Middleware Installation

INSTALLATION SCRIPT

Version 0.1 - Alpha Release 1 October 2005

=================================================================

This script installs redFOX, Redplain's distributed object system

for C++. The installation can be for the current user or for all

users (requires root privilege).

redFOX requires the GCCXML utility and the Boost library to be

installed also. This script will check that they are accessible

and GCCXML will be installed, if required. Boost must be installed

separately

This version of redFOX only works with g++ V3.n on Linux and

MS Windows (with Cygwin) platforms. Future releases will work on

a wider range of platforms.

Some of this software is not in the public domain and may be used

only in accordance with the licence displayed below.

Redplain Technologies Ltd, Ashbourne, Co Meath, Ireland

email: info@redplain.com web: www.redplain.com

-----------------------------------------------------------------

Step 1 - read the licence

Type ENTER to view or L to view with 'less' (q to quit)? ➊

SOFTWARE EVALUATION AGREEMENT

1.Introduction and Acceptance.

This Software License Agreement (the "Agreement") is a legal

agreement between you (either an individual or an entity)

("You") and Red Plain Technology Ltd. ("Red Plain") regarding

[...missing sections of license...]

14.Questions.

Should you have any questions relating to this Agreement, or

if you desire to contact Red Plain for any reason, please call

(USA) +1-919-602-3865; or (Europe) +353-87-2208233.

I accept and agree the license ? [y/n] y ➋

Step 2 - decide where the package should be installed

Please select the location where the package will be installed

1: standard location, shared by all users ()

2: your home directory (/home/john/redplain)

3: other location (to be defined)

enter a number from the list above:2 ➌

Linux_ia32

Location /home/john/redplain does not exist -- create it ? [y/n]y ➍

GCCXML is already installed

Do you want to install a new copy in /home/john/redplain ? [y/n]y ➎

[...list of installed files...]

Delete the installation folder /tmp/redplain_redFOX_0_92/. [y/n] n ➏

Redplain middleware redFOX has been successfully installed

The numbered notes below refer to the labels in the example above.

➊ Enter return to view the license agreement directly or "L" to use the less viewer. If you use less, type "q" to end viewing and return to the INSTALL script.

➋ Enter "y" to accept the agreement. If you enter anything else the script terminates.

➌ At this point you select the location for the installed files. Option 1 gives the shared installation in standard locations; option 2 places all the files in a sub-directory of your home directory while option 3 allows you to choose the location. In the example, option 2 is chosen. Options 2 and 3 require that the target directory does NOT exist. If it does the script will terminate.

➍ This question allows you to check that the correct target has been chosen. Answer "y" to continue.

➎ At this point a check is made to determine if the GCCXML utility is already installed on your system. If it is you do not need to install it again. However, the version supplied with redFOX may be more recent.

➏ At this point the installation is complete and you are offered the choice of retaining or deleting the temporary installation folder. Answer "y" or "n". (In the current release the folder is never deleted).

3 Getting Started

The redFOX distribution includes a simple demo application, which you can build and run under Linux or Windows. Use it to check that everything is working, to familiarize yourself with the tools and to serve as a starting template for your own applications.

The demo application has one source file, counter.cpp and a Makefile.

Open two console windows with the current directory at $(REDPLAIN)/samples/counter.
In one window, build the application by typing make.
In the same window, run counter, taking standard input from counter0.cfg
In the other window, run counter, taking standard input from counter1.cfg.

If everything worked, you have run your first distributed application using redFOX, albeit as two processes on a single processor. You can copy this simple application and use it to experiment with distributed processing.

The files counter0.cfg and counter1.cfg contain the node configuration information for the redFOX node manager. The information includes the node number, the total number of nodes and details of connections to other nodes. In this case, there are two nodes and they communicate by TCP/IP on the local host.

The application on each node starts by calling main(). When the first call is made to redplain::node_manager::instance(), the configuration information is read and the node is initialized. The node can now send, receive and run remote invocations.

In the counter application, a simple counter class (1) has a constructor (2), a destructor (3), increment (4) and value (5) methods. The class is accessed remotely using class redplain::dref<Counter>, which is similar in nature to a C++ rerefence and is automatically generated from directives (6). Node 0 merely initializes (7) and waits for shutdown (14). All activity on node 0 is a result of remote invocations from node 1. Node 1 waits for node 0 to come up (8), remotely creates a counter object on node 0 (9), increments it 10 times (10) and reads its value to confirm that it is correct (11). Node 1 then destroys the counter (12) shuts down node 0 (13) and terminates itself.

// redFOX sample application – remote counter

#include <iostream>
#include <redplain/dref.h>
#include <redplain/node_manager.h>
#include <redplain/thread.h> // for redplain::thread::sleep
using namespace std;
using namespace redplain;

// A simple class to demonstrate remotely accessible objects ///////////////

class Counter {                                       // (1)
private:
uint32_t n_;
public:
inline Counter() : n_(0) {                          // (2)
    cout << "Counter::Counter() called.\n";
}

inline ~Counter() {                                 // (3)
    cout << "Counter::~Counter() called.\n";
}

inline void increment() {                           // (4)
    cout << "Counter::increment() called.\n";
    ++n_;
}

inline uint32_t value() const {                     // (5)
    cout << "Counter::value() called. Returning " << n_ << "\n";
    return n_;
}
};

// Directives to generate dref<Counter>, making Counters remotely accessible ///

#pragma redplain dref<::Counter> interface           // (6)
#pragma redplain dref<::Counter> implementation

// Application /////////////////////////////////////////////////////////////

int main() {

redplain::node_id_t node = node_manager::instance().local_node(); // (7)
cout << "redFOX Remote Counter Demo starting on node " << node << ".\n";
if (node == 1) {
    while (!node_manager::instance().ping(0))        // (8)
      redplain::thread::sleep(1);
    cout << "Creating remote counter ...\n";
   dref<Counter> remoteCounter(0);                  // (9)

    const unsigned loops = 10;
    for (uint32_t n=0; n != loops; ++n) {
      cout << "Incrementing remote counter ...\n";
      remoteCounter.increment();                     // (10)
    }

    if (remoteCounter.value() == loops)              // (11)
      cout << "Remote Counter working.\n";
    else
      cout << "Remote Counter faulty.\n";

    cout << "Deleting remote counter ...\n";
    redplain::delete_object(remoteCounter);          // (12)

    // Tell other node manager to terminate
    node_manager::instance().shutdown_all();         // (13)

} else {
    // Main thread on node 0 just waits for termination.
    node_manager::instance().wait_for_shutdown();    // (14)
}

  cout << "Node " << node << " terminating.\n";
return 0;
}

4 Programmer's Model