Usage Examples

Examples of using Consolix framework.

Usage Examples

This page demonstrates how to use various features of the Consolix framework. It covers key components and utilities with practical examples.

Basic Setup

Here's how to initialize and use Consolix in a simple console application:

#define CONSOLIX_USE_LOGIT 1
#include <consolix/consolix.hpp>
 
int main(int argc, char* argv[]) {
    // Initialize logger
    consolix::add<consolix::LoggerComponent>();
 
    // Display the application logo
    consolix::add<consolix::LogoComponent>(consolix::TextColor::DarkYellow);
 
    // Handle command-line arguments
    consolix::add<consolix::CliComponent>("MyApp", "Program description", [](auto& options) {
        options.add_options()("debug", "Enable debug mode");
    }, argc, argv);
 
    // Load configuration from a JSON file
    consolix::add<consolix::ConfigComponent<MyConfig>>("config.json");
 
    // Execute the main loop
    consolix::run([]() {
        CONSOLIX_STREAM() << "Executing main loop...";
    });
}

Using the ServiceLocator

The ServiceLocator provides global access to shared resources:

#include <consolix/core.hpp>
 
int main() {
    // Register a service
    consolix::register_service<std::string>([]() {
        return std::make_shared<std::string>("Hello, Consolix!");
    });
 
    // Check and access the service
    if (consolix::has_service<std::string>()) {
        auto& message = consolix::get_service<std::string>();
        std::cout << message << std::endl;
    }
}

JSON Configuration Management

Load and manage application configuration from a JSON file:

#include <consolix/components.hpp>
 
struct AppConfig {
    std::string app_name;
    int max_connections;
};
 
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(AppConfig, app_name, max_connections)
 
int main() {
    // Load configuration from a JSON file
    consolix::add<consolix::ConfigComponent<AppConfig>>("config.json");
 
    // Access the configuration
    auto& config = consolix::get_service<AppConfig>();
    std::cout << "App Name: " << config.app_name << "\n";
    std::cout << "Max Connections: " << config.max_connections << "\n";
}

Custom Loop Example

Define and use a custom execution loop:

#include <consolix/components.hpp>
 
int main() {
    consolix::add<consolix::LoopComponent>(
        []() -> bool {
            std::cout << "Initialization complete.\n";
            return true;
        },
        []() {
            std::cout << "Executing loop iteration.\n";
            std::this_thread::sleep_for(std::chrono::seconds(1));
        },
        [](int signal) {
            std::cout << "Shutting down on signal: " << signal << "\n";
        }
    );
 
    consolix::run();
}

On POSIX systems, a termination signal only requests shutdown. The on_shutdown callback above still runs later in the normal application flow rather than inside the signal handler.

Resource Cleanup and Worker Shutdown

Use on_shutdown(int) for controlled shutdown logic such as stopping background threads, joining them, and then releasing owned resources:

class ShutdownAndResourcesDemo final : public consolix::BaseLoopComponent {
public:
    bool on_once() override {
        m_resource.reset(new WorkerResource("background-worker"));
        m_worker = std::thread(&ShutdownAndResourcesDemo::worker_loop, this);
        return true;
    }
 
    void on_loop() override {
        if (++m_tick_count >= 5) {
            consolix::stop();
        }
    }
 
    void on_shutdown(int signal) override {
        m_worker_stop.store(true);
        if (m_worker.joinable()) {
            m_worker.join();
        }
        m_resource.reset();
    }
 
private:
    std::thread m_worker;
    std::unique_ptr<WorkerResource> m_resource;
    std::atomic<bool> m_worker_stop{false};
    std::atomic<unsigned> m_heartbeats{0};
    std::atomic<int> m_tick_count{0};
};

This is the recommended lifecycle pattern in Consolix:

• do not perform cleanup in the signal handler itself
• do not detach long-lived worker threads owned by a component
• request stop first, then join(), then release owned resources
• use consolix::stop() for cooperative shutdown from the normal execution path

See examples/example_shutdown_and_resources.cpp for the full runnable example.

Logging with LogIt

Use the integrated LoggerComponent to manage logging:

#define CONSOLIX_USE_LOGIT 1
#include <consolix/consolix.hpp>
 
int main() {
    consolix::add<consolix::LoggerComponent>();
 
    CONSOLIX_STREAM() << "This is an informational message.";
    LOGIT_PRINT_ERROR("This is an error message.");
 
    return 0;
}

Working with Path Utilities

Resolve paths relative to the executable directory:

#include <consolix/utils.hpp>
 
int main() {
    std::string relative_path = "config/settings.json";
    std::string absolute_path = consolix::resolve_exec_path(relative_path);
 
    std::cout << "Absolute Path: " << absolute_path << std::endl;
}