Thread-Safe Singleton with `std::call_once`

1. The Singleton Pattern: A Single Point of Access

The core idea of the Singleton is straightforward. To enforce that only one instance of a class can exist, we must take control of its creation. We do this by:

1. Making the constructor private (or protected).
2. Deleting the copy constructor and copy assignment operator to prevent duplicates.
3. Providing a public static method (commonly named getInstance()) that creates the instance if it doesn't exist and returns a reference or pointer to it.

Here is a basic, single-threaded implementation:

class Logger {
public:
    // 3. Public static method to get the instance
    static Logger* getInstance() {
        if (instance == nullptr) {
            instance = new Logger();
        }
        return instance;
    }

    void log(const std::string& message) {
        // Implementation for logging...
        std::cout << "LOG: " << message << std::endl;
    }

    // 2. Delete copy operations
    Logger(const Logger&) = delete;
    Logger& operator=(const Logger&) = delete;

private:
    // 1. Private constructor
    Logger() = default;
    
    // Static pointer to the single instance
    static Logger* instance;
};

// Initialize the static member
Logger* Logger::instance = nullptr;

// Usage:
// Logger::getInstance()->log("Application started.");

This works perfectly fine in a single-threaded program. But as you know from our previous discussions, the moment we introduce multiple threads, this code becomes dangerously broken.

2. The Problem: A Race to Initialize

Consider what happens when two threads call Logger::getInstance() at roughly the same time:

1. Thread A calls getInstance(), sees instance is nullptr, and passes the if check.
2. The OS preempts Thread A and schedules Thread B.
3. Thread B calls getInstance(), also sees instance is nullptr, and passes the if check.
4. Thread B executes new Logger(), creating an object, and assigns its address to instance.
5. The OS schedules Thread A again. It resumes from where it left off, inside the if block.
6. Thread A executes new Logger(), creating a second object, and assigns its address to instance, overwriting the pointer from Thread B.

This is a classic data race. The result is a memory leak (the object created by Thread B is lost forever) and a violation of the Singleton's core guarantee.

3. Attempt #1: The Naive Lock

The most obvious way to fix the race condition is to use a mutex. In the article "Thread-Safe Initialization of a Singleton" from Modernes C++, you can see a direct implementation of this idea.

The code you reviewed looks something like this:

// Simplified from the article
class MySingleton {
public:
    static MySingleton& getInstance() {
        std::lock_guard<std::mutex> myLock(myMutex); // Lock every time
        if (!instance) {
            instance = new MySingleton();
        }
        return *instance;
    }
private:
    // ... private constructor, deleted copy ops ...
    static MySingleton* instance;
    static std::mutex myMutex;
};

This is correct and thread-safe. However, it's inefficient. After the Singleton is initialized, the if (!instance) check will always be false. Yet, every single call to getInstance() must acquire and release the mutex. This introduces unnecessary contention and overhead, especially in a high-throughput system. We're paying the full cost of a lock (which can involve system calls) on every call, even though we only need synchronization for the very first one.

4. Attempt #2: The Modern C++ Solution with std::call_once

To solve the performance problem of the naive lock, we need a mechanism that performs the expensive synchronization only once. This is precisely what std::call_once is designed for. It guarantees that a given callable (like a function or lambda) will be executed exactly once, even if called concurrently from multiple threads.

std::call_once works with an associated std::once_flag.

Let's break down the pattern you just saw:

#include <mutex> // for std::call_once, std::once_flag

class MySingleton {
public:
    static MySingleton& getInstance() {
        // Guarantees initSingleton() is called exactly once
        std::call_once(initInstanceFlag, &MySingleton::initSingleton);
        return *instance;
    }

private:
    MySingleton() = default;
    ~MySingleton() = default;
    MySingleton(const MySingleton&) = delete;
    MySingleton& operator=(const MySingleton&) = delete;

    // The function to be called once
    static void initSingleton() {
        instance = new MySingleton();
    }

    static MySingleton* instance;
    static std::once_flag initInstanceFlag; // The flag for call_once
};

// Static member definitions
MySingleton* MySingleton::instance = nullptr;
std::once_flag MySingleton::initInstanceFlag;

How it works:

• When getInstance() is called, it invokes std::call_once.
• The first thread to reach this line will execute the initSingleton function and "flip" the initInstanceFlag.
• Any other threads that arrive while the first thread is busy in initSingleton will block until it completes.
• Once initSingleton has finished, all blocking threads are unblocked, and all subsequent calls to getInstance() will see that the flag has been flipped and will return immediately without executing initSingleton or blocking.

This gives us the best of both worlds: thread safety and performance. The fast path (after initialization) involves only a cheap check on the state of the once_flag.

5. Under the Hood: How is std::call_once Implemented?

Your interest is in the "how," so let's dig deeper. How can the standard library implement std::call_once? It's essentially a well-implemented version of the Double-Checked Locking Pattern (DCLP).

As the article explains, a std::once_flag can be thought of as a struct containing a std::mutex and a std::atomic<bool>. The call_once logic then follows the DCLP structure:

// Conceptual implementation based on the article
template<typename Callable, typename... Args>
void call_once(once_flag& flag, Callable&& f, Args&&... args) {
    // 1. First check: Fast, non-locking atomic read.
    // This is the path taken for all calls after initialization.
    if (flag.has_run.load(std::memory_order_acquire)) {
        return;
    }

    // 2. Slow path: acquire a lock
    std::lock_guard<std::mutex> lock(flag.m);

    // 3. Second check: Another thread might have finished
    // initialization while we were waiting for the lock.
    if (flag.has_run.load(std::memory_order_acquire)) {
        return;
    }
    
    // 4. Execute the callable and set the flag.
    // The memory order ensures this write is visible before the lock is released.
    f(std::forward<Args>(args)...);
    flag.has_run.store(true, std::memory_order_release);
}

(Note: Real-world implementations are more complex, often using OS-specific primitives like futexes for better performance, but this captures the essential logic.)

This implementation beautifully illustrates the performance characteristics: the vast majority of calls hit the fast path in step 1. Only the very first few threads to arrive will enter the slow, locking path in step 2. The double-check in step 3 prevents redundant work. Also, standard implementations of std::call_once are exception-safe: if f() throws, the flag is not set, allowing another thread to attempt initialization.

6. The Ultimate Simplification: The "Meyers Singleton"

Since C++11, there is an even simpler way to write a thread-safe Singleton that relies on language guarantees. It's often called the "Meyers Singleton," after Scott Meyers who popularized it.

The entire implementation boils down to this:

class MySingleton {
public:
    static MySingleton& getInstance() {
        // The static variable is only initialized once, on first access.
        // C++11 guarantees this initialization is thread-safe.
        static MySingleton instance; 
        return instance;
    }
private:
    MySingleton() = default;
    ~MySingleton() = default;
    MySingleton(const MySingleton&) = delete;
    MySingleton& operator=(const MySingleton&) = delete;
};

That's it. The C++11 standard guarantees that the initialization of a function-local static variable is performed only once. If multiple threads attempt to call getInstance() concurrently, the compiler and runtime system ensure that only one thread will execute the initialization of instance, and all other threads will wait.

Under the hood, the compiler generates code that is functionally equivalent to using std::call_once or platform-specific DCLP mechanisms. On Linux with GCC/Clang, this typically involves the compiler emitting calls to guard functions in the C++ ABI, like __cxa_guard_acquire and __cxa_guard_release, which use a hidden flag variable to manage the thread-safe initialization. You get all the safety and performance without any of the boilerplate.

Conclusion

In this lesson, we explored the Singleton pattern and the critical challenge of making it thread-safe. We saw how a naive implementation fails and how simple locking is inefficient.

Key Takeaways:

• The Singleton pattern ensures a class has only one instance, which is crucial for managing global resources.
• Lazy initialization of a Singleton in a multithreaded environment is prone to race conditions.
• std::call_once is the standard, robust, and efficient C++ primitive for "initialize-once" logic. It is essentially a library-provided, correct implementation of the Double-Checked Locking Pattern.
• The Meyers Singleton (using a function-local static variable) is the simplest and often preferred method in modern C++. It relies on language guarantees for thread-safe initialization, effectively hiding the complexity of std::call_once from the developer.

You have now applied your knowledge of concurrency to a common architectural pattern, moving up the stack from raw primitives to reusable design solutions.

In our next lesson, we will explore the Factory Method pattern. While the Singleton is about restricting object creation to a single instance, the Factory Method is about delegating the responsibility of which concrete class to create to subclasses, giving your programs more flexibility.