Saving and restoring GDI+ state

When you create complex drawing code, you probably will split this over multiple methods and pass the Graphics-object between these methods. But because the Graphics-object contains state, all changes that you apply in a method will be propagated to the other methods as well. Often this is not what you want.

The common way to work around this is to reset all the changes that you made at the end of the method:

   1: void PaintBackGround(Graphics g)

   2: {

   3:     SmoothingMode oldSmoothingMode = g.SmoothingMode;

   4:     try

   5:     {

   6:         g.SmoothingMode = SmoothingMode.AntiAlias;

   7:         ...

   8:     }

   9:     finally

  10:     {

  11:         g.SmoothingMode = oldSmoothingMode;

  12:     }

  13: }

But if your code changes a lot of properties this will become cumbersome. In these cases it is simpler to save and restore the entire Graphics-state like this:

   1: void PaintBackGround(Graphics g)

   2: {

   3:     GraphicsState oldState = g.Save();

   4:     try

   5:     {

   6:         g.SmoothingMode = SmoothingMode.AntiAlias;

   7:         ...

   8:     }

   9:     finally

  10:     {

  11:         g.Restore(oldState);

  12:     }

  13: }

Creating a single-instance application

A lot has been written on the internet on how to create a single-instance application in C#. The proposed implementations fall into three categories:

• Check if a process with the same name is already running (using GetProcessesByName). This is plain wrong because it needs administrator privileges. Furthermore it will not work if there is another process that happens to have the same name as your process.
• Using the Microsoft.VisualBasic namespace (as explained here). This probably works OK (I have never done this), but it feels a bit wrong. Note that this approach is promoted in the book ‘Windows Forms 2.0 Programming’.
• Using a Mutex.

Personally I think that the last approach is best, but there are some details that you need to get correct if you want to rely on this. This is the pattern that I propose:

   1: static class Program

   2: {

   3:     static Mutex s_Mutex;

   4:  

   5:     /// <summary>

   6:     /// The main entry point for the application.

   7:     /// </summary>

   8:     [STAThread]

   9:     static void Main()

  10:     {

  11:         bool instantiated;

  12:         // WARNING: you need to replace the GUID in this string!

  13:         s_Mutex = new Mutex(false, "Local\\MyAppName{A6F214AB-669D-41B2-9F30-8DD5E5AC9AE1}", out instantiated);

  14:         if (!instantiated)

  15:         {

  16:             MessageBox.Show("The application is already running");

  17:             return;

  18:         }

  19:  

  20:         Application.EnableVisualStyles();

  21:         Application.SetCompatibleTextRenderingDefault(false);

  22:         Application.Run(new Form1());

  23:     }

  24: }

The pattern is applied to a Winforms application, but of course it can be applied to any type of application.

For those who don’t know what a mutex is: it is a Windows kernel-object that can be used for synchronization between threads and processes. The proposed pattern tries to create a mutex with a certain name and checks if this mutex already existed. If it did, this means that our process was already started.

Here are the details that are important:

• The mutex must be declared static, because we have to make sure that the garbage collector will never dispose it.
• The name of the mutex should contain a GUID, which ensures that no other application uses the same name. If you don’t know how to create a GUID, click here.
• The mutex is local, which means that every user that is logged on can create his own instance. If you don’t want this, simply ommit the ‘Local\\’.
• The mutex contains the name of the application. As a general guideline, I think that named kernel objects should have a descriptive name. This makes it easier when debugging problems: using tools such as SysInternal’s WinObj, you can look at the state of all the kernel objects. If your object has a proper name this will be much simpler.

GDI+ objects should be disposed

When a Winforms-control needs to do custom painting, this is typically done by overriding the OnPaint-method like this:

   1: protected override void OnPaint(PaintEventArgs e)

   2: {

   3:     base.OnPaint(e);

   4:  

   5:     Graphics g = e.Graphics;

   6:  

   7:     // WARNING: this code should be avoided because it does not dispose the GDI+ objects

   8:     g.FillRectangle(new SolidBrush(Color.Black), this.ClientRectangle);

   9:     TextRenderer.DrawText(g, "Hello world!", new Font(FontFamily.GenericSansSerif, 10f), new Point(10, 10), Color.White);

  10:     g.DrawLine(new Pen(Color.White), new Point(0, 0), new Point(100,100));

  11: }

