Singleton Design Pattern : The Pragmatic Approach - Part I

• Download source code - 20.4 KB

Introduction

This article is about understanding one of the most widely known  design pattern in creational design patterns category. I’m trying to approach this design pattern in a different manner. I would essentially take you through an evolution to understand singleton design pattern. I believe evolving through scenarios, constraints and use cases is the most pragmatic way to learn and understand anything and imbibe it deeply into your nerve patterns. 

Although this article involves concepts of C# .NET and Common Language Runtime (CLR) but you should be able to sail through the article easily even if you are a specialist from a different technology. I’ve tried to keep the flow of the article language agnostic as much as I could.

Common language run-time (CLR) is a key component of .NET Framework which provides the virtual execution environment for applications targeting .NET Framework. You can read more about it here

Background: How It All Started

A general discussion was going on with my colleague at my work place. A view point cropped up that static classes don't have instances as we refer them directly by their class name instead of creating their instance by using new keyword. Then I emphasized that there is indeed an instance internally, but it is managed directly by CLR. Then, we started discussing singleton design pattern w.r.t. static keyword and I realized that there is sufficient amount of confusion in this discussion to write a blog about it so that she and the rest of the world can understand static, singleton and the design pattern better. And here we are!
 

A Note About Source Code

There are many ways of structuring a project code, but I’ve followed plain old standard n-layer architecture in my code just for the sake of simplicity and avoiding any diversion in understanding the key topic of the article. Any enterprise application that you build today for production use might have different structuring.

The source code for this blog is also available under my account on GitHub here. Please feel free to leave your pull requests in case you think I can improve it in any way.

Let's Get Started: The Business Requirement

The problem statement I’m considering is about the concept of logging in an enterprise application. If you’ve ever got a chance to work in an enterprise application, you would have certainly used logging in your code. If not, then you will get introduced to the concept of logging sooner than later. So, what is logging?

To debug errors in code, you simply put break points and then step through your code step by step using any development environment like Visual Studio (VS). Simple and easy. Isn’t it? But what about the case when your application deployed in customer’s environment (i.e., production box) is throwing some error. It is very likely that your customer will not allow you to install VS on the production box so that you can do line by line debugging by attaching the debugger in VS. All the events happening inside your code becomes a black box the moment your code gets deployed into production in the form of DLL and EXE files. That’s where logging becomes the eagle eye to look through that black box.

What we can do is that, at all the important junctures in your code, you can put log statements or information which will get written to a persistent storage, e.g., a file, a database table which can be retrieved later in case of errors or issues. So as your application starts running, it creates foot prints or trail into the logging system of how it ran. Have a look at the below code snippet to understand how a typical logging can be done at critical junctures to be helpful at a later point of time. The method in the code snippet below is trying to obtain some information from the database of the application by firing a SQL query (refer to FetchData.cs):

public DataTable GetStudentData()
{
    var studentInfo = new DataTable();
    try
    {
        //Milestone 1 : put a message into pesistent storage that method execution has started
        var sqlConnection = GetDbConnection();
        sqlConnection.Open();

        //Milestone 2 : put a message into pesistent storage that 
        //Database connection was successfully established
        SqlDataAdapter sqlDataAdapter = new SqlDataAdapter("SELECT * FROM Student", sqlConnection);
        sqlDataAdapter.Fill(studentInfo);

        //Milestone 3 : put a message into pesistent storage that query to the database was successful
        //Milestone 4 : put an informational note about the count of students
        //that were fetched from the database.
     }
     catch (Exception ex)
     {
        //Exception flow Milestone : put a message into pesistent storage 
        //that an internal error occurred and the reason behind the error with line number of code, etc.
     }
     //Milestone 5 : put a message into pesistent storage that method execution has finished
     return studentInfo;
}

private SqlConnection GetDbConnection()
{
    var sqlConnection = new SqlConnection("Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;");
    return sqlConnection;
}

All the information present in the logging repository can then help you understand how your method or code ran step by step and at what exact point the error occurred. May be the database was down or the query was wrong and so on. Logging can also include informational message like the values of various variables at the point of error to help you get precise information to fix your code. The moment an error occurs, you can simply ask the production support engineers to help you with the log files which are usually present at a preconfigured location. You can analyze the root cause of the error using the log files.

