Singleton Pattern: One Principal for the Whole School

🎯 One school, one principal

Welcome to Green Valley School. It has hundreds of students, dozens of teachers, many classrooms, two playgrounds — but how many principals?

Exactly one. Her name is Principal Meena Madam.

There is one Principal Madam, one principal's office on the first floor, and one official notice board outside that office, polished daily by Raju bhaiya, the school peon. When the school needs an important decision — exam dates, holiday announcements, permission for the annual function — everyone goes to that same office. Anita Madam (maths) goes there. Vikram Sir (sports) goes there. Even little Pinky from Class 6A goes there when she wants permission for the science club. Nobody says, "Let me quickly appoint my own second principal for my class." Two principals announcing two different exam dates? Total chaos. Impossible!

Notice three things about how Green Valley manages this:

1. You cannot create a principal yourself. There is no shop where Pinky can "buy" a new principal. The post is protected.
2. There is one well-known way to reach the principal. Everyone knows where the office is. You do not need someone to personally introduce you.
3. Whoever asks, gets the same principal. Class 6A and Class 10B both reach the very same person, the very same notice board.

This is the Singleton pattern in real life. One special object for the whole program, creation strictly controlled, and a single famous "door" through which everyone reaches it.

The same idea sits on the roof of Pinky's apartment building, Shanti Heights: one water tank serves every flat. Flat 101 and flat 504 open different taps, but the water comes from the same tank. If flat 302 wastes water, flat 101 feels it. One electricity meter per house (two meters would double-count your units!), one captain for a cricket team, one water tank per building — some things are correct only when there is exactly one.

Here is a normal Tuesday at Green Valley, as a journey:

Hold on to this school story. We will write the principal's office in code soon. And later — this is important — we will also discuss honestly why many senior developers say, "Use this pattern very, very carefully."

💡 What is the Singleton pattern?

The Singleton pattern is a creational design pattern. Here is its plain definition:

Singleton guarantees that a class has only one instance during the whole life of the program, and it provides a single global access point (usually a static method like getInstance()) to reach that instance.

So the class takes on two jobs at once:

• It controls its own creation. The constructor is hidden (made private), so no outside code can write new Principal(). The class creates its one instance itself — just like the school board, not the students, appoints Meena Madam.
• It provides access. A static method or property hands out that one instance to anyone who asks, from anywhere in the program — the famous office door on the first floor.

Singleton is one of the 23 classic patterns from the Gang of Four book (1994). It is the easiest pattern to learn and, funnily, also the most criticised pattern ever — we will see both sides today.

College corner: notice that Singleton quietly violates the Single Responsibility Principle by design. The class manages its own lifetime (job 1) and does its real work (job 2). That double duty is the seed of most later complaints: lifetime management belongs to the application's composition root or a container, not to the class itself. Keep this thought — it returns in the anti-pattern section.

⚠️ The problem it solves

Why would anyone need such a strange class? Two real needs push developers here.

Need 1: Some things must exist only once.

Imagine a program where every part creates its own database connection pool:

// The dangerous "everyone makes their own" way
class ReportService {
  private pool = new ConnectionPool(); // pool #1 (100 connections)
}
 
class BillingService {
  private pool = new ConnectionPool(); // pool #2 (another 100!)
}
 
class EmailService {
  private pool = new ConnectionPool(); // pool #3 (!!)
}
// The database planned for 100 connections... now faces 300.
// It starts rejecting connections. The app crashes at peak time.

A plain constructor cannot say "no" to a second call. Every new gives a fresh object. But for some resources — the log file, the parsed configuration, the connection pool, the cache — a second copy is not just wasteful, it is wrong. Two log objects writing to one file can mix their lines. Two settings objects can disagree with each other. Two principals can announce two different exam dates. Two water tanks on one roof with one inlet pipe? The plumber will laugh at you.

Need 2: That one thing must be reachable from many places.

The logger is needed in almost every file. Passing it by hand through fifty layers of constructors feels tiring. A global variable would be reachable — but globals are fragile: any code can overwrite them, and nothing guarantees they are initialised before first use.

Singleton tries to answer both needs in one stroke: hide the constructor (so only one instance can ever exist) and expose a static access door (so everyone can reach it).