On the internet you will find lots of example code that does custom drawing like this. The problem is that every time this code is executed (and in GUI this can be a lot!), a bunch of GDI+ objects are created that are not disposed. Eventually the garbage collector will kick in and will dispose all these objects. This is to be avoided however:

• This puts a lot of stress on the garbage collector.
• These objects will be cleaned up in two fazes which will impact performance even more.
• GDI+ handles are limited resources, but the garbage collector is only invoked if your application needs more memory. It is not unlikely that your code uses a lot of GDI+ handles but does not consume a lot of memory. This may mean that the garbage collector never executes, and your code may consume a huge amount of GDI+ handles.
  This issue was especially problematic before GC.AddMemoryPressure() was added in .NET 2.

The obvious solution is to dispose the GDI+ objects when they are not needed anymore:

   1: protected override void OnPaint(PaintEventArgs e)

   2: {

   3:     base.OnPaint(e);

   4:  

   5:     Graphics g = e.Graphics;

   6:  

   7:     // Much better: less stress on the garbage collector

   8:     using (SolidBrush brush = new SolidBrush(Color.Black))

   9:     using (Font font = new Font(FontFamily.GenericSansSerif, 10f))

  10:     using (Pen pen = new Pen(Color.White))

  11:     {

  12:         g.FillRectangle(brush, this.ClientRectangle);

  13:         TextRenderer.DrawText(g, "Hello world!", font, new Point(10, 10), Color.White);

  14:         g.DrawLine(pen, new Point(0, 0), new Point(100,100));

  15:     }

  16: }

This code is good but we can make it even better. Note that every time the code is executed, new GDI+ objects are created and disposed. In this particular case this is a waste because the objects will be identical every time. It would be better to create the objects only once, and reuse them every time.

It seems that the Winforms-designers at Microsoft also had this idea, because they already cache the commonly used brushes and pens in the Brushes and Pens classes. For the Font-object we need to do this ourselves:

   1: static readonly Font s_Font = new Font(FontFamily.GenericSansSerif, 10f);

   2:  

   3: protected override void OnPaint(PaintEventArgs e)

   4: {

   5:     base.OnPaint(e);

   6:  

   7:     Graphics g = e.Graphics;

   8:  

   9:     g.FillRectangle(Brushes.Black, this.ClientRectangle);

  10:     TextRenderer.DrawText(g, "Hello world!", s_Font, new Point(10, 10), Color.White);

  11:     g.DrawLine(Pens.White, new Point(0, 0), new Point(100,100));

  12: }

Notice that our Font-instance is declared as static because it can be reused when there are many instances of our control.

Of course this technique can only be used if the GDI+ objects are the same every time. If they are highly dynamic then you will have to create a new object every time (this may occur if you are drawing a part of an animation). But don’t forget to dispose these objects with the using-statement.

A Winforms-control should not subscribe to its own events

Each Winforms-control defines many events that can be used to receive all kinds of notifications. Often I see that a control subscribes to its own events, for example:

   1: // this code is added by the designer in the InitializeComponent() method

   2: this.Load += new System.EventHandler(this.Form1_Load);

   3:  

   4: private void Form1_Load(object sender, EventArgs e)

   5: {

   6:     ...

   7: }

This will work OK, but events are conceptually not so simple. They are needed when you need a loose coupling between the publisher and the subscriber. This makes no sense if the publisher and the subscriber are the same control.

There is an alternative that is much simpler: for each event, there is also a virtual method that can be overridden:

   1: protected override void OnLoad(EventArgs e)

   2: {

   3:     base.OnLoad(e);

   4:  

   5:     ...

   6: }

This alternative will also have a slightly better performance. However, you should not forget to call the base-implementation (luckily, this call will be added automatically by IntelliSense). The base-implementation will raise the event, so if you omit this then the other parts of the code will not receive this event from your control.

Casting an array of value types

