Skip to content
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time

robust-services-core

This repository contains

  1. A framework for developing robust applications in C++.
  2. An application built using the framework.
  3. Tools for the static analysis of C++ software.
  4. A framework for developing a bot that can play the board game Diplomacy.

Robust Services Core

The framework that supports robust applications is referred to as the Robust Services Core (RSC). RSC will put your project on the right path and jump-start it if you're developing or reengineering a system whose requirements can be characterized as

  • highly available, reliable, and/or scalable;
  • embedded, reactive, stateful, and/or distributed.

The design patterns used in RSC make developers more productive. They have been proven in flagship telecom products, including (from the author's experience as its chief software architect) the core network server that handles all of the calls in AT&T's cellular network. A pattern language that summarizes the patterns appears in the second chapter of Robust Communications Software. The document RSC Software Overview describes which of them are currently available in this repository and points to the primary code files that implement them, and this tutorial provides more information about some of them.

C++ static analysis tools

The development of RSC has been somewhat sidetracked by the development of C++ static analysis tools. These tools detect violations of various C++ design guidelines, such as those found in Scott Meyers' Effective C++. They also analyze #include directives to determine which ones to add or delete. Their editor then allows you to easily and interactively fix (as of release v0.30.0) 100 of the 146 warning types. Even if you're not developing applications with RSC, you might find these tools useful. An overview of them is provided here.

POTS application

Including an application with a framework serves to test it and illustrate its use. This repository therefore includes a POTS (Plain Ordinary Telephone Service) application. POTS was chosen for several reasons. For one thing, the author had extensive experience with similar applications while working in the telecom industry. But more importantly, POTS is a non-trivial application, yet everyone has a reasonable understanding of what it does. You should therefore be able to figure out what the POTS code is doing without reading a large specification. An overview of the POTS application is provided here.

Diplomacy AI client

In 2002, a group in the UK began to design a protocol that allows software bots to play the board game Diplomacy. See their website for various useful links and downloads, amongst which is the executable for a Diplomacy server. Bots log into this server, which sends them the state of the game, allows them to communicate with one another using the protocol, and adjudicates the moves that they submit. Their website also provides base software for developing bots. It seemed that it would be interesting to refactor this software while decoupling it from Windows and bringing it more in line with C++11. This would help RSC evolve to better support standalone clients that use IP (TCP, in this case). The resulting software is available in the dip directory and is described in some further detail here.

Documentation

This page provides an overview of RSC. There is also a page which lists documents that go into far more depth on many topics.

Installing the repository

Download one of the releases. Code checked since the latest release is work in progress and may be unstable or incomplete, so downloading from the green "Code" dropdown menu on the home page is not recommended.

After you download and extract the repository, do not alter its directory structure. This is because, when the executable starts, it looks for its configuration file on the path ../<dir>/input/element.config.txt, where <dir> is the directory immediately above the src directory that contains the code.

Building an executable

RSC

  • requires C++17;
  • is a console application;
  • runs on both Windows and Linux;
  • defines an abstraction layer, in the form of generic C++ .h's and platform-specific .cpp's, that should allow it to be ported to other systems fairly easily.

If you don't want to build RSC, debug and release executables are provided with each release.

The directories that contain RSC's source code, and the dependencies between them, are listed in the comments that precede the implementation of main. Each of these directories is built as a separate static library, with main residing in its own directory.

RSC is developed using Visual Studio 2022. The Windows build options that RSC uses are described here.

RSC is built using CMake, as described here. Because Visual Studio's .vcxproj files are no longer modified as part of the build process, they have been removed from the repository.

Running the executable

During initialization, RSC displays each module as it is initialized. (A module is equivalent to a static library.) After all modules have initialized, the CLI prompt nb> appears to indicate that CLI commands in the nb directory are available. The information written to the console during startup is shown here, and a list of all CLI commands is provided here.

If you enter >read saveinit as the first CLI command, a function trace of the initialization, which starts even before the invocation of main, is generated. This trace will look a lot like this. Each function that appears in such a trace invoked Debug::ft, which records the following:

  • the function's name
  • the time when it was invoked
  • the thread that invoked it
  • its depth (in frames) on the stack: this controls indentation so that you can see how function calls were nested
  • the total time spent in the function (in microseconds)
  • the net time spent in the function (in microseconds)

All output appears in the directory ../<dir>/excluded/output, where <dir> is, again, the directory immediately above the src directory. In addition to any specific output that you request, such as the initialization trace, every CLI session produces

  • a console file (a transcript of the CLI commands that you entered and what was written to the console)
  • a log file (system events that were written to the console asynchronously)

The numeric string yymmdd-hhmmss is appended to the names of these files to record the time when the system initialized (for the console file and initial log file) or the time of the preceding restart (for a subsequent log file).

Developing an application

The easiest way to use RSC as a framework is to create a static library below RSC's src directory. Simply use whatever subset of RSC that your application needs. This will always include the namespace NodeBase (in the nb directory). It might also include NetworkBase (in the nw directory) and SessionBase (in the sb directory). Using a new namespace for your application is recommended.

If you put your code elsewhere, RSC will be unable to find its configuration file when you launch it, as described in Installing the Repository. You will then need to modify the function Element::RscPath so that it can find the directory that contains the input directory. You should also add RSC's help directory to that directory.

To initialize your application, derive from Module. For an example, see NbModule, which initializes NodeBase. Change CreateModules so that it also instantiates your module, and comment out its instantiation of modules that you don't want in your build. If you prefer not to change RSC's main(), you can change the copy in the app directory, as described here.

To interact with your application, derive from CliIncrement. For an example, see NbIncrement, the increment for NodeBase. Instantiate your CLI increment in your module's Startup function. When you launch RSC, you can then access the commands in your increment through the CLI by entering >incr, where incr is the abbreviation that your increment's constructor passed to CliIncrement's constructor.

Testing

Most of the files in the input directory are test scripts. The document that describes the POTS application also discusses its tests, which exercise a considerable portion of the RSC software. The tests described below are rather tactical by comparison.

Twenty-nine scripts test the Safety Net capability of the Thread class. A dedicated page describes these tests and the current status of each one.

Entering >nt in the CLI accesses the "nt" increment (a set of CLI commands). It provides sets of commands for testing functions in the BuddyHeap, LeakyBucketCounter, Q1Way, Q2Way, and Registry interfaces.

Licensing

RSC is freely available under the terms of the GNU General Public License, version 3, which basically says that you must also publish your own software, as well as your changes to RSC. If you are developing software that you want to keep proprietary, the GPLv3 license also allows RSC to be licensed under the terms of another license approved by the Free Software Foundation. Some of those licenses allow your software to remain proprietary. However, compensation would be required, and any changes that you make to RSC itself (bug fixes and enhancements) would still have to be published.

Contributing

How to contribute to RSC is described here.

Sponsoring

GitHub now lets you sponsor projects. A "Sponsor" button is located at the top of this page.