TimL on C#.NET

C# and .NET provide a variety of ways to execute code asynchronously. You could, for example, execute a method via a ThreadStart. You could also trap the DoWork event of a BackgroundWorker component. A seemingly simpler way, however, is to simply use the BeginInvoke method of a delegate.

We are all familiar with BeginInvoke: it's what we C#.NET programmers use all the time to schedule something to be executed on the main UI thread, right? Well, not exactly. BeginInvoke causes something to be executed on an appropriate thread, and it just so happens that the appropriate thread for Control.BeginInvoke happens to be the thread on which the control's Window handle was created. And, very convieniently for us, the appropriate thread for a Delegate.BeginInvoke happens to be a background worker thread.

A delegate can be use to easily execute any method on a background thread, even if that method has ref parameters, out parameters and returns a value or throws an exception. Consider the method below.

string MyMethod(string p1, ref string p2, out string p3)
{
   // Let's assume that this is some code that can
   // 1) Takes a long time to execute
   // 2) Uses p1 and p2 as inputs
   // 3) Returns p2, p3 and a return value
   // 4) Can throw exceptions
   ...
}

 

To execute the method asynchronously using a Delegate.BeginInvoke, we first need to define a delegate that has the same signature of the method to be executed on the background thread.

delegate string MyMethodDelegate(string p1, ref string p2, out string p3);

 

Next, we simply create an instance of the delegate, and call BeginInvoke on that delegate. We pass all of the parameters into the delegate, as well as an instance of an AsyncCallback that points to the method that should be called when the invoked method has completed. We also pass a reference to the delegate as the AsyncState. The AsyncState can be any object, but I'll explain why we should use the delegate in a minute.

MyMethodDelegate myDelegate = new MyMethodDelegate(MyMethod);

myDelegate.BeginInvoke(
   p1, ref p2, out p3,
   new AsyncCallback(MyMethodCallback),
   myDelegate ); // Note that we are passing the delegate as the AsyncState!

 

Ok, now for the callback. When MyMethod is done being invoke on a background thread -- whether it succeeds or throws an exception -- the method MyMethodCallback will be called. Since MyMethodCallback is pointed to by an AsyncCallback, it must take exactly one IAsyncResult parameter and return void.

void MyMethodCallback(IAsyncResult ar)
{
   ...
}

 

You may be asking if the callback only takes an IAsyncResult and only returns void, how do we get the return values back from MyMethod? Simple! Remember how we passed the instance of myDelegate as the AsyncState? We can get it back from the IAsyncResult.AsyncState cast back as the delegate, then call EndInvoke on that delegate to get p2, p3 and return value, and even trap an exception that may have been thrown.

void MyMethodCallback(IAsyncResult ar)
{
    MyMethodDelegate myDelegate = ar.AsyncState as MyMethodDelegate;

    string p2 = null;
    string p3;
    try
    {
        string result = myDelegate.EndInvoke(ref p2, out p3, ar);
    }
    catch
    {
        // Any exceptions thrown by MyDelegate while it was executed
        // on the background thread can be caught here.
    }
}

 

There are a few things to notice above. For starters, because the p2 parameter is a reference parameter, it must be initialized before it can be passed into EndInvoke. But, whatever it is initialized to is totally irrelevant because it is only being passed into EndInvoke to get the modified value back out. You can initialize p2 to anything, as long as you initialize it to something (including null) so that the compiler does not complain.

Secondly, note that you do not have access to parameter p1 from within MyMethodCallback. And, since the delegate was passed as the AsyncState you cannot pass p1 as the AsyncState. Therefore, if the callback needs access to any values that are not returned as reference parameters, out parameters or method returns values you will either have to store them as instance member variables, or perharps pass some object that includes the delegate and those variables as the AsyncState instead of just the delegate.

Thirdly, keep in mind that the method is executed on a background thread, and that the callback will occur on that backrgound thread. Therefore, you have all of the normal threading things to worry about. For example, let's say parameter p1 was an instance of some object other than a string. It would be quite possible that some other thread could have changed a value of a property on the object after BeginInvoke was called but before the method was actually exected; even worse the value of that property could be changed while the invoked method is still executing.

It's no secret...all WinForms programmers know that you can only access most properties and methods of a control from the thread that created the control; typically this is the main UI thread. If you attempt to access a control's property or method from another thread, you will get an InvalidOperationException that says "Cross-thread operation not valid:". [ Actually, you only get that exception on .NET 1.1 and later; .NET 1.0 would just lockup. ]

Typically, the programmer would check InvokeRequired on the form or control, and do a BeginInvoke if the code had to be scheduled to run on the appropriate thread.

Many programmers choose to re-invoke the same method, as shown in the example below.

// Declare a delegate to be used with BeginInvoke
delegate void MyDelegate(int a, int);

// Run the method
void MyMethod1(int a, int b)
{
    if (this.InvokeRequired)
    {
        // Reinvoke the same method if necessary
        BeginInvoke(
            new MyDelegate(MyMethod1),
            new object[]{a, b} );
    }
    else
    {
       // Do Whatever you need to do here
       ...
    }
}

 

