Singleton Pattern: Guaranteeing One Instance With a Global Access Point

One configuration, one connection pool, one log: the class itself makes sure there is only one.

The Singleton pattern makes a class create at most one instance of itself and give that instance to anyone who asks, through a method every caller can reach. This card covers the problem it solves, the intent, and why it is the most criticised pattern in the catalogue.

The problem is a resource that the program must have exactly one of. If two parts of a program each read the settings file and one of them later changes a setting, they disagree; if each creates its own connection pool, the database receives twice the connections it was sized for.

Separate instances and one shared instance

Without the patterneach part creates its own

billing_config = Config("settings.json")
email_config = Config("settings.json")
billing_config.values["currency"] = "EUR"

The file is read twice, and billing now charges in euros while emails still quote pounds.

With the patternthe class hands out one

billing_config = Config.instance()
email_config = Config.instance()
billing_config.values["currency"] = "EUR"

Both names refer to one object, so there is one set of settings to disagree with.

The Gang of Four state the intent as: ensure a class only has one instance, and provide a global point of access to it. Those are two promises, and the criticism falls on the second. One instance is often exactly right. A global point of access means any code anywhere can reach the instance without asking for it, so a function's signature no longer says what it depends on, and tests that change the instance affect each other.

Think of a country's one official time signal: every clock that needs the right time reads the same source. The analogy breaks on visibility. Everyone knows where the time signal comes from, while code that calls Config.instance() inside a method hides that dependency from anyone reading only its signature.

Singleton is one of five creational patterns, the family that controls how objects are created.

The creational family, with this pattern marked
Pattern	What it decides
Factory Method	Which class a subclass creates, through one overridable method.
Abstract Factory	Which family of related classes is created, through one object.
Builder	How a complex object is put together step by step.
Prototype	Which existing object a new one is copied from.
Singleton (this topic)	That a class has only one instance.

Singleton

Use it when

There must be exactly one of something, such as a pool sized for the database or a cache that all callers share.
Code that cannot receive the instance as a parameter, such as a framework hook, still needs to reach it.
The instance holds no state that would make one caller's actions visible to another, or that state is the point.

Avoid it when

Code could be handed the one instance when it is created, which keeps one instance without the global access.
Tests need a different instance, such as a fake database, for each case.
The only reason is convenience: not wanting to pass an object through a few constructors.

← → move through sections and cards