Now logs can be persisted in a variety of repositories. I’m enlisting a few of them here:

1. Plain text files
2. Database
3. Event viewer

For this discussion, we will consider a plain text file-based logging. So, to log into a plain text file, we need to build some common code and classes which will do this task of saving the information into log files in a centralized manner. We will call this infrastructure as text file logger class. Let’s try to build one.

Building a Simple Text File Logger

I’m working on a very simple web application for a college which gets the information of students studying in the college and shows them on a web page in tabular format. This application will be used by college staff, e.g., librarian. To debug any run-time errors in production environment, I will need some logging in my application. So, let’s build a text file logger which will do logging in a plain text file. Here are the basic things it should be doing:

1. Create a plain text file in a predefined location if it is not present already.
2. Open a handle to the file.
3. Write text or log statements using the file handle.
4. Save the contents on disk.
5. Repeat steps 3 and 4 above if there are more log statements in any method.
6. Flush the in-memory buffers if any onto disk and then release the file handle.

Let's Begin to Code

Here is a sample implementation of the Logger class (refer to TextLogger.cs) that I’ve written for StudentInfo application:

using System.IO;

public class Logger
{
    private string LogFileDirectory = "";
    public Logger()
    {
        //in general this path will be obtained at run time from the application configuration file.
        //it is hardcoded here for simplicity
        LogFileDirectory = @"C:\ProgramData\StudentInfo\";
    }

    public void Log(string logMessage, LogLevel logLevel)
    {
        if (Directory.Exists(LogFileDirectory))
        {
            using (StreamWriter streamWriter = new StreamWriter(LogFileDirectory + "log.txt",true))
            {
                streamWriter.WriteLine(DateTime.Now.ToString() + " [" + logLevel.ToString() + "]" + " - " + logMessage);
            }
        }
    }
}

Note: using keyword inside Log method is bit important here. It implicilty calls Dispose method on streamWriter object which sets the file handle to null so that operating system can reclaim the associated memory. Here is a nice blog about using keyword in C#. It helps dealing with point # 6 mentioned in previous section.

How would I consume this Logger class in the data access layer of StudentInfo application? Now I’ve replaced all the milestone comments where we had initially felt the need to put some information into logging system for later retrieval (refer to FetchDataWithTextLogger.cs):