But, there is no requirement to have to invoke the same method. Many programmers choose to invoke a seperate method. It takes a bit more code, but invoking a different method can be a little better performance-wise because it allows you to do some stuff on the calling thread before re-invoking onto the main UI thread.

// Run the method
void MyMethod2(int a, int b)
{
    // Do some calculations why still on the calling thread
    int y = 2 * a + b;
    int z = 4 * b + y;

    // Call a different method, passing in the calculated values
    if (this.InvokeRequired)
    {
        // BeginInvoke to schedule it on the main UI thread
        BeginInvoke(
            new MyDelegate(MyMethod2_Internal),
            new object[]{y, z} );
    }
    else
    {
        // Already on the main UI thread -- just call the method
        MyMethod2_Internal(y, z);
    }

    // Method that does all the work
    private void MyMethod2_Internal(
        int m,
        int n)
    {
        // Do Whatever you need to do here
        ...
    }
}

 

In either case, you see that BeginInvoke requires an instance of a delegate to be invoked and an object array of the parameters to be passed in. If your method is an event handler, there is most certainly already a delegate defined or you would not have been able to attach to the event. But, if your method is not an event handler, then you end up having to define a delegate such as MyDelegate in the examples above.

Starting with .NET 2.0, there is actually an easier way to do the BeginInvoke using a MethodInvoker and an anonymous method without having to define a separate delegate. This is shown below.

// Run the method
void MyMethod1b(int a, int b)
{
    if (this.InvokeRequired)
    {
        // Reinvoke the same method if necessary
        BeginInvoke( new MethodInvoker( delegate() { MyMethod1b(a, b); } ) );
    }
    else
    {
       // Do Whatever you need to do here
       ...
    }
}

 

This "trick" works because anonymous methods have access to the "outer variables", which are the variables available in the parent's scope. In the example above, a and b are outer variables, and are therefore available inside the anonymous method even though they are not passed as parameters [ I did not do delegate( int a, int b) ]. Since the anonymous method does not take parameters, the pre-defined MethodInvoker delegate can be used without having to create a new delegate. And, as an added bonus, the variables do not have to be placed in an object, so there isno boxing and unboxing of value-type parameters.

NOTE: If you are going to use the MethodInvoker / anonymous delegate trick above, you should really read one of my other post on the scope of bariables entitled "For Loops, Variable Scope and Anonymous Delegates with Outer Variables".

That's really all I had intended for this post, but there are a few side details I thought I would point out while I was on the subject

• There are only four things on a control that can always safely be accessed from another thread: InvokeRequired, Invoke(), BeginInvoke() and EndInvoke().


• The CreateGraphics() method can also be safely accessed from another thread, but only after the Windows handle has been created.


• InvokeRequired can return false even though you are not on the main UI thread! Specifically, it will return false if it cannot find an appropriate Window handle by searching up the control chain starting with the control.


• If InvokeRequired returns false, you can call IsHandleCreated to see if a control's Window handle has already been created.


• Calling BeginInvoke before a control's Window handle has been created throws an exception.


• If the Windows handle has not already been created, accessing a control's Handle property causes the Window handle to be created on the thread that called the property.


• Since BeginInvoke is asynchronous, don't allow the method that is invoked to throw exceptions because they will be untrapped.

StringBuilder...StringBuilder...StringBuilder! We have have all heard that in C#.NET, programmers should use StringBuilder for string concetenation. Some initial testing I had done awhile back seemed to indicate that is not necessarily the case. If your cocatenation occurs within the same statement, then just using the + operator seemed to have better performance.

// String Concatenation Using + in one statement is effecient
string z = a + b + c + d + e;  // You get the idea

 

But, if your concatenation occured across multiple lines of code or within each pass of a loop, then the StringBuilder seemed faster.

// String Builder should be used 
StringBuilder sb = new StringBuilder();
for (int x = 0; x < 10; x++)
{
    sb.Append(x);
}
string z = sb.ToString();

 

I was going to investigate this further and come up with some proof. But, I happened across the following excellent post on John's Performance Blog and I didn't think there was any need to reverse engineer the wheel again.

We've all seen them, and probably occasionally written them. And, if you're unlucky you've probably even had to modify them when they're written by other programmers. I'm talking about those huge "megalithic" functions -- a single method that is hundreds of lines of code and reaches 14 indents deep. Such methods are often difficult to refactor because of their complexity; any attempt to refactor them results in passing tons of variables as parameters, or creating custom structures or classes just to pass parameters around. I have come up with a time-honored solution that is proven to work for me in such cases.

I am not a big patterns guy. I am not against patterns -- it's just that I have never even read a single book on programming patterns. Yet, at the same time, I use common patterns because of solutions I have come up with myself or picked up from others over the years. So, forgive me if this is already a pattern known by a different name, but I believe it to be a pattern that I have created on my own. I am talking about what I call SUPIO: Single Use Per Instance Objects, the purpose of which is to refactor huge, monolithic methods.

