Singleton Pattern

Creational pattern for thread-safe resource management

Overview

Category

Creational Design Pattern

Purpose

Ensure single instance of expensive resources

---

Problem Statement

The Challenge

Creating database connections for every request is:

Issue	Impact
Resource-intensive	Exhausts connection pool
Slow	TCP handshake 50-100ms per connection
Dangerous	Can crash database server

Thread Safety

We use Double-Check Locking pattern:

1. First check (no lock) - Fast path for already-initialized case
2. Acquire lock - Slow path for initialization
3. Second check (with lock) - Prevent race conditions

---

Solution: Lazy Singleton

MongoDB Singleton

class MongoDB:
    def __init__(self):
        self._client: AsyncIOMotorClient | None = None
        self._db = None
        self._initialized = False
    
    @property
    def client(self) -> AsyncIOMotorClient:
        if self._client is None:
            raise RuntimeError("MongoDB not connected")
        return self._client

# Global Singleton Instance
db = MongoDB()

async def connect_to_mongo():
    """Called once at application startup"""
    db._client = AsyncIOMotorClient(connection_string)
    db._initialized = True

OllamaClient Singleton

_ollama_client_instance: Optional[OllamaClient] = None
_ollama_client_lock = threading.Lock()

def get_ollama_client() -> OllamaClient:
    global _ollama_client_instance
    
    # Fast path (no lock)
    if _ollama_client_instance is not None:
        return _ollama_client_instance
    
    # Slow path (with lock)
    with _ollama_client_lock:
        if _ollama_client_instance is None:
            _ollama_client_instance = OllamaClient(
                base_url=settings.OLLAMA_BASE_URL
            )
    
    return _ollama_client_instance

UML Diagram

File Locations

Singleton	File
MongoDB	db/mongo.py
OllamaClient	clients/ollama_client.py

Async Fix: The OllamaClient.generate() uses run_in_executor to run blocking SDK calls in a thread pool, preventing Event Loop blocking.

---

Benefits

Connection Pooling

Motor client manages pool of connections

Resource Efficiency

One initialization, reused across requests

Thread Safety

Double-check locking prevents race conditions

Fail-Fast

Errors at startup, not during requests