Monday, May 7, 2007

Singleton

As I promised the first pattern that I'm going to write about is Singleton. Now I know that this might be the simplest and the most well known pattern ever existed but I think there are a lot of points that haven't been collected in one location so I'm going to focus on that stuff. Let me re-iterate that I'm not going to get into in depth discussion of what is Singleton but to more advanced topics and discussions, but to start off we need an introduction so here goes:

In software design there are a lot of situations where we need only one instance of an object to exist or a limited control number of objects to exist (of a specific class). This might be due to resource issues or just the simple fact that it doesn't make sense to have more than one object of a specific class. Many consider the singleton pattern an excellent solution to common coupling (global data). This pattern provides a very easy solution to solve the problems of common coupling and at the same time have the ease of use of global data.

OK so let's take a look at a very simple singleton. Let's assume that we have a PrintManager class that we can call its Print method and pass a document to it for printing. Now this class should queue all the documents that it receives and print them in order. For the sake of simplicity let's assume we have only one printer to print to and therefore only one queue. The singleton pattern says that if you want to make a class a singleton write your logic as if you were going to have multiple instances of it (as a regular class) and then perform the following steps on it:

  1. Make the constructor private so no one can create an instance.
  2. Create a private class variable (static) of your class.
  3. Create a public class method (static) to access the private variable and instantiate it on demand.

For example:


public class PrintManager
{
//The following code is regular implementation not part of
//the singleton pattern
private Queue PrintQue; //Sample member variable

public void Print(Document doc)
{
//code that would take care of queing
//and other boring stuff we don't care about
}


//The singleton pattern implementation:
private PrintManager()
{
}

private static PrintManager _instance = null;

public static PrintManager getInstance()
{
if (_instance == null)
_instance = new PrintManager();

return _instance;
}
}

Obviously the client code needing to use the single instance of the above class will access it through code similar to this:

PrintManager.getInstance().Print(myDoc);

This way no one can create a new instance or remove the one instance that exists, but it's also available for everyone's use. It is also created on first use of the PrintManager.


Items to discuss:

1) Almost all implementations of the singleton pattern should safe guard against a race condition in multi-threaded environments. So the correct implementation of the above code would be:


public class PrintManager
{
/* Ommited for simplicity */

//The singleton pattern implementation:
private PrintManager()
{
}

private static PrintManager _instance = null;
private static object LockObject = typeof(PrintManager);

public static PrintManager getInstance()
{
lock(LockObject)
{
if (_instance == null)
_instance = new PrintManager();
}

return _instance;
}
}

The above code will make sure that no two threads can accidentally enter the getInstance method at the same time and create two instances of the PrintManager object, one overwriting the other.


2) Using C# syntax and relying on a couple of .net CLR features we can rewrite the above code like this:


public class PrintManager
{
/* Ommited for simplicity */

//The singleton pattern implementation:
private PrintManager()
{
}

private static PrintManager _instance = new PrintManager();

public static PrintManager Instance
{
get
{
return _instance;
}
}
}

And the client code would look like this:

PrintManager.Instance.Print(myDoc);

This is a lot nicer and more readable than the previous code. Also notice that since we are relying on the CLR's static member initialization routines we don't need to worry about a race condition or similar multi threading issues.


3) Another situation that exists is a singleton that might have multiple controlled objects (instead of only one object). To keep with the above example we might want to implement our PrintManager so that it can manage multiple printers. Each printer would have a name and would work completely separately from other printers (it will have its own separate queue etc.). One solution that might immediately pop into mind is changing the Print method to accept two parameters a printer name and a document. But this means changing the logic of our code, a logic that might be working fine and we only needed to extend it. Obviously a bad solution and if you really want to know why go look up functional cohesion. Yes if we mix the code to separate different printers & queues with the printing logic we have basically downgraded our design from functional cohesion level to a lower less cohesive level (in this design it looks like a downgrade to logical cohesion; very badJ).
OK to solve this we need a multi-instance singleton

The Multi-Instanced Singleton:

This variation of the singleton pattern which can be implemented in many different ways is basically a singleton that has more than one instance of its class, but each instance is created and controlled by the singleton. For our current example assuming that each printer would be differentiated using a string name our multi-instance singleton would look like this:


public class PrintManager
{
/*Same logic as before (no changes needed) */

//The singleton pattern implementation:
private PrintManager()
{
}

//We need a method to keep multiple instances of the PrintManager class:
private static Dictionary _instances = new Dictionary();

public static PrintManager GetInstance(string printerName)
{
lock (_instances)
{
if (_instances.ContainsKey(printerName) == false)
_instances.Add(printerName, new PrintManager());
}

return _instances[printerName];
}
}