A SUPIO is similar to a functor, but with a different purpose. The purpose of a SUPIO to refactor code, whereas the purpose of a functor is to pass a function along with its input parameters and expose a common mechanism for executing the function via an Execute() method.

The idea behind SUPIO is simple: Create a dedicated class that exposes one public static method that takes any necessary parameters. That static method creates an instance of an object, stores the input parameters in the object, executes a single instance method, and returns the results of that instance method out of the static function without ever actually returning the instance object that was created to do the work. That root instance method may in turn call other instance methods without passing a ton of parameters around because many things can be store as private instance member variables.

The example below illustrates these concepts. Keep in mind that using a SUPIO for this particular problem is overkill. But, as the complexity of the method goes up, so does the bennefit of using a SUPIO. In my experience, few things ever start as SUPIOs. Rather, a method is refactored into SUPIO as its complexity reaches the point of unmaintainability. [Most of the time this is when I have to modify a megalithic method written by someone else.] Hopefully you can refactor it before it implodes, or perhaps even have the forsight of starting it as a SUPIO if you know the logic is going to be outrageously complex.

// A SUPIO class will generally be internal because it makes for
// a non-friendyly API if it is exposed out of the assembly.
internal class MySupio
{
    // This is the static method that exposes the single
    // functionality of the SUPIO
    public static bool DoSomething(int x, int y, out int z)
    {
       // Create an instance of the object, execute the function
       // and return its results
       MySupio mySupio = new MySupio(x, y);
       bool retVal = mySupio.Execute(out z);
       return retVal;
    }

    // Declare parameters and calculated values needed by
    // multiple private instance methods as private instance
    // member variables.
    private int _x;
    private int _y;
    private int _a;
    private int _b;

    // The constructor is private to ensure that an instance
    // is only created by the public static method that exposes
    // the function of the SUPIO.
    private MySupio(int x, int y)
    {
        // Store input parameters as private instance member variables
        // so they can easily be shared between instance methods
        _x = x;
        _y = y;

        // Calculate any additional values that may be needed often
        // across multiple instance methods.
        _a = 2 * _x + _y;
    }

    // Execute the function of the SUPIO.  (Note that this
    // method has been fabricated for this example to do some logic
    // and use variables that were input parameters, calculated
    // from the input parameters, and returnd from other methods.)
    private bool Execute(out z)
    {
        int c;
        switch(_x.CompareTo(_y))
        {
            case -1:
                c = XLessThanY();
                break;

            case 0:
                c = XEqualToY();
                break;

            case 1:
                c = XGreatherThanY();
                break;
        }

        z = c * _b;
    }

    private int XLessThanY()
    {
        ...
    }

    private int XEqualToY()
    {
        ...
    }

    private int XGreaterThanY()
    {
        ...
    }
}

// If the function performed by the SUPIO needs to be exposed
// out of an API it can easily be accomodated.
public static MyLibraryClass
{
    public static bool CallMySupio(int x, int y, out int z)
    {
        return MySupio.DoSomething(x, y, out z);
    }

    public static bool MyNonSupio( ... )
    {
        ...
    }
}

Some people my question why an instance of an object has to be created? Why not just create a static class, with static member variables and static methods. The problem with that is that you can only have one thread in the method at the same time, and it is cannot recursive.

The .NET framework 2.0 introduced the concept of static classes. A static class is marked with the keyword static, cannot be instantiated and can only have static members. It can have static fields, properties, methods, events, indexers and even a parameterless static constructor (refer to a previous post on static constructors.)

You cannot derive one static class from another class (static or non-static); static classes are always sealed! This is because the object-oriented paradigms such as inheritance and polymorphism make absolutely no sense without runtime instances of objects. Likewise, you cannot cast an instance of any object to a static class because that makes no sense.

Like a static class, an abstract class cannot be instantiated. And, like a static class, an abstract class can contain static fields, properties, methods, events, indexers and static constructors. But, the intended purpose of a static class is very different from that of an abstract class. Unlike a static class from which you cannot derive other classes, the whole purpose of an abstract class is to act as a base class from which you will derive other classes. In addition to its static members, an abstract class can also have instance fields, properties, methods, events, indexers and constructors. And, although an abstract class cannot be created with new, an instance of a class derived from an abstract class can be cast to the abstract class using as.

A class that is declared with neither the static nor abstract keyword can also contain static fields, properties, methods, events, indexers and constructors. And, such a class can also have instance fields, properties, methods, events, indexers and constructors. But, unlike static and abstract classes, a class that is neither static nor abstract can be instantiated with new and can be cast as any class "above it" in the class derivation tree.

Before static classes, one of the old "tricks" was to define a private constructor. By default, if a class defines no instance consructors the compiler will automatically create a parameterless default constructor. But, if even a single instance constructor is defined with any number of parameters and any access level, the compiler will not create the default constructor.