public class FetchData
{
        public DataTable GetStudentData()
        {
            var studentInfo = new DataTable();
            //logger class instantiation with new keyword
            var logger = new Logger(); 
            try
            {
                logger.Log("Method GetStudentData entered.", LogLevel.Trace);
                var sqlConnection = GetDbConnection();
                sqlConnection.Open();
                logger.Log("Connection established with database.", LogLevel.Trace);

                SqlDataAdapter sqlDataAdapter = new SqlDataAdapter
                                                ("SELECT * FROM Student", sqlConnection);
                sqlDataAdapter.Fill(studentInfo);
                // noob programming! someone initialized one more instance of 
                // Logger class again in the same method.
                var logger2 = new Logger();
                logger2.Log("Data obtained from database.", LogLevel.Trace);
                logger2.Log("Number of students fetched." + studentInfo.Rows.Count, LogLevel.Information);
            }
            catch (Exception ex)
            {
                //anybody can instantiate Logger class at will.
  var logger3 = new Logger();
                logger3.Log("An error occurred in GetStudentData method. 
                Exception details are - " + ex.Message, LogLevel.Error);
            }
            logger.Log("Method GetStudentData Exited.", LogLevel.Trace);
            return studentInfo;
        }

        private SqlConnection GetDbConnection()
        {
            //one more logger instance.
            var logger = new Logger();
            logger.Log("Method GetDbConnection entered.", LogLevel.Trace);
            var sqlConnection = new SqlConnection
            ("Server=myServerAddress;Database=myDataBase;Trusted_Connection=True;");
            logger.Log("Method GetDbConnection exited.", LogLevel.Trace);
            return sqlConnection;
        }
}

Now have a look at the nice log trails this code is generating at path C:\ProgramData\StudentInfo\log.txt on my computer:

20-Feb-18 4:54:21 AM [Trace] - Method GetStudentData entered.
20-Feb-18 4:54:25 AM [Trace] - Method GetDbConnection entered.
20-Feb-18 4:54:28 AM [Trace] - Method GetDbConnection exited.
20-Feb-18 4:54:32 AM [Trace] - Connection established with database.
20-Feb-18 4:54:38 AM [Trace] - Data obtained from database.
20-Feb-18 4:54:38 AM [Trace] - Count of students fetched : 10.
20-Feb-18 4:54:40 AM [Trace] - Method GetStudentData Exited.

Some avid programmers must have noticed few obvious mistakes in my code where I’m trying to consume the Logger class. We will try to understand those mistakes we can make knowingly or unknowing in the next section.

Functional Correctness in Current Scenario

If multiple code flows of the program are instantiating and using the Logger class, then generated logs can get complex and might become a spaghetti when we start reading them.

• Chronological ordering of log statements: It becomes important in terms of time stamp of log statements so that the logs statements come out crisp and clean, else it will become a garbled piece of information. Ordering of log statements depicts the flow of control in your code. Multiple instances of Logger class which consequently creates instances of StreamWriter class can mess it up. Content of the file can get overwritten or can get written out of order.
• Simultaneous access can cause errors: When several StreamWriter class instances try to access same log file at one time, then they might get errors like file is already in use exception during write operation. This mainly happens when earlier handles were not closed after use and now someone is trying to open the file with exclusive write locks. In case of such exceptions, our log statements can get lost.
• Multi-threading and cross-thread synchronization: Simultaneous access can happen more frequently in case of multi-threaded applications. When multiple threads running in different modules of your application are trying to gain access to write the same log file, then it can often result in same access violation issues due to file being already in use errors and things like that. How would you keep a check on this?

Let’s say even if we don’t face the above errors and all this works just fine functionally by luck or due to our application being very less complex even then we can face performance issues also. Let’s explore that aspect.

Application Performance in Current Scenario

The code we saw in the previous sections has got some costly bits involved from your application performance stand-point:

• Instance of Logger class
• Instance of StreamWriter class (inside Log method’s using block): Instance of StreamWriter class internally involves creating unmanaged file handles at OS level. During disk I/O lot of things happen at operating system level like checking user access permission, etc.

So, each of the above operations might take a fraction of a second or may be in milliseconds and you might think that why should I care about the cost of creating a file handle (which is eventually an object instance) in this era where I have got 32 GB RAM computers and website server computers (or data centers) are even more powerful. I say we must care. You shouldn’t care about this aspect if you’re going to write few scores of log statements or going to open a few file handles here and there. But the point is that enterprise applications are very big in general. Really big applications can have even dozens or hundreds of log statements in a single flow of the program which ends up creating hundred instances of StreamWriter class at the same time.

Let’s consider few points below on how the above discussion can contribute to performance issues:

• Redudant instantiation due to bad programming: Notice the logger2 and logger3 instances of Logger class in the code snippet of FetchData class. Are they really required in GetStudentData method? Can you somehow prohibit your team-members from making such a mistake? Is our Logger class capable of putting any such restriction?
• Uncontrolled method level local instantiation: A single web call from one user can involve creating multiple handles to log file as you might require logging several pieces of information through various nested methods involved in your flow, e.g., GetStudentData and GetDbConnection as shown above. More file handles objects in memory will increase the memory foot-print of your application. If there are several such memory hungry applications running in your system, then your process can also face memory starvation.
• Increasing load on your application: I believe if I created good enough public facing website, then users of my website will only grow with time so the number of web calls per second will keep increasing where each web call is creating more handles allocating more resources in parallel, e.g., memory buffers, file handles, etc.
• Memory Leaks: File handles and their memory allocation is outside the purview of CLR’s managed memory space. You must be cautious about resource clean-up associated with such classes. Any miss on this front will cause memory leaks which can be horrible. using keyword in C# really comes to our rescue to deal with this scenario using IDisposable pattern. Missing using keyword is a direct invitation to memory leaks.

How Can We Avoid these Functional & Performance Issues?

So, we have some possible solutions that we can think currently:

• Global instance: Anybody would say that I could’ve maintained a global variable at class level which will maintain only one instance of StreamWriter class. Since there will be only once instance, we can ensure that memory leak doesn’t happen at the central place. But, globals are always considered a bad programming practice. Anybody can set it to null from anywhere in the code and then you start putting not null checks across your entire code base. To ensure that developers aren’t creating local instances of Logger class in any method, you will have to put few checks in place:
  • Continuous code review to check for such bad instantiation
  • Static code analysis (Linting) tools