Warning ahead: this article explains a dirty trick that should only be used in very specific circumstances (when memory conditions are low). I’ve personally seen this used when loading a large image from file (as a byte array) and needing to pass this array to a piece of legacy code that only accepts an array of shorts. Due to the size of the image, it was not feasible to copy the data.

Casting arrays of value types can be problematic. Image that you need to cast a large array of unsigned integers to an array of signed integers.

Our first experiment might be like this:

   1: static int[] Cast(uint[] input)

   2: {

   3:     int[] result = new int[input.Length];

   4:     

   5:     Array.Copy(input, result, input.Length);    // throws ArrayTypeMismatchException

   6:  

   7:     return result;

   8: }

This does not work. We get an ArrayTypeMismatchException because the two types are not compatible (the rules for compatible types are explained here).

The solution is to use the Marshal.Copy() method. This requires unsafe code however.
Here is an example:

   1: static unsafe int[] Cast(uint[] input)

   2: {

   3:     int[] result = new int[input.Length];

   4:  

   5:     fixed(uint* pInput = input)

   6:     {

   7:         Marshal.Copy(new IntPtr(pInput),result,0, input.Length);

   8:     }

   9:  

  10:     return result;

  11: }

This seems to work, but instead of casting the array we really made a copy of the array. The differences are subtle but can be important:

• the copy requires its own memory. If the array is very large, this can be a problem. I’ve encountered situations (e.g. in image processing) where this was not acceptable.
• when the copy is modified, the original array is left untouched. This is not what should happen when we cast a variable.

Using a dirty trick it is possible to cast an array of value types without copying the data. Look at this sample code:

   1: // WARNING: this is a dirty trick. Use at your own risk!

   2: static int[] Convert(uint[] input)

   3: {

   4:     Converter converter = new Converter();

   5:     converter.UInts = input;

   6:     return converter.Ints;

   7: }

   8:  

   9: [StructLayout(LayoutKind.Explicit)]

  10: struct Converter

  11: {

  12:     [FieldOffset(0)]

  13:     public int[] Ints;

  14:  

  15:     [FieldOffset(0)]

  16:     public uint[] UInts;

  17: }

We’re using a Converter-struct that uses some interop-magic to define two fields that map to the same location in memory. Now we can access the same data as an int[] or as an uint[]. The data is not copied in any way!

Note that this is a dirty trick: we fool the compiler into thinking that the type of the array is changed but it really is not. You can verify this by calling GetType() on the returned array: it will return System.UInt32[].

This trick can be used in other situations as well, for instance to access an array of integers as an array of bytes (without copying the data).

Warning: if the size of the array to be converted is reasonably small, you should just copy the data! Only use this trick if you really cannot afford to copy the data! This trick violates the type-safety of the runtime and is not guarantee to work in all situations or in future versions of .NET!

Removing items from a collection

A common coding pattern is removing items from a collection based on the value of the items. The simplest way to do this is to enumerate the collection, and remove all the items that you don't want.

Code example:

   1: List<string> colors = new List<string>();

   2: colors.Add("red");

   3: colors.Add("green");

   4: colors.Add("blue");

   5:  

   6: foreach (string color in colors) // WARNING: this code will throw an exception

   7: {

   8:     if (color == "green") colors.Remove("green");

   9: }

However, doing this will throw this exception: System.InvalidOperationException: Collection was modified; enumeration operation may not execute. It seems that the enumerator is invalid after the collection has been modified.

There are several ways to work around this behavior.

1 Store the items to be removed in a temporary collection

This approach is really simple: instead of immedeately removing the items, we keep them in a separate collection. In the end, after the original list has been enumerated, we remove all these items.

Code example:

   1: List<string> colors = new List<string>();

   2: colors.Add("red");

   3: colors.Add("green");

   4: colors.Add("blue");

   5:  

   6: List<string> itemsToRemove = new List<string>();

   7: foreach (string color in colors)

   8: {

   9:     if (color == "green") itemsToRemove.Add("green");

  10: }

  11:  

  12: foreach (string itemToRemove in itemsToRemove) colors.Remove(itemToRemove);

In most situations this approach works very well. Only in very large collections, the itemsToRemove collection may become very big and consume a lot of memory. In my experience this is seldom the case.

