cactus-rt: a Linux real-time app framework

Developing real-time applications is already difficult due to the need to validate all parts of the system from hardware to the application. On a general-purpose operating system such as Linux, the complexity increases further due to most APIs being optimized for throughput as opposed to maximum latency.

cactus-rt is a C++ library that aims to make writing real-time Linux applications as easy as writing Arduino programs. Real-time application developers simply have to fill out a Loop function achieve 1000 Hz on Linux. The library should make most of the tedious decisions for you and provide sane defaults for everything.

How?

Core library

The core of cactus-rt consists of code that wraps the underlying OS-level real-time APIs so your application do not have to call them manually. These components includes:

• cactus_rt::App: memory locking, malloc tuning, service thread creation.
• cactus_rt::Thread: pthreads API for real-time thread creation
• cactus_rt::CyclicThread: real-time-safe clock to implement real-time timer
• signal_handler: handle signals

These are the bare minimum needed to create a real-time application. The interface is simple enough that all the application developer needs to do is to fill out Loop methods on classes derived from CyclicThread.

Example (full example in examples/simple_example):

class ExampleRTThread : public cactus_rt::CyclicThread {
 public:
  ExampleRTThread() : CyclicThread("ExampleRTThread", MakeConfig()) {}

 protected:
  LoopControl Loop(int64_t elapsed_ns) noexcept final {
    // Your code here...
    return LoopControl::Continue;
  }

  // ... MakeConfig definition omitted
};

Asynchronous logging integration via Quill

Debugging logic bugs in real-time applications during development can be tedious as logging via STL logging facilities (std::cout, std::print) are not real-time-safe in general. To get around this problem, cactus-rt natively integrates with Quill, which is an asynchronous, lock-free, and allocation-free logging library that also allows for simple usability with template strings. cactus-rt sets up Quill to run in non-allocating mode which is safe for real-time usage.

Since printf debugging is a critical feature to debug during development (and beyond), having Quill integrated directly in cactus-rt makes debugging real-time applications as easy as normal applications.

Example (full example in examples/simple_example):

LoopControl Loop(int64_t elapsed_ns) noexcept final {
  LOG_INFO(Logger(), "Hello {} {}", "world", 123); // Hello world 123
  return LoopControl::Continue;
}

Runtime performance tracing and visualization

Debugging timing bugs in real-time applications is critical as missed deadlines can have catastrophic consequences. One of the design goal of this library is to make debugging timing problems as easy as printf debugging. To accomplish this, cactus-rt includes a real-time-safe tracing system (implemented in a lock-free and allocation-free manner) that can measure the timing of spans within the code.

This system is designed to be safe to run for real-time application in production, as many timing issues can only be debugged within production. For certain applications, the entire run session can theoretically be traced to enable detailed analysis in post.

Example (full example in examples/tracing_example):

void Plan noexcept {
  // span will use RAII to emit a start and end event to be used for visualization
  // For this span, it would be the duration of this function
  auto span = Tracer().WithSpan("Plan");
  // ... your code
}

File truncated at 100 lines see the full file