          And the fact remains that if the class is public, you can’t stop any developer on your team to instantiate it.           Compiler treats all developers equally irrespective of designation. 😊

• Add more hardware: Running short of RAM on your computer due to increasing object instantiation or memory leaks? One obvious solution is to add more RAM. Isn’t it? But, you can’t keep upgrading the RAM of your server box forever the moment it is running out of capacity with increasing user load. Ultimately, there is a dollar cost involved and you always must stop your website before upgrading your hardware.

And let’s say even if I don’t face all these issues, even then our honest attempt should always be to reduce memory foot print of our application. Isn’t it? An enterprise level application isn’t that simple as I’ve mentioned. Your server application requires memory for so many other things, e.g., threads, stack memory, I/O ports, etc. So, our intention should always be to minimize the main memory consumed by the process to make space for other activities and other processes running on the server.

So, all above pointers are giving us a push that we somehow need to restrict the possibilities of several file handles getting opened in parallel or if it happens, then it should happen in a controller manner. How do we achieve it?

How Can We Reduce Object Creation: Overcoming Resource Contention with Singletons

You must have heard the concept of sharing. At your home in general, we all have one television (TV) set. Why? TVs are costly, so it will not be affordable for every household to purchase a TV for every family member. Also, you’ve got limited space (which is again a resource) in your house. You can’t use the entire space just for installing several TVs. So essentially, you settle with only one TV in your house and share it among all the family members. The same concept in computer science world is known as resource sharing.

So, one question which comes to our mind is that – Can we do some resource sharing here to solve our problem. Yes. That shareable resource is an instance of Logger class which manages the file handles to our log file through StreamWriter class.

It is always the case that your entire application will have centralized log files which contain the logs created by various modules of your application. Logger class will eventually create a file handle to the same file always. Isn’t it?

So why create several instances within a single web request from a single user or across web calls? Essentially why to leave a scope in code that anybody can just instantiate the Logger class as and when they want it. Can we not stop it from happening at code level itself? Why not enforce to have only one (aka single) instance of the object. That should ring some bells now. Singleton (title of this article) has the word Single in it 😊.

So how can we ensure in code that one and only one (aka singleton) instance of our class is possible?

The static Keyword

C# has a keyword called static. You can check Microsoft docs here for some quick details. static can have different usages/meanings while used in different contexts of C# programming but while used in context of classes, it essentially means a thing which is associated with a type and not an instance of the type. If you apply static keyword to the class itself, then all the properties and methods get associated to that type directly, so you need the type (not the instance) when you need to refer them in code, e.g. <ClassName>.<MethodName>

A class decorated with static keyword can’t be instantiated. Let’s try to understand it with help of our Logger class. Let us say I’ve marked the Logger class with static keyword right after the “public” access specifier as shown below:

namespace TextLogger
{
    public static class Logger
    {
        //Logger class implementation
    }
}

Now at the call site in Database access layer, we try to consume “Logger” class using new keyword:

namespace DataAccessLayer
{
    public class FetchData
    {
        public DataTable GetStudentData()
        {
            //other code

            //this line now starts throwing compiler-time error.
            var logger = new Logger();
                     //other code
        }
     }
}

So the moment we try creating an instance of static class, it starts throwing the below compile-time error:

Cannot create an instance of the static class ‘Logger’

So that’s what we wanted. Isn’t it? No developer can instantiate the Logger class at their will and that is what we’ve got now. But what about using it. We would require at least one instance to log our messages into the log file. Let us see a quick implementation on how we can make it work using <className>.<MethodName> syntax for static classes/methods in C#:

Static Logger full implementation (refer to StaticClassTextLogger.cs):

namespace StaticClassTextLogger
{
    public static class Logger
    {
        static string logFileDirectory = @"C:\ProgramData\StudentInfo\";
        static StreamWriter streamWriter = null;
        //static constructor
        static Logger()
        {
            //initialize streamWriter instance once for the life time of static class
            if (Directory.Exists(logFileDirectory))
            {
                //we can't use using keyword anymore as it will dispose the streamWriter object at
                //the end of using block
                //using (streamWriter = new StreamWriter(logFileDirectory + "log.txt"))
                //{
                //    streamWriter.WriteLine(DateTime.Now.ToString() + " [" + logLevel.ToString() + "]" + " - " + logMessage);
                //}

                streamWriter = new StreamWriter(logFileDirectory + "log.txt");
            }

        }

