app

Base application lifecycle kit for modern C++.

app provides a minimal, deterministic application runtime foundation designed for Vix application scaffolding.

• Explicit start / stop lifecycle
• Structured run loop
• Graceful shutdown (SIGINT, SIGTERM)
• Hook-based initialization and cleanup

Header-only. Standard library only. Zero external dependencies.

Download

https://vixcpp.com/registry/pkg/vix/app

Why app?

Every long-running C++ application eventually needs:

• Startup initialization
• Graceful shutdown
• Signal handling
• Lifecycle structure
• A main run loop
• Clean separation between bootstrap and runtime

Most projects either:

• Put everything inside main()
• Reimplement ad-hoc loops
• Forget proper shutdown handling
• Mix lifecycle and business logic

app provides:

• A minimal lifecycle base class
• Explicit hooks (on_start, on_stop)
• Customizable run loop
• Safe stop signaling
• Clean extension points

No logging system. No HTTP layer. No async runtime.

Just a deterministic application foundation.

Installation

Using Vix Registry

vix add vix/app
vix deps

Manual

git clone https://github.com/vixcpp/app.git

Add the include/ directory to your project.

Dependency

Requires C++17 or newer. No external dependencies.

Quick examples

Minimal application

#include <app/app.hpp>
#include <iostream>

class MyApp : public vix::app::Application
{
protected:
    void loop_step() override
    {
        std::cout << "tick\n";
        stop(); // stop after one iteration
    }
};

int main()
{
    MyApp app;

    app.on_start([] {
        std::cout << "starting\n";
    });

    app.on_stop([] {
        std::cout << "stopping\n";
    });

    app.run();
}

Custom run loop

#include <app/app.hpp>
#include <chrono>
#include <iostream>
#include <thread>

class CustomApp : public vix::app::Application
{
protected:
    void run_loop() override
    {
        for (int i = 0; i < 5 && is_running(); ++i)
        {
            std::cout << "step: " << i << "\n";
            std::this_thread::sleep_for(std::chrono::milliseconds(50));
        }
        stop();
    }
};

int main()
{
    CustomApp app;
    app.run();
}

API overview

vix::app::Application

• Application::run()
• Application::stop()
• Application::is_running()
• Application::on_start()
• Application::on_stop()

Protected extension points:

• Application::run_loop()
• Application::loop_step()
• Application::tick_interval()

Lifecycle model

Execution order:

1. run()
2. on_start() hook
3. run_loop()
4. stop() requested
5. on_stop() hook
6. exit

Signals handled:

• SIGINT
• SIGTERM

Graceful shutdown is guaranteed if stop() is triggered.

Complexity

All operations are constant time.

Operation	Time complexity
run() start	O(1)
stop()	O(1)
is_running()	O(1)

The run loop complexity depends on user-defined behavior.

Design principles

• Deterministic lifecycle
• Explicit extension points
• No hidden threads
• No global state (except controlled signal pointer)
• Minimal abstraction
• Stable foundation for higher-level runtimes

This library provides primitives only.

If you need:

• HTTP server runtime
• WebSocket handling
• Async I/O engine
• Microservice orchestration

Build them on top of this layer (web_app, service_app, realtime_app, etc.).

Tests

Run:

vix build
vix test

Tests verify:

• Lifecycle execution
• Hook execution
• Proper stop behavior
• Loop iteration
• Graceful termination

License

MIT License
Copyright (c) Gaspard Kirira