2 Iterate the collection from back to front

This alternative uses a for-loop to iterate the collection from the back to the front.

Code example:

   1: List<string> colors = new List<string>();

   2: colors.Add("red");

   3: colors.Add("green");

   4: colors.Add("blue");

   5:  

   6: for (int counter = colors.Count - 1; counter >= 0; counter--)

   7: {

   8:     if (colors[counter] == "green") colors.RemoveAt(counter);

   9: }

Here we do not need a temporary collection. It is also slightly more efficient because we can remove the item based on its index. This means that the collection does not have to search for the item that has to be removed (as was the case in the first approach).

3 Using a predicate

The third alternative is only available from .NET 2 onwards. The List-collection implements a RemoveAll() method that takes a predicate as a parameter. Simply put, a predicate is a delegate that is used for filtering. In this case, the predicate returns true for each item that needs to be removed.

In this code example, the predicate is implemented as an anonymous method:

   1: List<string> colors = new List<string>();

   2: colors.Add("red");

   3: colors.Add("green");

   4: colors.Add("blue");

   5:  

   6: colors.RemoveAll(delegate(string color)

   7: {

   8:     return color == "green";

   9: });

This approach has some benefits:

• It is self-documenting.
• We don’t have to worry about the performance, we can assume that the RemoveAll() method is implemented in the most efficient way. If the internals of the collection-class would later change, the RemoveAll() method will likely be changed as well to keep the best performance.

A type-safe pattern to implement ICloneable and similar interfaces

The ICloneable interface contains a single method Clone() that returns a clone of the object.

However the return value is defined as type ‘System.Object’, which means that the user still has to cast this to the actual type:

   1: Test t = new Test();

   2: Test t2 = t.Clone() as Test;    // cast needed

This is cumbersome and error-prone because the cast may fail at runtime.

Use the following pattern to provide a type-safe implementation of this interface:

   1: class Test : ICloneable

   2: {

   3:     int m_Amount;  // just some example data...

   4:     Font m_Font;

   5:     string m_Name;

   6:  

   7:     #region ICloneable Members

   8:  

   9:     // Provide a type-safe implementation

  10:     public Test Clone()

  11:     {

  12:         Test clone = new Test();

  13:         clone.m_Amount = m_Amount;

  14:         clone.m_Font = m_Font.Clone() as Font;

  15:         clone.m_Name = m_Name;

  16:         return clone;

  17:     }

  18:  

  19:     // Provide an "Explicit Interface Method Implementation"

  20:     object ICloneable.Clone()

  21:     {

  22:         return Clone();

  23:     }

  24:  

  25:     #endregion

  26: }

This example implements a type-safe Clone() method, so the user does not have to cast the result. But we still have to implement the interface-method that returns a System.Object. This is done through explicit interface method implementation.

This pattern is easier for the user of the class, and it has the benefit that the compiler will now guarantee that the returned object is always of the correct type.

Beware of the stopwatch

In a comment on my last post, craniac argued that the StopWatch-class should be used for measuring time intervals.

Sadly, measuring a time interval is not as easy as it sounds. There are several mechanisms, I will explain 3 of them and point out their strengths and weaknesses.

1. DateTime.UtcNow

   1: DateTime begin = DateTime.UtcNow;

   2:  

   3: ...

   4:  

   5: DateTime end = DateTime.UtcNow;

   6: Console.WriteLine("Measured time: " + (end-begin).TotalMilliseconds + " ms.");

This is the fastest mechanism because under the hood it only reads a counter from memory (the code above takes only 76 nanoseconds to execute on my machine). However the resolution is not so great: only 10 milliseconds on recent version of Windows. If you want to measure a piece of code that takes shorter to execute, you will have to execute it e.g. 1000 times and measure how long this takes, then divide the result by 1000.

Another disadvantage is that this is not reliable if the system-time changes. This should be a very rare situation, but could for instance happen through synchronization with a time server.

2. Stopwatch

   1: Stopwatch watch = new Stopwatch();

   2: watch.Start();

   3:  

   4: ...

   5:  

   6: watch.Stop();

   7: Console.WriteLine("Measured time: " + watch.Elapsed.TotalMilliseconds + " ms.");