If all three types of classes can contain static fields, properties, methods, events indexers and constructors, you may wonder why a static class is needed at all. Especially if you can define a private constructor to keep an object from being created. The answer is simple: the sooner you find a bug, the cheaper it is to fix. One of the common bugs of many [even experienced] developers is to accidentally leave the static keyword off of members that are intended to be static. Defining the class as static enforces the intended design by providing compile-time errors if non-static members are encountered.

So-called "Function library" classes are an excellent use for static classes, especially since C#.NET does not support functions defined outside of a class. This is particularly useful if such functions work on interfaces instead of objects instances, thus allowing you to pass-in objects from any derivation tree as long as they support the interface. In such classes, each method is typically is a self-contained function.

You can even use a static class to implement something like a singleton pattern, as is shown in the example below compared to a more typical singleton pattern.

// Define the static singleton class
static class StaticSingleton
{
    // It is adviseable to make to lock object readonly
    // to prevent it from being changed accidentally
    private static readonly object s_dataLock =
        new object();

    private static long s_count = 0;

    public static long Increment()
    {
        long newValue;
        lock(s_dataLock )
        {
            newValue = ++s_count;
        }
        return newValue;
    }

    public static long Decrement()
    {
        long newValue;
        lock(s_dataLock )
        {
            newValue = --s_count;
        }
        return newValue;
    }
}


// Define the instance singleton class
// It is adviseable to make all singleton classes sealed.
class sealed InstanceSingleton
{
    // It is adviseable to make to the singleton object
    // readonly to prevent it from being changed accidentally
    private static readonly InstanceSingle s_instance =
        new InstanceSingleton();

    // It is adviseable to make to lock object readonly
    // to prevent it from being changed accidentally
    private readonly object _flagLock = new object();

    private long _count = 0;

    // Constructor is private to ensure that an instance can
    // only be created by the class
    private InstanceSingleton()
    {
    }

    // Returns a reference to the instance
    public static Instance
    {
        get
        {
            return s_instance;
        }
    }

    public long Increment()
    {
        long newValue;
        lock(_dataLock )
        {
            newValue = ++_count;
        }
        return newValue;
    }

    public long Decrement()
    {
        long newValue;
        lock(_dataLock )
        {
            newValue = --_count;
        }
        return newValue;
    }
}

// Using the static singleton
StaticSingleton.Increment();
StaticSingleton.Decrement();

// Using the instance singleton
InstanceSingleton.Instance.Increment();
InstanceSingleton.Instance.Decrement();

 

Although not technically a singleton because it never creates an instance of an object, the static class approach takes less code to implement and use. However, using a static class as a singleton does not give me a "warm and cozy feeling". I am not a big fan of it for several reasons, all of which arise because there is not instance of an object.

• You cannot pass the instance into another method. For example, what if I wanted to have multiple singleton classes that each implemented a common interface, then have some kind of factory method choose the right singleton to be pass into some other method.


• How the heck do you free the resources? With a more typical singleton pattern, if I decide I no longer need the instance I can set it to null (through a Release method, etc), thus releasing the reference and freeing all the resources used by the instance.


• It is harder to-reinitialize. With a more typical singleton pattern, I can set the existing instance to null and create a new instance if I want. For example, the class itself could even be watching for some kind of event to trigger that action.


• Will the singleton always be a singleton? I can recall more than one occasion in which I eventually needed more than one instance of something I thought was a singleton. In such case, changing from an Instance property to a GetInstance() method that takes a few parameters is quite trivial. Had I used a static class in those case, it would have taken a signifcant amount of rework.

This blog post was not really intended to be a "best practices" on implementing a singleton pattern in C#. Rather, it was simply intended to highlight a few things about static classes. If you're interested in learning more about instance singleton patterns in C#, checkout the Microsoft Patterns & Practices: Implementing Singleton in C#

All C# programmers are familiar with the enum keyword. Conceptually speaking, an enum is not much more than a named list of constants that represent possible numeric values.

enum MyEnum1
{
    ValueA,
    ValueB
}

 

As stated in a previous post, it is possible for the last item in the enum declaration to end with a comma. This is intended to facilitate easier resposition of the values, as well as easier auto-generation of enums from development tools.

enum MyEnum2
{
    ValueA,
    ValueB,
}

 

When an enum is declared, the compiler automatically creates a new type derived from the System.Enum class. That new type uses one of the numeric system types to store the enum value. By default, an int is used to as the underlying type to store the value. But, that underlying type can actually be a signed or unsigned byte, short, int or long.

NOTE: If the underlying data type is changed, the enum may no longer be CLS compliant because some languages such as VB.NET do not support all of the types.

enum MyEnum3a          // Underlying data type is int
{
    ValueA,
    ValueB
}

enum MyEnum3b : ulong  // Underlying data type is ulong
{
    ValueA,
    ValueB
}

 

Each value listed in the enum is associated with a number in the underlying numeric data type. By default, the first value in the enum is assigned the numeric value of 0. But, the initial value can be changed. The underlying numeric value is automatically incremented by one for each enum value thereafter for which a specific value is not specified.