        public static void Log(string logMessage, LogLevel logLevel)
        {
            //use the same instance everytime Log method is called.
            streamWriter.WriteLine(DateTime.Now.ToString() + " [" + logLevel.ToString() + "]" + " - " + logMessage);
        }

    }
}

How things will change at call-site: (refer to FetchDataWithStaticTextLogger.cs)

namespace DataAccessLayerWithStaticTextLogger
{
    public class FetchData
    {        
        public DataTable GetStudentData()
        {
            var studentInfo = new DataTable();
            //explicit instantiation not required anymore
            //var logger = new Logger();

            try
            {
                //access methods of a static class using <ClassName>.<MethodName> syntax
                Logger.Log("Method GetStudentData entered.", LogLevel.Trace);
                var sqlConnection = GetDbConnection();
                sqlConnection.Open();
                Logger.Log("Connection established with database.", LogLevel.Trace);

                SqlDataAdapter sqlDataAdapter = new SqlDataAdapter
                                                ("SELECT * FROM Student", sqlConnection);
                sqlDataAdapter.Fill(studentInfo);
                
                //Compiler stop you from doing bad programming any more
                //var logger2 = new Logger(); //bad programming
                Logger.Log("Data obtained from database.", LogLevel.Trace);
                Logger.Log("Number of students fetched." + studentInfo.Rows.Count, LogLevel.Information);
            }
            catch (Exception ex)
            {
                Logger.Log("An error occurred in GetStudentData method. 
                Exception details are - " + ex.Message, LogLevel.Error);
            }
            Logger.Log("Method GetStudentData Exited.", LogLevel.Trace);
            return studentInfo;
        }
    }
}

So, what all did we achieve in the above code snippet:

1. We have a single instance of one of the most heavy objects in our case, i.e., “StreamWriter”. Same static thing will get leveraged in every single call.
2. We got an extremely simple implementation. Just an extra keyword static and we achieved our goal.

Are you able to notice any problem here so far in the static way of managing Singleton instance of a class? Please scribble few notes on a piece of paper. We will go through them in a later section.

By the way, I just used the phrase “managing Singleton instance”. But where the hell is the instance? You didn’t use “new” keyword even once to create any instance in memory. Isn’t it?

But Where is the Instance in Memory?

It is true that you have now been restricted by the compiler to create instances of the “Logger” class but you know that new-up operation which we apply on normal classes do the crucial work of allocating space to member variables of a class and returning a handle in the end with the help of which we do various operations on the object instance. So where is the instance here? How is memory getting allocated to static class members? You know it already that any code starts to work only after it gets loaded in main memory of the computer which is RAM.

Yes. So that bring us all to an important concept in .NET called type instance. For every single class (static or non-static) that you have in your project, Common Language Runtime (CLR) creates a special instance for the class called Type instance. It contains all the meta information related to your class, e.g., fully qualified name, all method signatures and its code, etc.

So, all static stuff present in a class are associated directly with this special instance called type instance. If you declare static member variables, then they will lie in line with the memory area where type instance is residing. And that is how the <ClassName>.<MethodName> syntax came into being. By using that <ClassName>, you are referring to the type instance in memory and get your things done.

Please note that CLR guarantees that there will be one and only one type instance for a class per appDomain in a .NET process. So, you can be rest assured that there will be only occurrence of all the static stuff associated with your class as they are all present with the type instance.

This is a nice concept to know. But is CLR behaving in-line with our expectations while managing static classes. Can there be any pit-falls in the way CLR manages static classes and their instantiation which can be a road block for my application later? Are statics really true Singletons? Let’s explore.

Why Static Instance is Enough or NOT Enough for Managing Singletons

Ok. Let me jot down few problems that are there while managing singletons using static keyword. Take out your scribbled paper and start matching them.

The problems which are directly visible from looking at code:

1. You don’t have full control over disposing the static: How would you control the disposing off the object instance which is static instance in this case. You can’t. All the static stuff of your static class is associated with type instance which is controlled and managed by the CLR. In .NET, type instance is disposed only when AppDomain/process is going to get unloaded. So, at best, the memory of the object referred by static member variable streamWriter can still be reclaimed but the variable itself will remain alive. If static member variables are structs or value types, then they will also continue to live until process starts to unload which results in unloading of type instance.
2. Static classes don’t participate in inheritance: Static classes are sealed by default in C#. So, if you have an already existing logger class in your code which inherits from some other class and now you want to restructure it to convert it into a singleton, then you’ve got a bigger work at hand. If you make it static, then you will have to let go of all the inheritance stuff and bring all the functionality from base class to the current class.
3. Static classes can’t be passed around into methods as arguments: Method parameters are always references to instances in C# and Static classes can’t be instantiated.
4. You can’t control the timing of instantiation of static fields: Let us consider a case where you are trying to load a singleton object which is very resource intensive, e.g., if it is loading some very heavy graphics object which must be commonly shared by the entire application. It can always be the case that the heavy singleton graphics object is not required initially at the load time of the application. You want to defer it (lazy loading) to a later time when it is required, otherwise it will affect the start-up time of your application. Unfortunately, you don’t have a control on when the static fields get initialized as it is totally controlled by CLR. It can happen right when the application is starting up, or may be when AppDomain is getting created or any custom implementation/logic which is subject to change in any new version of CLR. In short, lazy loading or delayed initialization can’t be controlled in case of static classes.
5. Static constructors aren’t fault tolerant: Static classes also have constructors where you might want to initialize or setup few things. By any chance, if you encounter an error (e.g., database might be down currently which you are trying to connect) or an unhandled exception in the static constructor, then you lose the ability to give a retry to call the constructor again. CLR invokes the static constructor of a static class only once in the life time of the app domain. There is no built-in mechanism to put a retry mechanism to instantiate the type instance again if you can overcome the fault situation (database came back online) at a later point of time.

So, if you aren’t bothered by the above issues in the application you’re writing, then you are all good. A static class should suffice your needs as all the heavy lifting has already been done by CLR on your behalf to ensure that one and only one instance of the class gets created. Singleton instance was our original intention/requirement. Isn’t it?

If you think that the above issues with static might crib you down the line as your enterprise application evolves, then we might have to think another route. The key concern that we need to solve is - I as a programmer want to have absolute control over the instantiation and life-time of the singleton instance. I don’t want to rely on CLR or Java Virtual Machine (JVM – CLR’s counterpart in Java world) as when my singleton instance will get created, retried for creation or destroyed. Can we do something ourselves? Can we have an implementation of Singleton on our own?

Points of Interest

Hmmphhh! That was lot to chew. Isn’t it? Thanks for your patience to read this long article which sets the backdrop for the concluding blog. Let’s take some time to ponder and think of possible solutions for designing a singleton class ourselves. Once you’ve done the homework, then we can move to the concluding blog:

Singleton Design Pattern : The Pragmatic Approach - Part II

History

• 7^th March, 2018: First draft
• 8^th March, 2018: Added link to concluding blog (Part II)
• 9^th March, 2018: Changed prerequisites in "A Note for the Attached Code" section.
• 18^th March, 2018: Added link to GitHub repository for source code and minor corrections at few places.