The Prime Mover: Thread-Safe Metaclass Singleton in Python
A bulletproof, thread-safe implementation of the Gang of Four Singleton pattern in Python using a custom Metaclass and double-checked locking—guaranteeing singular object instantiation across concurrent worker threads.
✧ GANG OF FOUR LINEAGE & ARCANUM ✧
GOF DESIGN PATTERN: Singleton Pattern (Creational)
ARCANUM SCHOOL: Thaumaturgy // The Prime Mover Metaclass
SCRIBE / ARCHON: Joshua Edward McLaughlin Cox
CANONICAL REGISTRATION:
// EXECUTABLE PYTHON PATTERN //
import threading
class SingletonMeta(type):
_instances = {}
_lock = threading.Lock()
def __call__(cls, *args, **kwargs):
if cls not in cls._instances:
with cls._lock:
if cls not in cls._instances:
cls._instances[cls] = super().__call__(*args, **kwargs)
return cls._instances[cls]
class ArcaneDatabase(metaclass=SingletonMeta):
def __init__(self, uri="sqlite:///:memory:"):
self.uri = uri
The Lineage to the Gang of Four Singleton
In 1994, the Gang of Four defined the Singleton Pattern:
“Ensure a class only has one instance, and provide a global point of access to it.” — Design Patterns, p. 127
In Python, developers often attempt to implement Singletons by overriding __new__:
# ⚠️ THE FLAWED __new__ SINGLETON
class FlawedSingleton:
_instance = None
def __new__(cls, *args, **kwargs):
if not cls._instance:
cls._instance = super().__new__(cls)
return cls._instance
def __init__(self, count):
self.count = count # BUG: __init__ runs on EVERY call, overwriting state!
This naive approach suffers from two severe defects:
- Re-initialization Hazard: Python invokes
__init__every single timeFlawedSingleton()is called, even when__new__returns the existing cached instance. - Race Condition Hazard: In multi-threaded environments, two threads checking
if not cls._instance:simultaneously will instantiate two distinct objects.
By ascending to the level of the Metaclass (type), we intercept object creation in __call__ before __new__ and __init__ are invoked, combined with double-checked locking for optimal concurrency.
The Complete Python Script
#!/usr/bin/env python3
"""
PATTERN: Singleton Pattern (Gang of Four Creational)
ARCANUM: Thaumaturgy // The Prime Mover Metaclass
DESCRIPTION: Thread-safe, non-reinitializing Singleton via Metaclass __call__.
"""
import threading
import time
from typing import Any, Dict
class SingletonMeta(type):
"""
The Metaclass is the class of a class.
By overriding __call__, we control what happens when a class is instantiated.
"""
_instances: Dict[Any, Any] = {}
_lock: threading.Lock = threading.Lock()
def __call__(cls, *args, **kwargs) -> Any:
# First check (without lock overhead for fast-path reads)
if cls not in cls._instances:
with cls._lock:
# Second check (inside lock to prevent race conditions)
if cls not in cls._instances:
instance = super().__call__(*args, **kwargs)
cls._instances[cls] = instance
return cls._instances[cls]
class ArcaneDatabaseConnection(metaclass=SingletonMeta):
"""A singleton database connection pool."""
def __init__(self, connection_string: str = "sqlite:///vault.db") -> None:
# This __init__ block runs EXACTLY ONCE across the lifetime of the process!
print(f"[THAUMATURGY INCEPTION] Initializing connection to: {connection_string}")
self.connection_string = connection_string
self.created_at = time.time()
self.query_count = 0
def execute(self, query: str) -> str:
self.query_count += 1
return f"[EXEC #{self.query_count}] {query} on {self.connection_string}"
def test_concurrent_instantiation():
"""Verify that 10 concurrent threads receive the exact same memory instance."""
instances = []
def worker(thread_id: int):
time.sleep(0.01) # Induce thread interleaving
db = ArcaneDatabaseConnection(f"sqlite:///vault_{thread_id}.db")
instances.append(db)
threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
t.start()
for t in threads:
t.join()
# Assert that all 10 threads obtained the exact same object reference
first = instances[0]
all_identical = all(inst is first for inst in instances)
print("\n--- VERIFICATION TELEMETRY ---")
print(f"Total Threads Spawned: {len(instances)}")
print(f"Unique Memory Addresses: {len(set(id(x) for x in instances))}")
print(f"Initial Connection URI: {first.connection_string}")
print(f"Singleton Invariant: {'PASS (100% Identity)' if all_identical else 'FAIL'}")
print(first.execute("SELECT * FROM grimoire_secrets"))
if __name__ == "__main__":
test_concurrent_instantiation()
Why Metaclass Singleton Wins
Call: ArcaneDatabaseConnection("...")
│
▼
SingletonMeta.__call__
│
▼
Is cls in _instances?
├── YES ──▶ Return existing instance (Zero lock overhead, __init__ skipped!)
│
└── NO ──▶ Acquire threading.Lock()
│
▼
Is cls still not in _instances?
├── YES ──▶ super().__call__() -> __new__() -> __init__()
│ Save to _instances[cls]
│
└── NO ──▶ Return existing instance
- Zero Repeated
__init__Calls: Sincesuper().__call__is only executed when the instance is created, initialized attributes are never wiped out by subsequent calls. - Double-Checked Locking: Once the Singleton is instantiated, 99.99% of subsequent accesses bypass the mutex lock entirely, preserving multi-core throughput.
- Inheritance Cleanliness: Any class can inherit the Singleton property simply by specifying
metaclass=SingletonMeta.
Runic Tags:
#python
#python3
#singleton
#metaclass
#concurrency
#thread-safety
#gof-patterns
#thaumaturgy