Skip to content
Robust applications framework in C++. Includes a static analysis tool and two applications.
C++
Branch: master
Clone or download
GregUtas Utas191011a (#126)
* Minor changes.

* Fix template argument bugs and use NoFlags.

* Increase an object pool's size when allocation could fail.

* Fix immediate tracing of startup.

* Tweak test scripts for LIFO ingress messages and scheduling changes.

* Suppress some >check warnings.

* Rework scheduling of unpreemptable threads.
Latest commit 597afed Oct 15, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
an Use relative paths where possible. (#125) Oct 11, 2019
cb Use relative paths where possible. (#125) Oct 11, 2019
cn Use relative paths where possible. (#125) Oct 11, 2019
ct Utas191011a (#126) Oct 15, 2019
dip Use relative paths where possible. (#125) Oct 11, 2019
docs Update README.md Oct 8, 2019
exe Utas191011a (#126) Oct 15, 2019
help Utas191011a (#126) Oct 15, 2019
input Utas191011a (#126) Oct 15, 2019
mb
nb Utas191011a (#126) Oct 15, 2019
nt Use relative paths where possible. (#125) Oct 11, 2019
nw Use relative paths where possible. (#125) Oct 11, 2019
on Use relative paths where possible. (#125) Oct 11, 2019
output Utas191011a (#126) Oct 15, 2019
pb Use relative paths where possible. (#125) Oct 11, 2019
rn Use relative paths where possible. (#125) Oct 11, 2019
rsc Use relative paths where possible. (#125) Oct 11, 2019
sb Use relative paths where possible. (#125) Oct 11, 2019
shared Utas190903a (#121) Sep 15, 2019
sn Use relative paths where possible. (#125) Oct 11, 2019
st Use relative paths where possible. (#125) Oct 11, 2019
subs Utas190903a (#121) Sep 15, 2019
.gitattributes Add .gitignore and .gitattributes. Sep 1, 2017
.gitignore Utas181219a (#104) Feb 19, 2019
AGREEMENT.md Update AGREEMENT.md Nov 25, 2017
CODEOWNERS Create CODEOWNERS Nov 29, 2017
CONTACT.md Utas171202a (#84) Dec 3, 2017
CONTRIBUTING.md Utas190903a (#121) Sep 15, 2019
ENTITY.md Update ENTITY.md Nov 25, 2017
INDIVIDUAL.md Update INDIVIDUAL.md Nov 25, 2017
LICENSE.txt Licensing (#81) Nov 24, 2017
README.md Update README.md Oct 11, 2019
rsc.sln Utas181219a (#104) Feb 19, 2019

README.md

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 Product 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.

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.

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 should be added or deleted. Even if you're not developing applications with RSC, you might find these tools useful. An overview of them 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.

Installing the repository

Download the repository to a directory named rsc. This is because, when the executable starts, it looks for its configuration file on the path ../rsc/input/element.config.txt.

Building an executable

RSC requires C++11.

RSC is currently implemented on Windows, where it runs as a console application. However, it 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. Two executables, for 32-bit and 64-bit Windows, are provided here.

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 currently developed using Visual Studio 2017. If that is also your development environment, the .vcxproj (project) files in this repository should already provide most of the build instructions that you need.

Running the executable

During initialization, the program displays each module as it is initialized. (A module is currently 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 should 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 ../rsc/excluded/output (the first directory named rsc above the directory from which the .exe was launched). 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-mmm 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).

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 scripts test the Safety Net capability of the Thread class. Most of these tests cause a POSIX signal to be raised. POSIX signals are handled by throwing a C++ exception that is caught in Thread.Start, after which an appropriate recovery action is taken. Getting the safety net to work could be a challenge when porting RSC to another platform, which is why these tests are provided. All of the safety net tests can be run with the command >read test.trap.all. During each test, the following are generated (see the recover.* files in the output directory):

  • A function trace (*.trace.txt), as described above.
  • A function profile (*.funcs.txt) that lists each function that was invoked, along with how many times it was invoked and the total net time spent in it. This information is not that useful here, but it is valuable when you want to pinpoint which functions to focus on in order to improve real-time performance.
  • A scheduler trace (*.sched.txt). The first part of this trace lists all threads in the executable, with statistics for each. The second part is a record of all the context switches that occurred during the test.
  • A console file of the test (*.cli.txt), as described above.

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

License

The software in this repository is freely available under the terms of the GNU General Public License, version 3. If you have concerns about this license, it may be possible to obtain the software under the terms of another license approved by the Free Software Foundation.

Contributing

How to contribute to RSC is described here.

You can’t perform that action at this time.