This mechanism is a bit slower than the previous one (10 times slower on my machine) so for short intervals this may have an impact on the result. However there are some serious issues:

• This can be unreliable on a PC with multiple processors. Due to a bug in the BIOS, Start() and Stop() must be executed on the same processor to get a correct result.
• This is unreliable on processors that do not have a constant clock speed (most processors can reduce the clock speed to conserve energy). This is explained in detail here.

I suspect that you can get a reliable result if you run it on a single-processor machine and disable any power-saving options in the BIOS. I haven’t tested this though.

On the upside, it has the hightest possible resolution (which depends on the hardware it runs on).

3. Process.TotalProcessorTime

   1: TimeSpan begin = Process.GetCurrentProcess().TotalProcessorTime;

   2:  

   3: ...

   4:  

   5: TimeSpan end = Process.GetCurrentProcess().TotalProcessorTime;

   6: Console.WriteLine("Measured time: " + (end - begin).TotalMilliseconds + " ms.");

This mechanism is different from the previous ones because it does not measure how much time has passed, but it measures how long your process has kept the CPU busy. This is great for performance measurements:

• The timings are not distorted by other processes that consume a lot of CPU.
• You can measure the impact that your code has on the overall performance of the system. On laptops, this also gives an indication towards the battery-power that is consumed by your process. This can be important for applications that run for a long time (such as services and other background tasks).

To interpret the measured time correctly, you should realize that time that is spent while your code is waiting (e.g. in a Sleep) will not be counted. On the other hand, if your process is keeping multiple processors busy, the time of each processor will be added (if a dual-core processor is kept 100% busy, the ‘TotalProcessorTime’ will increment with 2 each second!).

Note that this mechanism has the worst performance: the code above takes 19264 nanoseconds on my PC. This is 250 times slower than using DateTime.UtcNow!

So there is not one-size-fits-all solution to measure a time interval. Personally, if I want to measure how long a piece of code takes to execute, I run it in a loop (e.g. one million times) and measure it using DateTime.UtcNow.

Sometimes it is better to use DateTime.UtcNow instead of DateTime.Now

When you want to measure how long a certain action takes, you should use DateTime.UtcNow instead of DateTime.Now:

   1: DateTime begin = DateTime.UtcNow;

   2:  

   3: ...

   4:  

   5: DateTime end = DateTime.UtcNow;

   6: MessageBox.Show("Time taken: " + (end-begin).TotalMilliseconds);

Reasons:

• DateTime.UtcNow is more efficient than DateTime.Now (on my PC: 21 nanoseconds versus 575 nanoseconds).
• More importantly: DateTime.Now will get you into trouble if Daylight Saving Time is enabled. For instance, it is possible that begin contains 02:59:00 and end contains 02:01:00 (while only two minutes have elapsed).

Of course, both mechanisms are incorrect if the user changes his clock (manually or through synchronziation with a time server).

Avoid invoking a virtual method in a constructor

You should be very careful when invoking a virtual method in the constructor of a class that is not sealed.

Reason: when the virtual method is overriden in a derived class, this method will be invoked even before the constructor of the derived class has been invoked! This probably was not anticipated by the developer of the derived class!

Take for instance this example:

   1: abstract class Base

   2: {

   3:     public Base() // This constructor calls a virtual method

   4:     {

   5:         Initialize();

   6:     }

   7:  

   8:     protected abstract void Initialize();

   9: }

  10:  

  11: class Derived : Base

  12: {

  13:     FileStream m_File;

  14:  

  15:     public Derived()

  16:     {

  17:         m_File = new FileStream(@"c:\temp\test.txt", FileMode.Open);

  18:     }

  19:  

  20:     protected override void Initialize()

  21:     {

  22:         MessageBox.Show(m_File.Length.ToString());    // NullReferenceException! m_File has not been constructed yet!

  23:     }

  24: }

When an instance of Derived is created, first the constructor of the base class is called. This will result in Derived.Initialize() being called before the constructor of Derived has executed!

Because this is very contra-intuitive, it is best not to invoke virtual methods from a constructor altogether. Except when the class is sealed of course, because then there can be no derived class.