libsolace

---

libSolace is a library to help to build a mission-critical application.

library: a collection of types, functions, classes, etc. implementing a set of facilities (abstractions) meant to be potentially used as part of more that one program. From Cpp Code guidelines glossary

The idea of this library is partially inspired by NASA's Rules for Developing Safety Critical Code. That is the aims to provide building blocks for efficient and reliable applications using modern C++ (at least C++17). Note: it is by no means as strict implementation of all of P10 rules but an attempt to provide components that make it easy to observe these rules.

Motivation

Solace is used to provide building primitives to develop a system of communicating processes that solve a problem via collaboration (aka cluster application/actor system). It puts the developer in charge of the system and provides mechanisms for explicit memory management. As such, it never spawns a thread or allocates memory after initialization.

Contributing changes

The framework is work in progress and contributions are very welcomed. Please see CONTRIBUTING.md for details on how to contribute to this project.

Please note that in order to maintain code quality, a set of static code analysis tools is used as part of the build process. Thus all contributions must be verified by these tools before PR can be accepted.

Using the library

This library needs to be installed on your system in order to be used. There are a few ways this can be done:

• You can install the pre-built version via Conan package manager. (Recommended)
• You can build it from sources and install it locally.
• You can install a pre-built version via your system package manager such as deb/apt if it is available in your system repository.

Consuming library with Conan

The library is available via Conan package manager. Add this to your project conanfile.txt:

[requires]
libsolace/0.3.9

Please check the latest available binary version.

Building from sources

The project build is managed via CMake with a Makefile provided to automate some everyday actions during the development process.

Build tool dependencies

In order to build this project, following tools must be present in the system:

• git (to check out this project)
• cmake (version 3.12 and above)
• conan - Conan package and dependency management.
• doxygen (for documentation generation)
• cppcheck (static code analysis, the latest version from git is used as part of the 'codecheck' build step)
• cpplint (for static code analysis in addition to cppcheck)
• valgrind (for runtime code quality verification)

This project is using C++17 features extensively. The minimal tested/required version of gcc is gcc-7. CI is using clang-5 and gcc-7. To install build tools on Debian based Linux distribution:

sudo apt update -qq
sudo apt install cmake doxygen python-pip valgrind ggcov
python3 -m pip install cpplint conan -U
conan profile new default --detect

The only external dependency is on googletest - a unit testing framework used for development.

Building the project

Current build system used for the project is cmake. Please make sure that the system has cmake installed. Minimal confirmed version is 3.0

> cmake --version
cmake version 3.12.1

# In the project checkout directory:
# To build a debug version with sanitizer enabled (recommended for development)
./configure --enable-debug --enable-sanitizer

# To build the library itself
make

# To build and run unit tests:
make test

# To run Valgrind on test suit:
# Note: `valgrind` does not work with `./configure --enable-sanitize` option
# Configure as: `./configure --enable-debug --disable-sanitize`
make verify

Build API documentation using doxygen:

Documentation system used by the library is doxygen. Docs can be build with:

make doc

Installing library locally:

To install locally for testing:

make --prefix=/user/home/${USER}/test/lib install

To install system-wide (as root):

make install

To run code quality check before submission of a patch:

# Verify code quality before submission
make codecheck

Target Platforms

The library is designed with the following platforms in mind:

• Parallella
• Raspberry Pi
• BeagleBone
• NVIDIA Jetson
• Linux / Freebsd / Macos

Design

Main goal of design for this library is to make declarative programming in C++ easy. As a result a number of similir data structures provided are inspired by othre functional languages. So some of the concepts and types might fill familiar if you have previous experience with Rust, Java, Python etc.

• Fixed-size integral types:

  • Fix sized integral types:
    • int{8,16,32}
    • uint{8,16,32}
    • float{32,64}

• Memory management interface:

  • MemoryManager – a custom memory allocator that can be locked to control memory allocation after initialization.

• Immutable String (for those who are from Java land) with StringBuilder.

• Optional<> - optional monad.

• Result<> - Either monad. An alternative approach to error handling instead of throwing exceptions.

• Fixed-size collections:

  • Array: Fixed-size array (dynamically allocated on the heap)
  • Vector: A collection to hold up-to given number of elements. No re-allocation performed if limit is reached.

• Views to different data structures. Views don't own underlying resources and must be used with care as to not to exceed lifetime of the object being viewed. Views are designed to be "lightweight" many views can exist for same resource. It is also convenient for slicing of a resource. It is preferable to pass views by value.

  • ArrayView: a memory view as a collection of objects.
  • MemoryView – a OOP way of dealing with raw memory that knows its size and has associated destructor.
  • StringView - non-owning "string" consisting of pointer and an integer representing length of the string.

• ArrayBuilder: variable-length collection

• Text utilities:

  • Formatting
  • Encoding

• Path – immutable hierarchy of string elements.

• PathBuilder – a builder object for path.

Exceptions policy

Given the language of choice, the library is designed with the idea that exceptions can be thrown and functions that don't throw are annotated accordingly. The design is the result of a few ideas:

• Regular functions that return values but which invocations can result in an error (due to invalid internal state or invalid arguments) - this functions should signal that fact by returning Result<Value, Error> (the idea borrowed from Rust language)
• Object constructors can't return value; thus they are allowed to throw.
• All API clients that want to use 'safe' interface should use object factories that return Result<> with possible error but don't throw.

Dependencies

The project has no dependencies other then unit testing framework.

• GTest - Google's C++ test framework

Testing

The library is equipped with the GTest test suit. The source code for unit test located in directory test

Tests can (and should) be run via:

make test

Developers/Contributing

Please make sure that static code check step returns no error before raising a pull request

make codecheck

It is also a good idea to run Valgrind on the test suit to make sure that the memory is safe

make verify

Projects that might be similar in some aspects:

• Folly
• Stout
• Poco
• NSPR
• APR
• SDL
• Marmalade
• GLibMM
• Qt(Core)

Licensing

The library available under Apache License 2.0 Please see LICENSE for details.

Authors

Please see AUTHORS file for the list of contributors.