enum MyEnum4a
{
    ValueA,        // Underlying numeric value is 0
    ValueB,        // Underlying numeric value is 1
    ValueC,        // Underlying numeric value is 2
    ValueD         // Underlying numeric value is 3
}

enum MyEnum4b
{
    ValueA,        // Underlying numeric value is 0
    ValueB,        // Underlying numeric value is 1
    ValueC = 200,  // Underlying numeric value is 200
    ValueD         // Underlying numeric value is 201
}

enum MyEnum4c
{
    ValueA = 100,  // Underlying numeric value is 100
    ValueB,        // Underlying numeric value is 101
    ValueC = 200,  // Underlying numeric value is 200
    ValueD         // Underkying numeric value is 201
}

 

Because each value of an enum is associated with an underlying numeric data type, you can actually use enum values in math and conditional operations as long as you cast it to the underlying type.

int x = 2 * (int)MyEnum4c.ValueC; // x == 400

int y = 500;
if (y > (int)MyEnum4c.ValueD)
{
   DoSomething(y);
}

 

You can also use enums in conditionals without casting as long as you are comparing it against enum values of the same enum type.

MyEnum4c e = MyEnum4c.ValueC;

if (e < MyEnum4c.ValueC)
{
    ...
}
else if (e == MyEnum4c.ValueC)
{
    ...
}
else
{
    ...
}

switch (e)
{
    case MyEnum4c.ValueA:
    case MyEnum4c.ValueB:
        DoSomething();
        break;

    case MyEnum4c.ValueC:
        DoSomething();
        break;

    case MyEnum4c.ValueD:
        DoSomething();
        break;

    // Always a good idead to trap default in case someone adds
    // another enum value but forgets to add it to the case.
    default:
        Debug.Assert(false, "Oops!  Unknown enum value " + e.ToString() );
}

 

It is convention to declare an enum value None if you will need to "clear" the value, or represent an initial or unknow state. The enum values Unknown and Default are also used frequently in practice. These are typically declared as the first value of the enum, and therefore default to an assigned value of zero.

enum MyEnum5a
{
    None,
    ValueA,
    ValueB
}

enum MyEnum5b
{
    Unknown,
    ValueA,
    ValueB
}

enum MyEnum5c
{
    Default,
    ValueA,
    ValueB
}

 

Although it may seem tempting to do so, it is considered to be bad practice to "mark" the boundaries of an enum with another enum value; such "markers" do not represent data values, and have no business being declared in something for which the sole purpose of being created is to represent possible data values.

// *** Start Bad Practice **
enum MyEnum6a
{
   ValueA,
   ValueB,
   LastValue
}

enum MyEnum6b
{
   ValueA,
   ValueB,
   LastValue = ValueB,
}
// *** End Bad Practice ***

 

The reason someone may typically want to "mark" the last enum value is often because he or she wants to loop over all possible values. However, marking the boundaries is error-prone for several reasons:

• The programmer may forget to update the marker's numeric value when enum values are added or removed


• It does not accommodate gaps in the numeric values


• It does not handle multiple bits being set when the [Flags] attribute is used (described later in this post)

Instead, you should consider using the static Enum.GetValues(), Enum.GetName() and Enum.GetNames() methods.

foreach(int x in Enum.GetValues(typeof(MyEnum4c)))
{
    DoSomething(x);
}

 

Under most circumstances, a variable of type enum can only contain a single value. The [Flags] attribute (System.FlagsAttribute) can be used, however, to indicate that a variable of type enum can be a composite of zero or more enum values.

[Flags]
enum MyEnum7
{
    ValueA = 1,
    ValueB = 2,
    ValueC = 4,
    ValueD = 8
}

 

As a general rule, when using the [Flags] attribute, you will want to specifically map each unique enum value to an underlying numeric value that is a power of 2 (see example above). The compiler will not automatically do that for you, and will not enforce that you do it yourself either. This is because you may want to define "group" values that represent combinations of two or more possible values.

[Flags]
enum MyBits : byte
{
    None = 0,
    Bit0 = 1,
    Bit1 = 2,
    Bit2 = 4,
    Bit3 = 8,
    Bit4 = 16,
    Bit5 = 32,
    Bit6 = 64,
    Bit7 = 128,
    LowerNibble = Bit0 | Bit1 | Bit2 | Bit3,  // Group value
    UpperNibble = Bit4 | Bit4 | Bit6 | Bit7   // Group value
}

 

As was implied in the example above, the bitwise operators and bitwise assignment operators are very useful for enums that have been declared with the [Flags] attribute.

• | and |= (bitwise OR and bitwise OR Assignment operators)


• & and &= (bitwise AND and bitwise AND Assignment operators)


• ^ and ^= (bitwise XOR and bitwise XOR Assignment operators)


• ~ and ~= (bitwise NOT and bitwise NOT Assignment operators)

// Assign multiple enum values
MyBits bitsA = MyBits.Bit0 | MyBits.Bit3 | MyBits.Bit7;
MyBits bitsB = MyBits.Bit0 | MyBits.Bit1;

