cactus-rt: a Linux real-time app framework

Relevant blog posts: Part 1 | Part 2 | Part 3 | Part 4

cactus_rt library

This is a library that refactors a lot of the boilerplate code needed for writing a real-time Linux application. Some key features are:

• cactus_rt::App: Implements logic for memory locking, memory reservation, and malloc tuning.
  • The memory reservation and malloc tuning may not be needed if an O(1) allocator is not used. See this discussion.
• cactus_rt::Thread<SchedulerT>: Implements a thread class. Applications are expected to create a derived class for their custom threads. The SchedulerT template argument specifies the scheduler class the thread can use. Right now, cactus_rt::schedulers::Fifo, cactus_rt::schedulers::Deadline, and cactus_rt::schedulers::Other (non-RT) can be used.
• cactus_rt::CyclicThread<SchedulerT>: Implements a looping thread.
  • For applications with extra low-jitter requirements, it implements a busy wait method to reduce wakeup jitter. See this for more details. In the future, this will be a scheduler (cactus_rt::schedulers::FifoBusyWait) but it is not yet implemented.
• cactus_rt::mutex: A priority-inheriting mutex that is a drop-in replacement for std::mutex.

Examples

• simple_example: The most basic example showing a single real-time looping thread running at 1000 Hz.

• tracing_example: This demonstrates how to use the real-time-safe tracing system built into cactus-rt. This is probably a good thing to undrestand immediately after the above example.

• mutex_example: Demonstrates the usage of priority-inheritence mutex (cactus_rt::mutex) to pass data between real-time and non-real-time threads via the implementation of a mutex-based double buffer.

• logging_example: Demonstrates setting up custom logging configuration via cactus_rt::App.

• simple_deadline_example: Same as simple_example, except it uses SCHED_DEADLINE as opposed to SCHED_FIFO. This is for a more advanced use case.

• tracing_example_no_rt: Shows how to using the tracing library in cactus_rt without using cactus_rt::App.

Installation instructions

Dependencies

cactus_rt the library is dependent on:

• Linux
  • PREEMPT_RT patch preferred, but not required as mainline Linux has partial real-time support (with higher latency).
• C++ compiler supporting C++ 17 and up.
• CMake
• Quill: this is included as a part of the CMake-based build process.
• moodycamel::ReaderWriterQueue: this is included as a part of the CMake-based build process.
• Protobuf: for runtime tracing
• GTest (libgtest-dev), Google Benchmark (libbenchmark-dev): for testing and benchmarking

For Debian/Ubuntu:

$ sudo apt install build-essential cmake protobuf-compiler libprotobuf-dev libgtest-dev libbenchmark-dev

For building documentations, we need: doxygen.

Build

To build in debug mode:

$ make debug

To run an example:

$ sudo build/debug/examples/simple_example/rt_simple_example

To turn OFF building the examples:

$ make debug ENABLE_EXAMPLES=OFF

To turn on clang-tidy:

$ make debug ENABLE_CLANG_TIDY=ON

For compiling in release mode:

$ make release

All flags remain valid for both make debug and make release. Consult the Makefile for details on how it works as it is just a convenience wrapper on cmake. The example binaries will be located in the folder build/release instead of build/debug.

For testing like CI, you need docker installed and then you can use:

$ scripts/test-in-docker

Include from another project

To build into other projects, simply use FetchContent in your CMakeLists.txt file:

include(FetchContent)
FetchContent_Declare(
  cactus_rt
  GIT_REPOSITORY https://github.com/cactusdynamics/cactus-rt.git
  GIT_TAG        ...
)
FetchContent_MakeAvailable(cactus_rt)

# ...

target_link_libraries(myapp PRIVATE cactus_rt)

Note that if you compile your app in debug mode, cactus-rt will be compiled in debug mode due to how FetchContent works. To get cactus-rt in release mode, compile your app in release mode.

LICENSE

Open source projects and some commercial projects can use MPL 2.0.

If you need commercial, closed-sourced modifications, please obtain a license from Cactus Dynamics.

This library embeds work from Perfetto, which is licensed under Apache License, version 2.