How big is the waste, really? Look at the open connections when every service builds its own heavy pool versus everyone sharing one:

Ten services, each opening a 100-connection pool, means one thousand connections hammering a database sized for one hundred. The shared pool keeps it at exactly one hundred. This chart is the whole business case for "exactly one instance".

🛠️ How it works, step by step

The recipe is small. You can write it in any language in five steps:

1. Make the constructor private. This locks the front door. Outside code can no longer write new Principal() — the compiler itself will refuse, like the school board rejecting Pinky's application to appoint her own principal.
2. Add a private static field inside the class to hold the single instance. It starts empty (null).
3. Add a public static method — traditionally named getInstance() — that everyone will call.
4. Inside getInstance(), create lazily. On the very first call, the instance does not exist yet, so create it and store it in the static field. On every later call, just return the stored one. "Lazy" means created only when first needed, not at program start.
5. Make it thread-safe if needed. If two threads call getInstance() at the exact same moment when the instance is still empty, both can pass the "is it null?" check and create two instances — breaking the whole promise! Languages give safe tools for this (we will see C#'s Lazy<T> below).

Note the funny self-arrow: the class holds an instance of itself in a static field. That is the signature of Singleton.

Watch what happens when two teachers visit, one after the other:

The whole lifetime of a singleton has only three interesting moments — not created yet, created on first demand, and then the same instance returned forever:

Look at the loop on SameInstanceReturned in Figure 6 — that loop is the entire promise of the pattern. After the first call, nothing new is ever created. And notice there is no arrow back to NotCreated: a classic singleton, once born, lives until the program dies. Remember this — it is also why tests struggle with it later.

🧪 Real-life code example: the principal's office in TypeScript

Let us code Green Valley School. Follow the comments.

// The one and only principal's office.
class PrincipalOffice {
  // Step 2: the private static field holding the single instance.
  // It is empty until someone first needs the office.
  private static instance: PrincipalOffice | null = null;
 
  // The official notice board (the office's state).
  private notices: string[] = [];
 
  // Step 1: PRIVATE constructor. Nobody outside can call `new`.
  private constructor() {
    console.log("🏫 Principal's office is being set up (runs only ONCE)...");
  }
 
  // Step 3 + 4: the public static door, with LAZY creation.
  public static getInstance(): PrincipalOffice {
    if (PrincipalOffice.instance === null) {
      // First visitor ever — set up the office now.
      PrincipalOffice.instance = new PrincipalOffice();
    }
    // Every visitor, first or later, gets the SAME office.
    return PrincipalOffice.instance;
  }
 
  public announce(notice: string): void {
    this.notices.push(notice);
    console.log(`📢 New notice: ${notice}`);
  }
 
  public readNotices(): string[] {
    return [...this.notices];
  }
}
 
// ---------- Client code: a normal school day ----------
 
// Anita Madam visits the office.
const officeForMaths = PrincipalOffice.getInstance();
officeForMaths.announce("Maths exam on Monday, 9 AM.");
 
// Vikram Sir visits "another" office... or does he?
const officeForSports = PrincipalOffice.getInstance();
officeForSports.announce("Annual sports day on 26 January.");
 
// Are these two different offices? Let's check!
console.log("Same office?", officeForMaths === officeForSports);
 
// Pinky reads the board — sees BOTH notices,
// because there is only ONE board in ONE office.
console.log("Notice board:", officeForSports.readNotices());
 
// And if someone naughty tries:  new PrincipalOffice();
// ❌ TypeScript error: Constructor of class 'PrincipalOffice' is private.

Expected output:

🏫 Principal's office is being set up (runs only ONCE)...
📢 New notice: Maths exam on Monday, 9 AM.
📢 New notice: Annual sports day on 26 January.
Same office? true
Notice board: [ 'Maths exam on Monday, 9 AM.', 'Annual sports day on 26 January.' ]

Read the output carefully — it proves all three promises:

1. The setup message printed only once, even though getInstance() was called twice. That is lazy creation: built on the first call, reused afterwards.
2. officeForMaths === officeForSports is true — both variables point to the same object in memory.
3. The notice from Anita Madam is visible to Vikram Sir and to Pinky, because everyone shares one notice board.

⚠️ What about two visitors at the exact same moment?

JavaScript and TypeScript normally run your code on a single thread, so two calls cannot truly collide — our simple if (instance === null) check is safe there.

But in languages like C#, Java, or C++, many threads run at once. Picture this race:

Thread A: checks instance — it is null      ─┐
Thread B: checks instance — it is also null ─┤ both passed the check!
Thread A: creates office #1                  │
Thread B: creates office #2                  │ ← TWO principals now! 😱

Two offices, two notice boards, total confusion — exactly what Singleton promised to prevent. The classic fixes are:

• Eager creation: build the instance at class-load time, before any thread can race. Simple and safe, but you lose laziness (it is built even if never used).
• Lock every call: take a lock before checking. Safe, but every call pays the locking cost forever.
• Double-checked locking: check first without the lock, lock only if still empty, check again inside. Fast — but famously easy to get subtly wrong without memory barriers.

College corner — why double-checked locking burned experts: the danger is not the logic, it is the memory model. The line instance = new PrincipalOffice() is not one atomic action; the compiler or CPU may reorder it into (1) allocate memory, (2) publish the pointer, (3) run the constructor. A second thread can then observe a non-null instance whose constructor has not finished — and happily use a half-built object. Java fixed this only when volatile got stronger semantics in the Java 5 memory model (JSR-133); C# needs volatile or careful use of Interlocked for the same reason. The safe modern idioms push the problem onto the runtime: C#'s Lazy<T> (which handles safe publication internally), Java's class-holder idiom (the JVM guarantees class initialisation is both lazy and thread-safe), Java's enum singleton, Go's sync.Once, Rust's OnceLock. The lesson generalises beyond Singleton: never hand-roll one-time initialisation from memory; use the language's blessed primitive.

The modern advice in one line: do not hand-roll this. Which brings us to C#.

🧪 The same idea in C# — thread-safe with Lazy<T>

C# gives a beautiful one-liner for safe lazy singletons. Lazy<T> guarantees the factory runs exactly once, even if a hundred threads ask at the same instant.

public sealed class PrincipalOffice
{
    // Lazy<T> creates the instance on FIRST access,
    // and .NET guarantees thread safety for us. No locks to write!
    private static readonly Lazy<PrincipalOffice> _lazy =
        new(() => new PrincipalOffice());
 
    public static PrincipalOffice Instance => _lazy.Value;
 
    private readonly List<string> _notices = new();
 
    // Private constructor: outside code cannot use `new`.
    private PrincipalOffice()
    {
        Console.WriteLine("Principal's office set up (only once).");
    }
 
    public void Announce(string notice) => _notices.Add(notice);
 
    public IReadOnlyList<string> ReadNotices() => _notices;
}
 
// Usage — from anywhere, on any thread:
PrincipalOffice.Instance.Announce("PTM on Saturday at 10 AM.");
 
var a = PrincipalOffice.Instance;
var b = PrincipalOffice.Instance;
Console.WriteLine(ReferenceEquals(a, b)); // True — the same office

sealed stops anyone from subclassing the singleton (a subclass could sneak in a second instance). static readonly plus Lazy<T> handles the entire thread-safety puzzle in one line. This is the idiomatic modern C# singleton.

And for completeness, the Python flavour. In Python, the most honest singleton is simply a module — Python imports every module exactly once and caches it, so module-level objects are natural singletons:

# water_tank.py — the module IS the singleton.
# Python runs this file only once, no matter how many files import it.
 
class _WaterTank:
    def __init__(self):
        self.level = 1000  # litres
 
    def use(self, litres: int) -> None:
        self.level -= litres
 
    def refill(self, litres: int) -> None:
        self.level += litres
 
# The one tank on the roof of Shanti Heights:
tank = _WaterTank()
 
# Any other file:
#   from water_tank import tank
#   tank.use(50)
# Everyone gets the same tank object — guaranteed by the import system.

No private constructor gymnastics needed. The import system already gives "create once, share everywhere". (Python folks also discuss the Borg/monostate idea in faif/python-patterns — many objects sharing one state — a fun cousin with the same dangers.)

💡 Where you see it in real software

Singleton (and "singleton-like" single instances) appear all over real systems:

• Application configuration. A program parses its settings file once and shares the result everywhere. Parsing twice wastes time; two disagreeing configs would be a bug.
• Loggers. Logging frameworks like Java's Log4j or Python's logging module hand you the same logger object for the same name every time — one shared writer per log destination, so log lines do not get mixed up.
• Database connection pools. The pool is sized to the database's limits, so there must be exactly one. Creating pools per-class is the classic outage story (remember Figure 3).
• Spring Framework beans (Java). Here is the interesting twist: in Spring, singleton is the default scope for every bean — one instance per container — but the container manages it and injects it into your classes. You get single-instance behaviour without writing getInstance() anywhere. This is widely considered the right modern way (more on this below).
• ASP.NET Core services. Same idea: services.AddSingleton<MyService>() registers a class with singleton lifetime in the DI container. One instance, but delivered through constructors, not global statics.
• Runtime objects. Java's Runtime.getRuntime() is a textbook Singleton shipped inside the JDK itself.
• Learning repositories. The iluwatar/java-design-patterns repo shows five Java variants (eager, lazy, double-checked, holder idiom, enum).

Which of these are truly unique by nature? In a typical backend codebase, the honest split looks something like this:

That last slice is the painful one — objects that someone made a singleton only for convenience. The next two sections are about exactly that slice.

📊 When to use it and when not to

Want it as a picture? Judge your case on two axes: how truly unique the resource is by nature, and how much its state changes:

A shopping cart as a singleton (bottom-left) is the classic disaster: every user would share one cart. A parsed, read-only config (top-right) is about as safe as singletons get.

⚠️ Why many seniors call Singleton an anti-pattern

Now the honest part. Ask any experienced developer about Singleton and you will see a careful frown. Singleton is the only GoF pattern that is routinely called an anti-pattern — a solution that looks helpful but quietly creates bigger problems. Important: the criticism is not against the idea of "one instance" (that is sometimes genuinely required — one water tank really is correct for one building). It is against the technique: a class giving global static access to itself.

Here are the four big complaints, in simple words:

1. It is global state in a fancy coat. For decades, programmers learned to avoid global variables — anything can read or change them from anywhere, so the program becomes impossible to reason about locally. A mutable singleton is exactly a global variable wearing a class costume. Change it in module A, and module Z mysteriously behaves differently. Debugging such "spooky action at a distance" eats whole evenings. In Shanti Heights language: if anyone in any flat can secretly open the tank's outlet valve, no single flat can ever explain why the water pressure dropped.

2. It hides dependencies. Look at this function:

function generateReportCard(student: Student): ReportCard {
  // ...looks like it depends only on `student`...
  const config = SchoolConfig.getInstance();  // surprise dependency!
  const logger = Logger.getInstance();        // another surprise!
  // ...
}

The signature says "give me a student, I give you a report card." It lies. The function secretly reaches out to two singletons. A reader cannot know the true dependencies without reading every line of the body. Constructors and parameters stop being honest contracts.

3. It makes testing painful. Good unit tests want a fresh, isolated world for every test. But a singleton is shared static state that survives between tests — remember Figure 6: there is no arrow back to NotCreated. Test 1 posts a notice; test 2 unexpectedly sees it; tests pass alone but fail together, in confusing order-dependent ways. Worse: you usually cannot substitute a fake. If OrderService internally calls PaymentGateway.getInstance(), then testing "place order" hits the real payment gateway. Ouch.

4. Thread-safety is easy to get wrong. As we saw, hand-rolled lazy creation has a race condition, and double-checked locking trapped even expert programmers for years. And after creation, the singleton's own mutable state still needs its own synchronisation — one notice board scribbled on by fifty threads is still a mess, even if there is only one board.

So what should you reach for instead? Here is the menu, from simplest to most powerful:

💡 The better way: dependency injection

Here is the wonderful news — you can keep the benefit ("only one logger, one config, one pool") and drop almost all the costs. The recipe is called dependency injection (DI), and it is simpler than its scary name:

1. Create exactly one instance near the program's starting point (the main function — often called the composition root).
2. Pass it into the classes that need it, through their constructors.

// At startup — created ONCE, like appointing one principal:
const config = new SchoolConfig("settings.json");
const logger = new Logger(config);
const office = new PrincipalOffice(logger);
 
// Dependencies are now EXPLICIT and visible in constructors:
const examService = new ExamService(office, logger);
const sportsService = new SportsService(office);

There is still only one PrincipalOffice — but now:

• ExamService declares openly what it needs. No lies in the signature.
• In a test, you can hand it a FakePrincipalOffice in one line. Testing becomes easy.
• No global static state exists at all.

The school board (your main function) appoints Meena Madam once and introduces her to every department. No teacher conjures a principal out of thin air, yet everyone works with the same one.

College corner — "singleton" becomes a lifetime, not a pattern: DI containers (Spring, ASP.NET Core, Angular's injector, NestJS) turn "how many instances exist" into configuration. In ASP.NET Core, AddSingleton, AddScoped (one per web request), and AddTransient (new every time) are just three lifetime choices for the very same class. The class itself stays plain — public constructor, explicit dependencies, fully testable — and the container enforces uniqueness at the composition level. This separation (class logic vs lifetime policy) is the textbook fix for the SRP violation we flagged in the first College corner. One caution from real projects: a singleton-scoped service must never hold per-user or per-request state, and it must be thread-safe, because all requests share it. The pattern's old dangers do not vanish; they just move into a smaller, well-labelled box.

⚠️ Common mistakes students make

📊 Compare with cousins

Singleton sits among the creational patterns, but its goal is the opposite of most of them — others help you create many objects flexibly; Singleton stops you from creating more than one!

One more relative worth naming: Facade. A facade object (a simple front-door to a complex subsystem) is very often made a Singleton, because one front door per subsystem is enough.

To revise the whole topic in one glance, here is Singleton as a mind map:

🎯 Quick revision box

+--------------------------------------------------------------+
|                 SINGLETON PATTERN — REVISION                 |
+--------------------------------------------------------------+
| Idea       : Exactly ONE instance + one global access door   |
| Story      : One principal, one office, one notice board     |
|              (and one water tank for the whole building)     |
|                                                              |
| Recipe     : 1. private constructor  (lock the front door)   |
|              2. private static instance field                |
|              3. public static getInstance()                  |
|              4. lazy creation on first call                  |
|              5. thread-safety (Lazy<T> / sync.Once / eager)  |
|                                                              |
| Proof      : getInstance() twice -> SAME object (a === b)    |
| Lifecycle  : NotCreated -> Created -> SameInstanceReturned   |
|                                                              |
| Real world : config, logger, connection pool,                |
|              Spring beans (DI-managed!), Runtime.getRuntime  |
|                                                              |
| ⚠️ Honest warning — why seniors frown:                       |
|   - global mutable state in disguise                         |
|   - hidden dependencies (signatures lie)                     |
|   - tests cannot swap a fake; state leaks between tests      |
|   - thread-safe lazy init is easy to get wrong               |
|                                                              |
| Better way : dependency injection — create once at startup,  |
|              PASS it in; DI container singleton scope        |
+--------------------------------------------------------------+

🧪 Practice exercise

Three tasks, from easy to thought-provoking — Pinky-level to Meena-Madam-level. Try them before peeking back!

1. The water tank. Write a WaterTank singleton in TypeScript with a private constructor, a getInstance() method, and a level (litres) starting at 1000. Add use(litres) and refill(litres) methods. From three different "flats" (three variables obtained via getInstance()), use some water, then print the level from a fourth variable. It must show the combined effect — proving everyone shares the one tank on the roof.

2. Break it, then fix it. Take your WaterTank and pretend two threads call getInstance() at the same time when the instance is null. Write down, step by step on paper, how two tanks could get created. Then write the C# version using Lazy<WaterTank> and explain in two sentences why the race disappears. Bonus for college students: explain why a naive double-checked lock could still hand out a half-constructed tank without proper memory barriers.

3. The DI makeover (the most important one). Write a BillingService that first uses WaterTank.getInstance() internally. Then refactor: remove getInstance() from inside the service and instead accept the tank through the constructor — new BillingService(tank). Finally, write a tiny FakeWaterTank and show how the refactored version lets you test BillingService without touching the real tank. Feel the difference — that feeling is why seniors prefer dependency injection.

If task 3 made sense to you, congratulations — you now understand not only the Singleton pattern but also its biggest criticism and its modern replacement. That is more than many working programmers can say. Shabash, keep going!