Repository files navigation

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

The framework for robust C++ applications is referred to as theRobustServices Core (RSC). RSC will put your project on the right path and jump-startit if you're developing or reengineering a system whose requirements can becharacterized as

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

The design patterns used in RSC make developers more productive. They havebeen proven in flagship telecom products, including (from the author'sexperience as its chief software architect) the core network server thathandles all of the calls in AT&T's cellular network. A pattern language thatsummarizes the patterns appears in thesecond chapter ofRobust Communications Software.The documentRSC Software Overviewdescribes which of them are currently available in this repository and pointsto the primary code files that implement them, and thistutorial provides more information about some ofthem.

The development of RSC has been somewhat sidetracked by the development of C++static analysis tools. These tools detect violations of various C++ designguidelines, such as those found in Scott Meyers'Effective C++. They alsoanalyze#include directives to determine which ones to add or delete. Theireditor then allows you to easily and interactively fix many of the warningsthat the tool generates. Even if you're not developing applications withRSC, you might find these tools useful. An overview of them is providedhere.

Including an application with a framework serves to test it and illustrate itsuse. This repository therefore includes a POTS (Plain Ordinary TelephoneService) application. POTS was chosen for several reasons. For one thing, theauthor had extensive experience with similar applications while working in thetelecom industry. But more importantly, POTS is a non-trivial application, yeteveryone has a reasonable understanding of what it does. You should thereforebe able to figure out what the POTS code is doing without reading a largespecification. An overview of the POTS application is providedhere.

In 2002, a group in the UK began to design a protocol that allows softwarebots to play the board gameDiplomacy. Theirwebsite has various useful links and downloads,amongst which is the executable for a Diplomacy server. Bots log into thisserver, which sends them the state of the game, allows them to communicate withone another using the protocol, and adjudicates the moves that they submit.Their website also provides software for developing bots. I decided torefactor this software, decouple it fromWindows, and bring it more in line with C++11. This helped RSC evolveto better support standalone clients that use IP (TCP, in this case). Theresulting software is available in thedip directory and isdescribed in some further detailhere.

This page provides an overview of RSC. Another page listsdocuments that go into far more depth on many topics.

Download one of thereleases.Code committed since the latest release is work in progress and may be unstableor incomplete, so downloading from theCode▾ dropdown menu on themain page is not recommended.

⚠️Warning

For proper operation, RSC must be launched from a directory belowitssrc directory. See theinstallation guide.

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 andplatform-specific.cpp's, that should allow it to be ported to other systemsfairly easily.

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

The directories that contain RSC's source code, and the dependencies betweenthem, are listed in the comments that precede the implementation ofmain. Each of these directories is built as a separatestatic library, withmain residing in its own directory.

RSC is developed using Visual Studio 2022 and built using CMake, as describedhere. Windows build options for RSCare describedhere. VisualStudio's.vcxproj files are no longer used during builds, sothey were removed from the repository.

During initialization, RSC displays each module as it is initialized.(Amodule is equivalent to a static library.) After all moduleshave initialized, the CLI promptnb> appears to indicate that CLI commandsin thenb directory are available. What is written to the consoleduring startup is shownhere, and a list of allCLI commands is providedhere.

If you enter>read saveinit as the first CLI command, a function trace ofthe initialization, which starts even before the invocation ofmain, isgenerated. This trace will look a lot likethis.Each function that appears in such a trace invokedDebug::ft, which recordsthe 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 youcan 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 the directory immediately above thesrc directory.In addition to any specific output that you request, such as the initializationtrace, every CLI session produces

• aconsole file (a transcript of the CLI commands that you entered andwhat was written to the console)
• alog file (system events that were written to the console asynchronously)

The numeric stringyymmdd-hhmmss is appended to the names of these filesto record the time when the system initialized (for theconsole file andinitiallog file) or the time of the most recent restart (for a subsequentlog file).

The easiest way to use RSC as a framework is to create a static library belowRSC'ssrc directory. Theapp directory is provided forthis purpose. Simply use whatever subset of RSC that your applicationneeds. This will always include the namespaceNodeBase (thenbdirectory). It might also includeNetworkBase (thenwdirectory) andSessionBase (thesb directory). Using a newnamespace for your application is recommended.

If you put your code elsewhere, RSC will be unable to find importantdirectories when you launch it, as described in theinstallation guide. You will then needto modify the functionElement::RscPath so that itcan find the directory that contains theinput directory. Youshould also add RSC'shelp directory to that directory.

To initialize your application, derive fromModule.For an example, seeNbModule, which initializesNodeBase. ChangeCreateModules so that it alsoinstantiates your module, as well as the other modules that you need inyour build.

To interact with your application, derive fromCliIncrement.For an example, seeNbIncrement, the incrementforNodeBase. Instantiate your CLI increment in your module'sStartupfunction. When you launch RSC, you can then access the commands in yourincrement through the CLI by entering>incr, whereincr is theabbreviation that your increment's constructor passed toCliIncrement'sconstructor.

Most of the files in theinput directory are test scripts. Thedocument that describes thePOTS applicationalso discusses its tests, which exercise a considerable portion of RSC'ssoftware. Some other tests are more tactical in nature:

• A set of scripts tests the Safety Net capability of theThread class.A dedicatedpage describes these tests and thecurrent status of each one.

• Entering>nt in the CLI accesses the "nt"increment (a set of CLIcommands). It provides commands for testing functions in theBuddyHeap,SlabHeap,LeakyBucketCounter,Q1Way,Q2Way, andRegistry interfaces.

RSC is freely available under the terms of theLesser GNU General PublicLicense, version 3, which basically says that you must alsopublish your changes to RSC, such as bug fixes and enhancements. If youare developing commercial software that you want to keep proprietary, theLGPLv3 license allows applications built on RSC to be proprietary.

How to contribute to RSC is describedhere.

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