Summary

Establish ecosystem-wide guidelines for implementing singletons and managing static objects to prevent Static Destruction Order Fiasco (SDOF) across all kcenon system libraries.

Background

The Problem

Multiple ecosystem projects have encountered SDOF issues during process termination:

• thread_system#293, refactor(utils): extract generic enum serialization template #295, refactor(logging): consolidate LOG_* macros with variadic dispatch #296 - thread_logger and thread_pool SDOF
• network_system#302, docs: Standardize BASELINE.md location across all ecosystem systems #304, docs: Create documentation structure guidelines template for ecosystem #305, docs(contributing): add documentation structure guidelines for ecosystem #306 - io_context_thread_manager and basic_thread_pool SDOF
• Symptoms: free(): invalid pointer, heap corruption, crash on Ubuntu CI

Current Ad-hoc Solutions

Different projects have applied various solutions independently:

1. Intentional Leak pattern - Don't destroy singletons
2. atexit handlers - Set shutdown flags before destruction
3. Defensive checks - Skip operations if shutting down

Without unified guidelines, each project reinvents solutions, leading to:

• Inconsistent implementations
• Missed edge cases
• Difficulty maintaining cross-project compatibility

Proposed Guidelines

1. Singleton Pattern Selection

2. Intentional Leak Pattern Template

class MySingleton {
public:
    static MySingleton& instance() {
        // Intentionally leak to avoid SDOF.
        // Memory is reclaimed by OS on process termination.
        // This singleton may be accessed during other singletons' destruction.
        static MySingleton* instance = new MySingleton();
        return *instance;
    }
    
    // Optional: Explicit shutdown for graceful cleanup before exit
    static void prepare_shutdown() {
        // Set flags, flush buffers, etc.
        // Called via atexit or explicitly by application
    }

private:
    MySingleton() {
        // Register shutdown handler early
        std::atexit(prepare_shutdown);
    }
};

3. shared_ptr with No-op Deleter

For objects managed by shared_ptr that may outlive static destruction:

auto* obj = new MyClass();
auto ptr = std::shared_ptr<MyClass>(
    obj,
    [](MyClass*) { /* no-op deleter - intentional leak */ }
);

4. Documentation Requirements

Each singleton should document:

1. Why the pattern was chosen
2. Memory impact (typically ~few KB)
3. Shutdown behavior (what happens at process exit)
4. Thread safety guarantees

5. Testing Requirements

• Test with Address Sanitizer (ASan)
• Test with Thread Sanitizer (TSan)
• Verify no SDOF on Ubuntu (strictest glibc checks)

Proposed Location

Add guidelines document to common_system:

• docs/SINGLETON_GUIDELINES.md - Full documentation
• include/kcenon/common/patterns/singleton.h - Optional template implementations

Acceptance Criteria

• Create SINGLETON_GUIDELINES.md in common_system
• Document Intentional Leak pattern with code examples
• Document when to use Meyer's Singleton vs Intentional Leak
• Add shared_ptr no-op deleter pattern documentation
• Reference from thread_system and network_system READMEs
• Optional: Provide template implementations

Benefits

1. Consistency: All ecosystem projects follow same patterns
2. Maintainability: Single source of truth for SDOF prevention
3. Onboarding: Clear guidelines for new contributors
4. Debugging: Easier to identify SDOF issues when patterns are documented

Related Issues

• thread_system#293, refactor(utils): extract generic enum serialization template #295, refactor(logging): consolidate LOG_* macros with variadic dispatch #296, refactor: Extract common validation and error handling patterns in service_container to eliminate duplication #297
• network_system#302, docs: Standardize BASELINE.md location across all ecosystem systems #304, docs: Create documentation structure guidelines template for ecosystem #305, docs(contributing): add documentation structure guidelines for ecosystem #306
• This issue was referenced in network_system#302 as common_system#197

References

• C++ Core Guidelines I.3: Avoid singletons
• Static Destruction Order Fiasco
• Meyers Singleton and Thread Safety