// Get all the enum values that are not on in bitsA
MyBits oppositeBits = ~bitsA; // See text below this example!

// Get all the enum values that are on in bitsA and/or bitsB
MyBits compositeBits = bitsA | bitsB;

// Get only those enum values that are on in both bitsA and bitsB
MyBits commonBits = bitsA & bitsB;

// Get only those enum values that are unique to bitsA and bitsB
MyBits uniqueBits = bitsA ^ bitsB;

// Turn on bit 4, then turn it back off
bitsA |= MyBits.Bit4;
bitsA &= (~MyBits.Bit4); // See text below this example!

// Determine if a particular bit is on
bool bit3On = ((bitsA & MyBits.Bit3) == MyBits.Bit3);

// Get only the values for bits 0 - 3
MyBits maskLowerNibble = (bitsA & MyBits.LowerNibble);

// Deteremine if there are any high bits
bool hasHighBits = ((bitsA & MyBits.UpperNibble) > MyBits.None);

// You get the idea!

 

When it comes to the underlying numeric value of an enum, there is something to be aware of. If you are not careful, it is possible to create an enum variable that does not contain a valid enum value (or values if using [Flags]). In fact, in the example above, the bitwise NOT (invert) was used in two places. Had MyBits not declared an enum value for every bit in the underlying byte numeric type, those operations would have created invalid values. Several other samples are shown below.

enum MyEnum8
{
   ValueA,   // Numeric Value == 0
   ValueB    // Numeric Value == 1
}

// Successfully assign invalid numeric values to an enum
MyEnum8 invalidValue1 = ~MyEnum8.ValueA; // invalidValue1 == -1
MyEnum8 invalidValue2 = (MyEnum8)22;     // invalidValue2 == 22

 

Also, if you have declared an enum with the [Flags] attribute, you need to be cautious when using switch statements since the switch works on the underlying numeric value that may actually be a composite of one or more enum values.

switch (bitsA)
{
    case MyBits.Bit0:
        OnlyBitZeroIsOn();
        break;

    case MyBits.Bit1:
        OnlyBitOneIsOn();
        break;

    case MyBits.Bit0 | MyBits.Bit1:
        BothBitsZeroAndOneAreOn();
        break;
}

 

If an enum does not have the [Flags] attribute, converting it back and forth to a string is fairly straight forward.

// Convert to a string
MyEnum8 myEnum8 = MyEnum8.ValueA;
string valueStr = bitsA.ToString();

// Convert back from a string (throw exception if it cannot)
valueStr = "ValueB";
myEnum8 = (MyEnum8)Enum.Parse(typeof(MyEnum8), valueStr);

 

If the enum has been declared with [Flags] attribute, however, conversion back and forth to a string is a bit more difficult. Perhaps I will make that the topic of my next post.

For more information, visit the following MSDN links.
System.Enum class
C# Language Reference

Threads often scare novice programmers. But any experienced programmer will agree that nearly all "real" programs are threaded. If your program is constantly blocked waiting for something to finish, it is practically useless. As soon as a user sees a UI lockup for more than a few seconds, that user will undoubtably start clicking the mouse everywhere, trying to kill things in Task Manager (if they even know how to do that), or even yanking the power cord out of the wall while the computer is still on (thus corrupting the registry and possibly damaging the hard disk).

If your application is threaded, you must synchronize access to data that may potentially be accessed "simultaneously" by different threads. On a 32-bit system, even something as trivial as reading the value of a 64-bit long is not atomic because it takes two processor cycles, and may therefore be interrupted by a thread context-switch. Without some kind of synchronization, there could be a thread context-switch between reading the first 4-bytes and last 4-bytes, and another thread could change the value; the resulting number "read" by the first thread would be neither the old number or new number, but instead a composite of both.

• Initial value is 00112233aabbccdd


• Thread 1 reads upper four bytes: 00112233


• Context switch to Thread 2


• Thread 2 writes eight new bytes: 99887766ffeeddcc


• Context switch back to Thread 1


• Thread 1 reads lower four bytes: ffeeddcc


• Thread 1 thinks the value is 00112233ffeeddcc

The Windows operating system povides the basic synchronization mechanisms in the form of semaphores, mutexes, critical sections, events (different from .NET events) and interlocked operations. .NET wraps all of these in one form or another. C#.NET programmers are probably most familiar with the lock(){...} which internally uses a System.Threading.Monitor, which is really not much more than a critical section. In my opinion, however, the simple interlocked atomic operations are sorely underused; I sometimes wonder if programmers even know they exist.

An operation is said to be atomic if the operating system cannot context-switch to another thread before the operation has completed. As stated earlier, even something like reading a 64-bit number on a 32-bit machine is not inherently atomic. Likewise, the x++, ++x, x--, --x we all know and love are also not atomic. .NET programmers should be happy to hear, however, that .NET does provide some primitive interlocked atomic operations in the System.Threading.Interlocked class. The following method calls are guaranteed to do atomic operations; Windows will not context-switch to another thread before the operations performed by these methods have completed.

