Summary

Establish standardized singleton pattern guidelines for the entire kcenon ecosystem to prevent Static Destruction Order Fiasco (SDOF) issues across all systems.

Background

Multiple systems in the kcenon ecosystem use singleton patterns for various managers and loggers. The interaction between these singletons during static destruction has caused recurring issues:

• network_system#301: CI failures due to SDOF
• network_system#302, docs: Standardize BASELINE.md location across all ecosystem systems #304: io_context_thread_manager SDOF
• thread_system#293, refactor(utils): extract generic enum serialization template #295: thread_logger and thread_pool SDOF

Problem Statement

When multiple systems are integrated (e.g., network_system with thread_system), their singletons can be destroyed in unpredictable order, leading to:

• free(): invalid pointer crashes
• Accessing destroyed objects
• Undefined behavior during process termination

Affected Singletons (Known)

Proposed Guidelines

1. Default Pattern: Intentional Leak for Infrastructure Singletons

class MySingleton {
public:
    static MySingleton& instance() {
        // Intentionally leak to avoid SDOF
        static MySingleton* instance = new MySingleton();
        return *instance;
    }
    
    // Optional: explicit shutdown for resource cleanup
    static void shutdown() {
        // ... cleanup logic (logging, flushing, etc.)
    }
    
private:
    MySingleton() = default;
    ~MySingleton() = default;  // Never called
};

2. When Intentional Leak is Required

• Loggers and logging infrastructure
• Thread pools and async managers
• Any singleton that might be accessed during other objects' destruction
• Global managers that coordinate cross-system resources

3. When Meyer's Singleton is Acceptable

• Pure data singletons with no dependencies
• Configuration managers that are only read during initialization
• Singletons that are guaranteed to be destroyed last

4. Documentation Requirements

Each singleton should document:

1. Why this pattern was chosen
2. Memory implications
3. Shutdown procedure (if any)

5. Static Destruction Safety Checklist

For new singletons, verify:

• No logging calls in destructor
• No access to other singletons in destructor
• No thread operations in destructor
• Consider Intentional Leak if any of the above are needed

Implementation Plan

Phase 1: Audit (All Systems)

• Audit all singleton patterns in common_system
• Audit all singleton patterns in thread_system
• Audit all singleton patterns in logger_system
• Audit all singleton patterns in container_system
• Audit all singleton patterns in network_system
• Audit all singleton patterns in monitoring_system

Phase 2: Documentation

• Create SINGLETON_GUIDELINES.md in common_system
• Document each singleton's pattern choice
• Add code review checklist

Phase 3: Migration

• Migrate problematic singletons to Intentional Leak pattern
• Add shutdown() methods where explicit cleanup is needed
• Update CI to detect SDOF issues early

Acceptance Criteria

• SINGLETON_GUIDELINES.md created in common_system
• All systems audited for singleton patterns
• Problematic singletons identified and tracked
• CI passes across all integrated systems

Related Issues

thread_system

• refactor: Extract generic enum serialization template to eliminate duplication #293: thread_logger Intentional Leak (CLOSED)
• refactor(utils): extract generic enum serialization template #295: thread_pool SDOF prevention (NEW)

network_system

• refactor(adapters): consolidate adapter utilities into unified template #301: CI standardization (blocked by SDOF)
• refactor(error): add decentralized error category infrastructure #302: io_context_thread_manager safe destruction
• docs: Standardize BASELINE.md location across all ecosystem systems #304: io_context_thread_manager Intentional Leak (NEW)

References

• C++ Core Guidelines I.3: Avoid singletons
• Static Initialization Order Fiasco
• Intentional Leak Pattern (Google C++ Style Guide)