In all variations of the multi-instanced singleton we always face two design decisions:

  • How am I going to store the multiple objects (the data structure needed)?
  • How am I going to differentiate between the different instances?

The first question is usually easy to answer we might need a list or a dictionary or similar data structures. In rare cases we might not even need to store the different instances directly and they would get stored in some other sort of runtime available structure (discussed later).

The second question is a lot more interesting. The above example is a perfect example where the client code will decide which instance it needs to access and the singleton will check if it has that instance, if it does it's returned otherwise it's created (or loaded) and then returned.

Another widely used variety of the pattern is when the singleton class itself can decide which instance to return (the client code just uses the Instance property oblivious to which instance is actually returned. In these cases there has got to be some external way of figuring out which instance to return. As an example suppose we are writing an MDI document processing application. When the user clicks on the Tools menu and selects "Spell Check" we want to invoke the spell check routine passing it the current active document. Now suppose we have implemented Document class as a singleton. When accessing this Document singleton the client code doesn't need to tell it which document all it needs to do is say Document.Instance (whatever object is returned will be the active document).

Another perfectly useful example of this second variation is when you are developing objects that should only exist one per thread. The calling client doesn't need to tell the singleton which object it requires, all that is needed is to ask for the Instance and the active instance will be decided based on the calling thread. See below:


public class ConnectionManager
{
/* ConnectionManager implementation */

//Singleton logic:
private ConnectionManager()
{
}

private static Dictionary _instances = new Dictionary();

public static ConnectionManager Instance
{
get
{
lock (_instances)
{
if (_instances.ContainsKey(System.Threading.Thread.CurrentThread) == false)
_instances.Add(System.Threading.Thread.CurrentThread, new ConnectionManager());
}

return _instances[System.Threading.Thread.CurrentThread];
}
}
}

4) Other situations exist that we need a singleton object but this singleton object might be implemented in different ways or need to use mechanisms such as polymorphism to allow different implementation of the singleton. As an example suppose that we were implementing the above ConnectionManager in a single instance singleton but we needed to provide multiple implementations of it. For example an implementation to work with a SQL Server DB and another to work with an Oracle DB. These implementations would differ a lot in the actual logic of the class but would require the same singleton logic and the same access point for clients. In other words we want our clients to be able to say:

ConnectionManager.Instance.OpenConnection();

regardless of whether the SQL Server DB is configured for use or the Oracle version is going to be used. To achieve this we would need a mechanism to decide which version of our ConnectionManager is going to be used at instantiation but that is irrelevant in this example and for the sake of simplicity I'm going to assume that we will use reflection to create the currently configured version of our ConnectionManager and start using it as the only instance available. Please see the following piece of code:

The Polymorphic Singleton:


public abstract class ConnectionManager
{
//Abstract methods that need to be implemented by concrete ConnectionManagers:
public abstract void OpenConnection();
public abstract void CloseConnection();
// .
// .
// .

//Singleton logic:

//Note that in this version the constructor should be protected
protected ConnectionManager()
{
}

private static ConnectionManager _instance = CreateInstance();

public static ConnectionManager Instance
{
get
{
return _instance;
}
}

private static ConnectionManager CreateInstance()
{
//let's assume the assembly name and class name of the currently
//active ConnectionManager is stored in the .config file
Assembly asm = Assembly.Load(ConfigurationManager.AppSettings["Assembly"]);
return (ConnectionManager)asm.CreateInstance(ConfigurationManager.AppSettings["CMFullName"]);
}
}

public class SQLConnectionManager : ConnectionManager
{
public SQLConnectionManager() : base()
{
}

public override void OpenConnection()
{
//SQL implementation
}

public override void CloseConnection()
{
//SQL implementation
}
}

public class OracleConnectionManager : ConnectionManager
{
public OracleConnectionManager() : base()
{
}

public override void OpenConnection()
{
//Oracle implementation
}

public override void CloseConnection()
{
//Oracle implementation
}
}

As is obvious in the above implementation the constructor of our singleton class must be protected (otherwise no one can inherit from it) and the sub-classes need to have a public constructor so that the singleton CreateInstance method can create them on demand.

5) Finally you might even think of a situation where we need a multi-instanced polymorphic singleton as the final type of singleton.


Singletons in Web Apps

A question that I have been asked time and again is what happens in web based applications. Do we still need the singleton pattern there? Can't we just use the Application/Session objects?