// Interlocked.Read(ref a)
// Read and returns 64-bit value
long a = 100;
long z = Interlocked.Read(ref a); // Results: a == 100; z == 100

// Interlocked.Exchange(ref a, b)
// Sets a = b; Returns original value of a
int a = 100;
int b = 200;
int z = Interlocked.Exchange(ref a, b); // Results: a == 200; z == 100

// Interlocked.CompareExchange(ref a, b, c)
// Replace a with b if a == c; Returns original value of a
int a = 100;
int b = 200;
int c1 = 300;
int c2 = 100;
int z1 = Interlocked.CompareExchange(ref a, b, c1); // Results: a == 100; z == 100
int z2 = Interlocked.CompareExchange(ref a, b, c2); // Results: a == 200; z == 100

// Interlocked.Increment(ref a)
// Increments a; Returns new value of a; Wraps w/o exception
int a = 100;
int z = Interlocked.Increment(ref a); // Results: a = 101; z = 101;

// Interlocked.Decrement(ref a)
// Decrements a; Returns new value of a; Wraps w/o exception
int a = 100;
int z = Interlocked.Decrement(ref a); // Results: a = 99; z = 99;

// Interlocked.Add(ref a, b)
// Replace a with a + b; Returns new value of a; Wraps w/o exception
int a = 100;
int b = 200;
System.Threading.Interlocked.Add(ref a, b); // Results: a == 300; z = 300

 
From the comments in the code sample code above, it should be apparent that you need to keep in mind whether the first parameter does or does not change, and whether the new value or original value is returned by the function. This can be summarized in a few basic rules.

• If the interlocked operation causes something to be updated, the first parameter will always have that new value after the operation has completed (Exchange, CompareExchange, Increment, Decrement and Add)


• If the interlocked operation does math, the method always returns the new value of the first parameter(Increment, Decrement and Add)


• If the interlocked operation does not do math, the method always returns the original value of the first parameter (Read, Exchange and CompareExchange)

Also, it should be noted that interlocked math operations do not throw exceptions! on underflows or overflows. Rather, they wrap instead. Because the operations are atomic, they need to be very fast and light-weight. They get in, do their thing, and get out. Throwing exceptions just does not fit that paradigm.

The interlocked operations are simple and useful. But, just because these operations are atomic does not mean you can't still run into problems if you're not careful. You really only get "protection" against other accesses to the same variable by interlocked functions. For example, you could still have problems if you attempt to protect access with a lock in one place but use an Interlocked.Increment in another.

// Variable accessible by both threads
int a = 100;

// Running on Thread 1
object obj = new object();
lock(obj)
{
     a++;
}

// Running on Thread 2
Interlocked.Increment(ref a);

In the example above, the interlock is atomic but the a++ is not. It is quite possible that the following scenario could occur.

• Initial value of a is 100


• Thread 1 reads value of a as 100


• Context switch to Thread 2


• Thread 2 increments value of a to 101


• Context switch back to Thread 1


• Thread 1 increments a from 100 to 101


• The value of a is now 101 instead of 102

This post has nothing to do with C# or .NET, but I decided to post it here anyway because it doesn't really "fit" on any of my other blogs either. For this csharp.timl.net blog, I wanted to somehow create an index of all the pages. I use Blogger, and did not want to have to manually create an index page.

One quick and easy solution I came up with is to use the "site search" feature of Google. As you may or may not know, Google allows you to limit your search results to a particular domain by specifying "site:<domain>" after your search criteria (where "<domain>" is the name of the domain from which results are obtained). I happened to stumble across the fact that if you do no specify any search words and only specify the "site:<domain>" in the Google search box, then Google returns a list of all of the pages.

Whala! That is exactly what I want. The only thing left is turn the search into a hyper link. Here is the example from timl.chsarp.net.

Index of timl.net

Many of you are probably aware that C#.NET allows you to explicitly scope methods, properties, events and indexers to an interface. An simple example of scoping a property directly to an interface is shown below.

interface IMyInterface
{
    bool MyInterfaceProperty { get; set; }
}

class MyClass : IMyInterface
{
    private bool _flag;

    IMyInterface.MyInterfaceProperty
    {
        get { return flag; }
        set { _flag = value }
    }
}

The question becomes, when should you do this? My answer is only when you have a good reason, and there are some good reasons!

C#.NET does not support multiple inheritence. A class, however, can implement more than one interface. Therefore, it is possible that something in an interface could conflict with something in another interface. It is also possible that something in an interface may conflict with something in the parent class from which your class was derived. Ideally, you would resolve the conflict. But, you can only do that if you are "in control" of the parent class and other interfaces.

Explicitly scoping a property, event, method or indexer to a specific interface allows you have different signatures and implementations where the names conflict.

interface IA
{
   int Foo {get;}
}

interface IB
{
   bool Foo {get;}
}

class ClassA
{
   int Foo
   {
      get { return 1; }
   }
}

class ClassB : ClassA, IA, IB
{
    new int Foo
    {
        get { return 2; }
    }

    int IA.Foo
    {
        get { return 3; }
    }

