Singleton Template Class

Overview

The Singleton template class provides a thread-safe singleton pattern implementation with optional threading support and lifecycle management. This class is part of the springtail namespace and is designed to ensure that only one instance of a derived class exists throughout the application’s lifetime.

Features

Thread-safe initialization using std::call_once
Optional threading support with automatic thread naming
Service registration integration with centralized shutdown management through ServiceRegistry
Protected lifecycle hooks for derived class customization
Deleted copy/move semantics to prevent duplication
Atomic shutdown flag for safe thread termination

Class Template

template <typename T>
class Singleton

The template parameter T should be the derived class that inherits from Singleton<T> (CRTP pattern).

Public Interface

Static Methods

`get_instance()`

static T* get_instance()

Returns the singleton instance of type T. Creates the instance on first call using thread-safe initialization. Returns: Pointer to the singleton instance Thread Safety: Yes Example:

MyService* service = MyService::get_instance();

`shutdown()`

static void shutdown()

Performs cleanup and destruction of the singleton instance. Can be called multiple times safely (only executes once). This method:

Sets the shutdown flag
Signals thread termination if a thread exists
Joins the thread
Calls internal cleanup
Deletes the instance

Thread Safety: Yes

Instance Methods

`start_thread()`

void start_thread()

Starts a dedicated thread for the singleton instance. The thread executes the _internal_run() method. Thread name is automatically set based on the service ID or type name. Example:

MyService::get_instance()->start_thread();

Protected Interface

Derived classes should override these methods to customize behavior:

`_internal_run()`

virtual void _internal_run()

Main execution function for the singleton’s thread. Must be overridden if start_thread() is used. Should periodically check _is_shutting_down() to enable graceful termination. Example:

void _internal_run() override {
    while (!_is_shutting_down()) {
        // Perform work
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
    }
}

`_internal_thread_shutdown()`

virtual void _internal_thread_shutdown()

Called during shutdown before the thread is joined. Use this to wake up blocking operations (e.g., notify condition variables). Example:

void _internal_thread_shutdown() override {
    _condition.notify_all();
}

`_internal_shutdown()`

virtual void _internal_shutdown()

Called during shutdown after the thread has been joined. Use this for cleanup of resources. Example:

void _internal_shutdown() override {
    _connection.close();
}

`_is_shutting_down()`

bool _is_shutting_down() const

Returns whether the singleton is in the shutdown process. Returns: true if shutting down, false otherwise

Constructor

explicit Singleton(ServiceId service_id = ServiceId::ServiceInvalidId)

Protected constructor that can only be called by derived classes. Optionally registers the service for centralized shutdown management. Parameters:

service_id: Service identifier for registration (default: ServiceId::ServiceInvalidId)

Static Utility Methods

`_assert_instance()`

static void _assert_instance()

Asserts that the singleton instance has been created. Terminates if not.

`_has_instance()`

static bool _has_instance()

Checks if the singleton instance exists. Returns: true if instance exists, false otherwise

ServiceId Enum

ServiceId uniquely identifies a logical service within the Springtail system. These identifiers are used for:

Dependency ordering
Thread naming
Coordinated shutdown
Service registration

The ServiceId enum defines service identifiers for various components in the system:

enum class ServiceId : int32_t {
    ServiceInvalidId = -1,
    ServiceRegisterId = 0,
    DatabaseMgrId,
    UserMgrId,
    ProxyServerId,
    // ... additional service IDs
    ServiceCountId
}

ServiceInvalidId is reserved for non-registered or internal services.

Helper Functions

`get_type_name<T>()`

template <typename T>
std::string get_type_name()

Extracts the type name from compiler-generated strings. Returns: String representation of type T

Service Registration

void springtail_register_service(ServiceId service_id, ShutdownFunc fn)
const std::string& springtail_get_service_name(ServiceId id)

Functions for registering services and retrieving service names.

`springtail_register_service()`

Registers a service shutdown callback with the global service registry.

Services are shut down in dependency order.
Registration is idempotent and enforced per service ID.
Typically invoked automatically by Singleton.

Registered shutdown functions are executed during springtail_shutdown().

`springtail_get_service_name()`

Returns a human-readable name for a given ServiceId. Used for:

Logging
Thread naming
Debug output

If a service ID is invalid, "Invalid" is returned.

Singleton Framework

The Singleton<T> template provides a thread-safe, lifecycle-aware singleton implementation designed for long-lived system services.

Key Properties

Lazy exactly-once initialization
Exactly-once shutdown
Optional background thread
Dependency-aware cleanup
Integrated with service registry

Singleton Lifecycle

Instance Creation

The instance is created on first call to get_instance().
Creation is guarded by std::call_once.
The derived class must have a default constructor.

Thread Management

Singletons may optionally run a dedicated thread. To enable threading:

Call start_thread().
Implement _internal_run().

Thread behavior:

Thread name is derived from ServiceId.
If no valid ServiceId exists, the type name is used.
Names are truncated to 15 characters to satisfy pthread limits.

Shutdown Semantics

Shutdown is global and idempotent. When shutdown() is called:

_shutting_down is set to true.
_internal_thread_shutdown() is invoked.
The thread is joined (if started).
_internal_shutdown() is invoked.
The instance is destroyed.

Shutdown occurs exactly once, even if called multiple times.

Overrides in Derived Classes

Derived classes may need to implement overrides for the following hooks. Some of these functions are for running and shutting down the internal thread, while another is simply for internal shutdown.

`_internal_run`

Executed in the background thread. Must be overridden if start_thread() is used.

`_internal_thread_shutdown`

Used to wake or unblock the background thread prior to joining. Typical use cases:

Notifying condition variables
Closing file descriptors
Signaling event loops

It does not have to be overriden, but if it is, it should signal termination for the thread run by this singleton service.

`_internal_shutdown`

Final cleanup hook. Used for:

Releasing resources
Stopping dependent components
Final state updates

If there are other threads owned by this service, this is the place to signal their termination and join them.

Shutdown State Checking

`_is_shutting_down`

Returns true if shutdown has been initiated. Intended for use inside _internal_run() loops to allow cooperative termination.

Constructor Behavior

The Singleton constructor accepts an optional ServiceId. If a valid ServiceId is provided:

The service is automatically registered for shutdown.
The shutdown order is dependency-aware and is a part of the initialization framework.

Default value for service id is ServiceInvalidId. This value ensures that the service won’t be registered with initialization framework. It will be up to the user to figure out when and how to invoke shutdown() function.

Type Name Utility

`get_type_name<T>`

Returns a demangled type name extracted from __PRETTY_FUNCTION__. Used internally for:

Thread naming fallback
Diagnostics

Not intended as a stable ABI feature.

Typical Usage Pattern

Define a service class inheriting from Singleton<T>.
If you want this class to be a part of the global shutdown sequence, then you need to do the following:

create a new service id in ServiceId enum
in the constructor pass this new service id to Singleton constructor
in init.cc file, setup dependencies for this service on the other existing services, for the very least it should depend on ServiceRegisterId because this is the id of the service that provides initialization and shutdown for Springtail base functionality
in init.cc file, add the name of the new service to service names map dependencies_names

Optionally start a background thread.
Let the framework manage lifecycle and shutdown if the service id is assigned, otherwise manage it yourself.

Shutdown is coordinated globally via springtail_shutdown(). Here is the usage example.

class MyService : public springtail::Singleton<MyService> {
    friend class springtail::Singleton<MyService>;

protected:
    MyService() : Singleton(springtail::ServiceId::MyServiceId) {
        // Initialize your service
    }

    void _internal_run() override {
        while (!_is_shutting_down()) {
            // Process work
            process_requests();
            std::this_thread::sleep_for(std::chrono::milliseconds(100));
        }
    }

    void _internal_thread_shutdown() override {
        // Wake up any blocking operations
        _request_queue.notify_all();
    }

    void _internal_shutdown() override {
        // Cleanup resources
        _cleanup();
    }

public:
    void process_request(const Request& req) {
        // Public API
    }

private:
    void process_requests() {
        // Internal processing
    }
};

// Usage
int main() {

    springtail_init(false);

    // Get instance and start thread
    MyService::get_instance()->start_thread();
    
    // Use the service
    MyService::get_instance()->process_request(request);
    
    // Shutdown (typically called from a signal handler)
    springtail_shutdown();
}

Thread Safety

Instance creation is thread-safe via std::call_once
Shutdown is thread-safe via std::call_once
The _shutting_down flag is atomic for safe cross-thread access
Derived classes are responsible for their own thread-safety

Design Considerations

No double initialization
No double shutdown
Deterministic shutdown order
Thread-safe lifecycle transitions
No dependency cycles allowed
Uses the Curiously Recurring Template Pattern (CRTP) for static polymorphism
Derived classes should friend Singleton<T> to allow private constructor access
All copy and move operations are explicitly deleted
Instance is created on first get_instance() call
Services can self-register for centralized shutdown

This framework is designed for:

Long-lived system services
Daemons and infrastructure components
Deterministic startup/shutdown

Documentation Index

​Singleton Template Class

​Overview

​Features

​Class Template

​Public Interface

​Static Methods

​get_instance()

​shutdown()

​Instance Methods

​start_thread()

​Protected Interface

​_internal_run()

​_internal_thread_shutdown()

​_internal_shutdown()

​_is_shutting_down()

​Constructor

​Static Utility Methods

​_assert_instance()

​_has_instance()

​ServiceId Enum

​Helper Functions

​get_type_name<T>()

​Service Registration

​springtail_register_service()

​springtail_get_service_name()

​Singleton Framework

​Key Properties

​Singleton Lifecycle

​Instance Creation

​Thread Management

​Shutdown Semantics

​Overrides in Derived Classes

​_internal_run

​_internal_thread_shutdown

​_internal_shutdown

​Shutdown State Checking

​_is_shutting_down

​Constructor Behavior

​Type Name Utility

​get_type_name<T>

​Typical Usage Pattern

​Thread Safety

​Design Considerations