YES you can and many people do and feel that it's a lot easier dealing with Application/Session than with a singleton, but I'd like to make these couple of points regarding web based scenarios:

  1. In many cases you might be developing a library or a reusable piece of code that will be run in multiple environments. You might need to use it in a web based scenario and a windows based scenario and other similar situations. For these kinds of reusable parts using the Application/Session will tightly couple them with the web-based environment and will prevent their reuse in non-web based environments. To get over this we can implement our singleton using the methods discussed above or implement a polymorphic singleton that depending on the environment that it's in will choose a web based or a windows based implementation.
  2. Another big question in web based scenarios is what are you using the singleton for? Are you using it to store user specific information, in other words a multi-instanced singleton that has an instance per user storing that users' information or are you designing a singleton (or multi-instanced one) that has no relation to the user. For the former you have to use the Session object otherwise in server farm scenarios you would have to implement a lot of code to replicate your singleton's data across all servers. But for the latter situation a regular singleton should suffice.
  3. Speed & performance might be another reason you would pick a regular singleton over the Session/Application data. Session data (especially in a server farm environment) could be really slow (object serialization, transfer to state server, storage there and the reverse process). Again if you don't need to replicate that data across all servers in the farm why use a Session object.
  4. As a general best practice it's better to wrap all your Session/Application needs in a class similar to a singleton implementation so you don't have to deal with strings in accessing Session/Application data and you have strongly typed variables (preventing many runtime time errors). The wrapper you would create around the session/application object can be a singleton in itself.

Other patterns:

Many patterns can be combined with the singleton object to solve more complex problems and I will try to touch on them in the next posts, but maybe one of the most famous ones is the Abstract Factory pattern. This pattern in most cases gets combined with a polymorphic singleton and we'll get into this on the next design pattern post I'm going to get into.

5 comments:

Farzad said...

Hi :)
Thanks for your detailed explanation.

Farzad said...

As you mentioned before, it is not possible to execute a SQL command from one thread when another thread is inside a transaction in the same connection.
In this situation we have to open a new DB connection for each thread.

I guess using Thread.SetData() and Thread.GetData() will help.
I can open a new connection for each thread and store the reference in the thread by using Thread.SetData() and I can retrieve the connection by using Thread.GetData().

Thread.SetData() and Thread.GetData() are inside the
public static DBConnectionManager Instance() property.

What is your idea for this problem?

Ehsan said...

Farzad,
I don't think you're even allowed to share a connection between two different threads. If you try to access a connection object through different threads you will most likely get an exception. Anyhow as you can see in my post in the "Multi-Instanced-Singleton" section I've given an example of a ConnectionManager that will maintain a different instance of itself based on what thread is calling it.
You can extend that example so instead of storing the ConnectionManager instances in the dictionary, they would be stored in the Thread using GetData and SetData, which for the given example is excellent (since all will be cleaned up when the thread dies) but in general might not work (consider the MDI word processor example).

Kambiz said...

First visit, best wishes

Jamal Mavadat said...

G'day dearest Farzad and Ehsan,

Dear Ehsan! I'd have submitted this comment much sooner should I had read this post at its very beginning; my apologies as I had no idea you've got such a wonderful blog.

Well, to be perfectly superhonest, multi-threaded usage of live connection is provider-specific. Microsoft's famous provider for Microsoft SQL Server, SqlClient, does support asynchronous command execution - not to be confused with ADO.NET 2's async command execution. So that an open SqlConnection instance could be shared between two threads without any guards, and then each thread could execute its own SqlCommand instances. ADO.NET takes care of the rest so that the command execution might be blocked till the other thread's command get completed, and data fetched if any. The surprising part, it's not a widely known feature; funny huh?! :)

By the way, as an architect I've never recommended my clients going for it because there are some architectural, implementation, and deployment considerations/restrictions which I'm not gonna put here. As an example only, most of the time, it does worth paying the 35+ KB memory consumption per sql-connection, instead of getting stuck down with those implementation difficulties. The traditional and easy-to-learn connection pool wins in most cases.

Dear Farzad?! Emmm!!! I basically do not recommend using Thread Local Storage (TLS) the way you mentioned, because the solution has great negative impact on the resource management as thread's local references donot support disposable objects; whilst connections are among most expensive resources! Therefore, you must manage such resources manually. By the way, as our dearest Ehsan mentioned, it'd give you a replacement option for the dictionary; there are few pros and cons applicable to both options, you know!

Cheers,
Jamal Mavadat