    bool IB.Foo
    {
        get { return false; }
    }
}

However, just because one of the properties was specifically scoped does not mean all of them have to be. For example, Since ClassA.Foo and IA.Foo share the same signature, they can also share the same implementation as is shown below.

class ClassB2 : ClassA, IA, IB
{
    // This method hides Foo from the parent class, and also
    // is used as the implementation of IA.Foo.
    new int Foo
    {
        get { return 2; }
    }

    bool IB.Foo
    {
        get { return false; }
    }
} 

Given the classes and interfaces above, the following results are obtained.

ClassB b = new ClassB();
b.Foo.ToString();               // "2"
(b as ClassA).Foo.ToString();   // "1"
(b as IA).Foo.ToString();       // "3"
(b as IB).Foo.Tostring();       // "False"

ClassB2 b2 = new ClassB2
b2.Foo.ToString();              // "2"
(b2 as ClassA).Foo.ToString();  // "1"
(b2 as IA).Foo.ToString();      // "2"
(b2 as IB).Foo.ToString();      // "False"

Sometime you may have to explicitly scope to an interface to resolve conflicts as is mentioned above. However, there are actually reasons you may want to explicitly scope a something to an interface even when you don't have too. For example, if you want compile-time notice that a method implemented in the class was removed from the interface.

Sometimes you have to do it and sometimes you may want to do it, but explicitly scoping something to an interface does have some drawbacks. For starters, the event, property, method or indexer is actually "more private than private", and may yet still be very public. This is because items scoped directly to the interface can only be accessed via the interface; even the class that implements the property, method, event or indexer that is explicitly scoped to an interface cannot access that item without casting itself as the interface. Yet, at the same time, the item could indeed be very accessible from outside the class, derived class or assembly if the interface itself is public.

public interface ISomeInterface
{
    string SomeMethod { get; }
    string SomeOtherMethod { get; }
}

class SomeClass : ISomeInterface
{
    string SomeMethod()
    {
        return "Hello World 1";
    }

    ISomeInterface.SomeOtherMethod()
    {
        return "Hello World 2";
    }

    void Test()
    {
        string someMetod = SomeMethod();        

#if (true)
        // This DOES compile because this instance is cast to the interface
        string someOtherMethod = (this as ISomeInterface).SomeOtherMethod();
#else
        // This DOES NOT compile because even a class cannot directly access
        // something explicitly scoped to an interface.
        string someOtherMethod = SomeOtherMethod();
        string someOtherMethod = ISomeInterface.SomeOtherMethod();
#endif
    }
}

class SomeOtherClass()
{
    void TestMethod()
    {
        ISomeInterface i = new SomeClass();
        string result = i.SomeOtherMethod();
    }
}

If you think about it, this is probably the reason why an interface cannot specify access modifiers for individual items within an interface. The interface has no idea whether classes implementing the interface will or will not provide implementations that are explicitly scoped to the interface; that is an implementation detail of the class. Specifying an item in an interface as private, protected, internal or public is absolutely nonsensical because if a class chooses to scope an item to the interface then that item is inherently "more private than private".

Similar arguments can be made for other modifiers such as virtual and static. If an item is explicitly scoped to an interface, then it cannot even be accessed directly by the class in which it is implemented; how could you expect it to be overriden by a derived class? Likewise, static makes no sense for an item within an interface; if there is no instance of an object, there is nothing to cast to the interface.

Because of the limitations with modifiers, I recommend that items explicitly scoped to the interface should really be nothing more than a stub that calls something else on the class. Doing so allows modifiers such as virtual to be used as need, as is shown in the following example.

interface IThisInterface
{
   int ThisInterfaceProperty { get; }
}

class ThisClass : IThisInterface
{
    int IThisInterface.ThisInterfaceProperty
    {
        get { return IThisInterface_ThisInterfaceProperty; }
    }

    protected virtual int IThisInterface_ThisInterfaceProperty
    {
       get { return 100; }
    }
}

class ThisOtherClass : ThisClass
{
    protected override int IThisInterface_ThisInterfaceProperty
    {
        get { return 200; }
    }
}

ThisClass thisClass = new ThisClass();
int thisResult = (thisClass as IThisInterface).ThisProperty;           // 100

ThisOtherClass thisOtherClass = new ThisOtherClass();
int thisOtherResult = (thisOtherClass as IThisInterface).ThisProperty; // 200

Another drawback of explicity scoping an item to an interface is the way it must be handled if reflection is used. For example, the Type.GetProperty() method will not return a property that is explicitly scoped to an interface. Rather, the Type.GetInterfaceMap() method may be used.

One interesting thing to point out is that Type.GetInterfaceMap returns an InterfaceMappping object, and that object has an InterfaceMethods property but does not also have corresponding InterfaceProperties, InterfaceEvent or InterfaceIndexers properties. This is because, under the covers, these other types ultimately call methods that are contained in the array returned by InterfaceMethods property. For example, the getter for ThisInterfaceProperty corresponds to a method named get_ThisInterfaceProperty().