jaredpar's WebLog : API Design

The File System is unpredictable

Jared Parsons — Thu, 10 Dec 2009 13:00:00 GMT

One of the more frequent questions I answer on StackOverflow is a variation of the following.

I’m doing XXX with a file, how can I know if the file exists?

The variations include verify no one else has the file open, if the file is in use, the file is not writable, etc …. The answer to all of these questions is unfortunately the same. Simply put you can’t. The reason why is the fundamental nature of the file system prevents such predictive operations.

The file system is a resource with multiple levels of control that is shared between all users and processes in the system. The levels of control include but are not limited to file system and sharing permissions. At any point in time any entity on the computer may change a file system object or it’s controls in any number of ways. For example

The file could be deleted
A file could be created at place one previously did not exist
Permissions could change on the file in such a way that the current process does not have access
Another process could open the file in such a way that is not conducive to sharing
The user remove the USB key containing the file
The network connection to the mapped drive could get disconnected

Or in short

The file system is best viewed as a multi-threaded object over which you have no reliable synchronization capabilities

Many developers, and APIs for that matter, though treat the file system as though it’s a static resource and assume what’s true at one point in time will be true later. Essentially using the result of one operation to predict the success or failure of another. This ignores the possibility of the above actions interweaving in between calls. It leads to code which reads well but executes badly in scenarios where more than one entity is changing the file system.

These problems are best demonstrated by a quick sample. Lets keep it simple and take a stab at a question I’ve seen a few times. The challenge is to write a function which returns all of the text from a file if it exists and an empty string if it does not. To simplify this problem lets assume permissions are not an issue, paths are properly formatted, paths point to local drives and people aren’t randomly ripping out USB keys. Using the System.IO.File APIs we may construct the following solution.

static string ReadTextOrEmpty(string path) {
    if (File.Exists(path)) {
        return File.ReadAllText(path); // Bug!!!
    } else {
        return String.Empty;
    }
}

This code reads great and at a glance looks correct but is actually fundamentally flawed. The reason why is the code changes depends on the call to File.Exist to be true for a large portion of the function. It’s being used to predict the success of the call to ReadAllText. However there is nothing stopping the file from being deleted in between these two calls. In that case the call to File.ReadAllText would throw a FileNotFoundException which is exactly what the API is trying to prevent!

This code is flawed because it’s attempting to use one piece of data to make a prediction about the future state of the file system. This is simply not possible with the way the file system is designed. It’s a shared resource with no reliable synchronization mechanism. File.Exists is much better named as File.ExistedInTheRecentPast (the name gets much worse if you consider the impact of permissions).

Knowing this, how could we write ReadTextOrEmpty in a reliable fashion? Even though you can not make predictions on the file system the failures of operations is a finite set. So instead of attempting to predict successful conditions for the method, why not just execute the operation and deal with the consequences of failure?

static string ReadTextOrEmpty(string path) {
    try {
        return File.ReadAllText(path);
    } catch (DirectoryNotFoundException) {
        return String.Empty;
    } catch (FileNotFoundException) {
        return String.Empty;
    }
}

This implementation provides the original requested behavior. In the case the file exists, for the duration of the operation, it returns the text of the file and if not returns an empty string.

In general I find the above pattern is the best way to approach the file system. Do the operations you want and deal with the consequences of failure in the form of exceptions. To do anything else involves an unreliable prediction in which you still must handle the resulting exceptions.

If this is the case then why have File.Exist at all if the results can’t be trusted? It depends on the level of reliability you want to achieve. In production programs I flag any File.Exist I find as a bug because reliability is a critical component. However you’ll see my personal powershell configuration scripts littered with calls to File.Exsit. Simply put because I’m a bit lazy in those scripts because critical reliability is not important when I’m updating my personal .vimrc file.

Understanding the is, was and will of programming

Jared Parsons — Mon, 27 Apr 2009 15:00:00 GMT

When using an API you must take care to understand not only what it returns, but also for how long the data returned will be valid. This is very important to consider because programs must make either be making decisions on valid and predictable data or have appropriate fallback mechanisms for failure.

I often find bugs because people assumed certain APIs were giving back data about the present or future, but in fact the were giving back information about the past or much shorter present. Part of the problem stems from the fact that API names are usually written in the present tense regardless of what point in time the data returned is valid. For example “Exists” instead of “Existed” or “DidExist”. The language of the API lulls developers into a false sense of security and leads to programming errors.

I like to think of these values as a question of when they are valid. For instance, the data is, was or will be valid.

Will – The data return is valid now and will be valid for the remainder of the program.
Is – The data is valid now and will remain valid until the program or thread takes some action to alter the underlying data source.
Was – The data was valid at some point in the past but by the time the program receives the result it can no longer be relied upon to be valid.

Working with APIs in the “was” category are the trickiest. Because the data we are working with is volatile we must approach them in a different way in order to provide reliable programs. Most algorithms work by validating the present or future state of the system and then executing code with the expectation of success. When working with a “was” API, there is no way validate the state of system because it cannot provide reliable information about its present or future state. Instead we must execute the algorithm with the expectation of failure and spend our time considering how to account for these failures appropriately. Failure must be the expected case, and not the exception.

Working with “will” and “is” APIs is a bit easier. Each has a level of predictability and it’s possible to use program state to make reliable decisions and hence produce reliable results.

Lets add some substance to this conversation by considering these types of APIs and the ContainsKey method on various hashtable style collections. This API is often written in the present tense regardless of how long the data is actually valid.

A “will” API is the safest to work with because the data will always be valid. This API cannot be influenced by side effects. Hence the the programmer is free to think only about the algorithm at hand. These APIs are rare and are typically associated with purely immutable data structures. This is the main type of structure for which data does not ever change. For instance consider this set of calls

var name = "bob";
ImmutableMap<string, Student> map = GetSomeImmutableMap();
if (map.ContainsKey(name)) {
    SomeOtherCall();
    var student = map[name];
}

This call to the indexer will succeed no matter what. The structure cannot be changed irrespective of what actually happens in SomeOtherCall. The ContainsKey method already asserted the key was present in the hashtable. Because the structure is immutable this assertion will be valid for the remainder of the program and hence the indexer must succeed.

An “is” API is the most common type of API. It is generally associated with mutable structures completely within the control of the program / thread. The data will remain valid until it is explicitly, or much worse implicitly, invalidated by the user. In a well factored program it is possible to reason about these types of APIs but hidden side effects can get you into trouble. For instance consider the following code in the context of a single thread.

var name = "bob";
Dictionary<string, Student> map = GetSomeDictionary();
if (map.ContainsKey(name)) {
    Console.WriteLine(map[name]);
    SomeOtherCall();
    Console.WriteLine(map[name]);
}

The state of a Dictionary<TKey,TValue> structure is completely within the control of the program. As such the first call to Console.WriteLine will work fine. There is nothing which can alter the state of map between the call to ContainsKey and the actual accessing of the map in the first WriteLine call so the assertion is still valid.

However without knowing the hidden side effects of the SomeOtherCall API we cannot know the next call to WriteLine will succeed. It’s possible for SomeOtherCall to access the underlying Dictionary reference and Clear it thus making the next call fail. True a programmer must investigate this before writing the above code. But consider the opposite problem. I am the maintainer of SomeOtherCall and I get a bug assigned to me which necessitates clearing out that Dictionary. I must now consider everyone who calls me, directly or indirectly and consider if any of them have an implicit dependency on the state of the underlying Dictionary object. This can get very difficult in a large program.

As previously stated, a “was” API is the most dangerous type of API. They never give back data for which you can make a reliable decision about. These APIs are associated with a data source that is not completely in the control of the current thread or program. Thus it’s possible for the data source to be altered at any point in the execution of the program / thread. Threading is a prime example of this problem.

For an example, consider SynchronizedDictionary to be an implementation of Dictionary<TKey,TValue> which uses locks internally to prevent data corruption from reads / writes on multiple threads but provides no other synchronization capabilities .

var name = "bob";
SynchronizedDictionary<string, Student> map = GetSomeSynchronizedDictionary();
if (map.ContainsKey(name)) {
    var student = map[name];
}

In this example it’s possible for the call to map[name] to fail because another thread came through and cleared the collection in between the if statement and the call to map[name]. The bug here is that the program was written as if ContainsKey gave information about the present or future but in fact only gave information about the past. This actual return of the API could be made clearer by simply altering the name of the API. A much more applicable name is “DidContainKey” or “DidAndMayStillContainKey”. This name is much more representative of the data returned and will hopefully give a developer pause before writing code like the above.

My personal pet peeve in this category is the file system and in particular File.Exists. Notice how this name is written in the present tense indicating a successful return means the file is currently in existence. Lets ignore permissions for a minute[1] and consider only the files existence. Any program on the machine is at liberty to change the file system and can do so at any point in time. Even the user can affect the file system by doing some thing as simple as yanking out a USB thumb drive or stumbling over a network cable. Any of these operations can alter the state of the file system and hence invalidate the existence of a File with 0 action from your program. Hence File.Exists cannot ever reliably determine if a file exists, it can only determine that a file “did” exist at some point in the past and may exist at some point in the future. A more representative name would be File.DidExist, or File.DidAndMayStillExist.

So when designing your APIs, take care to consider the lifetime of the data when naming them.

[1] Once you consider permissions you find that even File.DidExist in not a representative name. It probably should be called File.DidExistAndHadSomeMeasureOfAccess. Yes, that’s a terrible name :(

Is it Serializable?

Jared Parsons — Tue, 31 Mar 2009 15:00:00 GMT

I’ve recently run across several APIs that have a dependency on only dealing with objects that are serializable (in the binary sense). Unfortunately determining if an object is serializable is a non-trivial task and rife with problems. These problems have a direct impact on the types of guarantees these APIs can make.

For all objects which are serializable, it’s only possible to prove that a very small subset of them actually are in code. Easier but less reliable tests are very easy to write. So APIs must make a trade off. Only accept instances of types which are provable serializable and miss out on a while class of objects. Or do a much less reliable check and open themselves up to failure further down in the algorithm.

Take System.Exception for example. It is possible to associate arbitrary data with an exception through the Data property. Associated just any object with Exception is problematic though because Exceptions should be serializable. In order for an Exception instance to store these objects and remain serializable, the objects must also be serializable. Since serializability is not provable, the authors of Exception had to make a trade off between an overly restrictive test, or a loose test. They chose the latter. As a result it’s impossible to determine before hand if a given Exception instance is actually serializable.

Why is this the case though that serialization is tough to determine? Lets start with what it takes to make a type serializable. There are two separate components

Declaring that the type is Serializable by either having the SerializableAttribute on the class definition or by implementing ISerializable
Making the type conform to the rules of serialization.

These are completely separate actions. It’s possible to have types which do any combination of the above but not both. Take for instance the following type declarations

[Serializable]
class DeclaredOnly {
    private ConformsOnly m_conforms;
}

class ConformsOnly {
    private string m_name;
}

Both of these types are legal C# code and both represent one of the two extremes listed above. Yet neither of these types are actually serializable. ConformsOnly is not because it has not actually declared itself to be serializable. DeclaredOnly is not because one of it’s members is not serializable.

Lets look at proving serialization by ensuring types follow both of the rules. Proving the first part of serialization is pretty straight forward. Simply check to see if a type implements ISerializable or is decorated with the Serialization attribute. The latter is directly supported in the type system via Type.IsSerializable. This property is also the source of the most common mistake I see with respect to determining if an object is serializable. Take the following code snippet for an example.

public static voidExample1(object o) {
    if(o.GetType().IsSerializable) {
        // Do something different
   }
}

On the surface, this looks like reasonable code. But as we just pointed out, the property IsSerializable just determines the presence or absence of the Serializable attribute but nothing about the second part. A more descriptive attribute name would be IsSerializableAttributeDeclared. Yet many pieces of code attempt to equate this property with the ability to be serialized (A fun experiment here is to search for it’s use in Reflector)

Proving the second part involves two cases, types implementing ISerializable and types decorated with the Serializable attribute. Lets start with the attribute. Proving these is involved but a straight forward process. The type must …

Be decorated with the Serializable Attribute
One of the following items must be true for every field at all points in the hierarchy
1. It must be decorated with the NonSerializedAttribute
2. The type of the field must be sealed and must conform to all of these rules

Instances of types which meet these guidelines will always be serializable. Not meeting these rules though does not exclude a type from serialization. There are several sets of types decorated with Serializable which are serializable and do not meet these rules.

Take for instance types that violate rule 2.2. By having a field whose type is not sealed, it is possible to construct a runtime instance which contains a value whose type is not serializable. The following type fits into this category.

[Serializable]
class OnlyKnownPerInstance {
    private object m_field1;
}

Whether or not an instance of this type is serializable depends on the value of m_field1. So the only way to prove it is serializable is to look at the runtime information. This makes any definitive analysis on the type impossible. The actual object must be inspected.

The other case to examine are types implementing ISerializable. Serialization is a custom task for instances of these types and is done in imperative code. Proving these types are serializable involves actual algorithm inspection and is beyond the scope of this blog post. But suffice to say, proving these are serializable is an order of magnitude more difficult.

Getting back to the crux of this article. What is the best way to determine if an object is serializable or not? Bottom line, there is no good way. The only 100% definitive way is to serialize the object and see if it succeeds or not. This is problematic because it is not future proof. It only tells you that the object was serializable. This is a very important distinction. It’s possible for the object to be mutated in a different state later on which will prevent it from being properly serializable.

If serialization of a parameter is very important to the semantics of an API this is the only way to ensure the semantics are not violated is to serialize the object immediately and store the binary data. Otherwise you can only make a loose guarantee that an attempt to serialize in the future will succeed.

Building a WeakReference Hashtable

Jared Parsons — Tue, 03 Mar 2009 16:00:00 GMT

Recently I ran into a situation on a personal project where I needed a hashtable like structure for a set of WeakReference values. When poking around for an existing implementation I saw found several versions which were very thin, type safe wrapper around a Dictionary<TKey,WeakReference> (usually the class even implements IDictionary<TKey,TValue> directly). While this produces a type safe API it fails to take into account the different nature of a WeakReference. Because a WeakReference is constantly being collected without explicit user action it alters the types of operations that be performed on them. Failing to take this into account produced APIs which lead users to write incorrect code.

Finding no suitable implementation I set off to build my own. It took several iterations and I thought the result and process would be fun to share the design experience as a blog post.

Let start with the basics. At a high level the API should appear to the user as a type safe Dictionary<TKey,TValue>. Under the hood all values will be stored in an instance of WeakReference in order to enable collection. But this is an implementation detail and should not be visible to the user. The user should only see type safe keys and values.

A standard Hashtable works on the concept of a key/value pair. A value is associated with a particular key in the table and at any time, the value can be retrieved from the hashtable with the specified key. A key can be determined to be valid simply by ascertaining it’s presence in the underlying table. The value is irrelevant, it’s mere presence makes it valid.

A weak hashtable will work on the same concept but have a much different implementation. Keys are only valid if they point to an actual value. Since the value in the hashtable is a WeakReference the mere presence of the key does not determine it’s validity. Only the presence of the key and the value contained within the weak reference determines the validity of a key.

This seems like an obvious assumption but it has a dramatic impact on the type of API a weak hashtable can have. Lets take a simple property such as Count for an example of why this is important. Count on a hashtable is used to determine the number of valid key/value pairs in the table. On a normal hashtable, this count is simply incremented and decremented with the corresponding Add and Remove API’s. With a weak hashtable, any given run of the garbage collector can affect the count of key/value pairs by collecting a value. This means a simple counter cannot be used to keep track of the valid key/value pairs.

In order to get the actual Count every singe value must be accessed an verified that it is still alive. What’s even worse is that once a value is determined to exist, it must be stored for the duration of the Count method. Otherwise a GC could occur in the middle of the loop and collect Values that were marked as still alive.

This is what Count would need to look like …

public class WeakHashtable<TKey,TValue> {
    private Dictionary<TKey, WeakReference> _map;
    public int Count {
        get {
            var list = _map.Values
                .Select(x => x.Target)
                .Where(x => x != null)
                .ToList();
            return list.Count;
        }
    }
}

Count transformed from a simple O(1) return of an internal counter to a O(N) method which allocates memory. Worse yet, the return value is practically useless. As soon as the value is returned it cannot be considered to be valid. A GC could kick in and invalidate half the table. Count would in fact be giving the user information about the object in the past.

In some ways, this problem is similar to issues encountered with multi-threaded applications. In between every line of your code there is another operation, in this case the GC, which can alter the state of your structure.

The only API’s that can ask questions about a value and still have a reasonable use by the user must return the value with the call. Returning the value will, at least temporarily, provide a GC root and prevent the object from being collected. It gives the user a chance to use the value before it’s taken out from under them.

A good API comparison here are operations such as Contains and TryGetValue. Contains holds no value to the user because as soon as the call returns the GC can collect the value. TryGetValue on the other hand returns the value in question thus locking it in memory and preventing a collection.

When designing the API for a weak hashtable I tried to keep it simple and stick to these ideas. I started with the IDictionary<TKey,TValue> interface and removed the methods which hold no value for the end user due to GC limitations. In the end I was left with only the following.

void Add(TKey key, TValue value)
bool Remove(TKey key)
void Clear()
bool TryGetValue(TKey key, out TValue value)
List<TValue> Values { get; }

I also added the following methods

List<Tuple<TKey,TValue>> Pairs { get; }
Put(TKey key, TValue value)
Option<TValue> TryGetValue(TKey key);

The Values property returns a List<TValue> implementation instead of IEnumerable<TValue> In order to guarantee the values remain in existence they must be rooted in some structure. The easy choice is a List<TValue>. Since a List<TValue> must be created anyways, why return a less accessible interface such as IEnumerable<TValue>?

At first I did consider a design where Values returned IEnumerable. It is fairly simple to implement with a C# iterator.

public IEnumerable<TValue> Values {
    get {
        foreach (var weakRef in _map.Values) {
            var obj = weakRef.Target;
            if (obj != null) {
                yield return (TValue)obj;
            }
        }
    }
}

The problem though is that anything more than a simple .ForEach() over the IEnumerable may behave unexpectedly. Consecutive calls to GetEnumerator can produce different enumerations with no explicit user alteration of the table. I’ve seen several APIs which (rightly or wrongly) make this assumption. Given the user is not explicitly modifying the collection, it is not a necessarily bad assumption to make. However it would not work for a collection of this type.

I intentionally left off Keys here. Keys are only valid when they have a live value in the table. Unless the Value is returned with Key this cannot be guaranteed. The Pairs property serves this role.

This post went a bit longer than I originally intended. I also wanted to discuss how compaction of the table should work in a weak hashtable. I’ll save that for next time.

Here is the implementation of the dictionary without any compaction support.

public sealed class WeakDictionary<TKey, TValue> {
    private Dictionary<TKey, WeakReference> m_map;

    public List<Tuple<TKey, TValue>> Pairs {
        get {
            return m_map
                    .Select(p => Tuple.Create(p.Key, p.Value.Target))
                    .Where(t => t.Second != null)
                    .Select(t => Tuple.Create(t.First, (TValue)t.Second))
                    .ToList();
        }
    }

    public List<TValue> Values {
        get { return Pairs.Select(x => x.Second).ToList(); }
    }

    public WeakDictionary()
        : this(EqualityComparer<TKey>.Default) {
    }

    public WeakDictionary(IEqualityComparer<TKey> comparer) {
        m_map = new Dictionary<TKey, WeakReference>(comparer);
    }

    public void Add(TKey key, TValue value) {
        m_map.Add(key, new WeakReference(value));
    }

    public void Put(TKey key, TValue value) {
        m_map[key] = new WeakReference(value);
    }

    public bool Remove(TKey key) {
        return m_map.Remove(key);
    }

    public Option<TValue> TryGetValue(TKey key) {
        WeakReference weakRef;
        if (!m_map.TryGetValue(key, out weakRef)) {
            return Option.Empty;
        }

        var target = weakRef.Target;
        if (target == null) {
            return Option.Empty;
        }

        return (TValue)target;
    }

    public bool TryGetValue(TKey key, out TValue value) {
        var option = TryGetValue(key);
        value = option.ValueOrDefault;
        return option.HasValue;
    }
}

A more usable API for a mutable thread safe collection

Jared Parsons — Mon, 16 Feb 2009 16:00:00 GMT

In my last post we discussed the problems with designing a safer API for mutable thread safe collections that employ only an internal locking system. The result was an API that was more difficult to mess up, yet pretty much unusable. Lets take a look at this problem and see if we can come up with a usable API that still helps to eliminate mistakes.

One of the main issues I have with mutable thread safe collections is the use of decision procedures such as Count and Contains. Procedures such these only return information that pertains to the collection as it existed at a previous point in time. It can provide no relevant information to the collection in it’s current state and only encourages the user to write bad code. For example.

if (col.Count > 0) {
    // Collection can be modified before this next line executes leading to 
    // an error condition
    var first = col[0]; 
}

Therefore they have no place on a mutable thread safe collection. Yet, once you take away these procedures, you’re left with a collection that is virtually useless. It can only have a minimal API by which to access data. Here is the last example we were left with

public sealed class ThreadSafeList<T> {
    public void Add(T value) { ... }
    public bool TryRemove(T value) { ... }
    public bool TryGet(int index, out T value) { ... }
}

This is hardly a usable API. What’s worse, as wekempf point out, is that I inadvertently exposed a decision procedure in this API. It’s possible to infer state about a lower or equal index by a successful return result from TryGet(). For example, a user may say that “if I can access element 2, then surely element 1 must exist”. The result would still be evident in code (ignoring the return value of a TryGet method should be a red flag). But a better choice for this method would have been a TryGetFirst().

At the end of the day, users are going to want some level of determinism out of their collections. It’s possible to program against API’s like the above, but most people won’t do it. In order to be more used, the collection must be able to reliably implement procedures such as Count and Contains and allow the user to use the return to reason about the state of the collection.

One way to do this is to simply exposed the internal lock to the consumer of the collection. Consumers can take the lock and then query to their hearts content. Lets do a quick modification of the original sample to allow for this.

public sealed class ThreadSafeList<T> {
    private List<T> m_list = new List<T>();
    private object m_lock = new object();

    public object SyncLock { get { return m_lock; } }

    public void Add(T value) {
        lock (m_lock) {
            m_list.Add(value);
        }
    }
    public void Remove(T value) {
        lock (m_lock) {
            m_list.Remove(value);
        }
    }
    public bool Contains(T value) {
        lock (m_lock) {
            return m_list.Contains(value);
        }
    }
    public int Count { get { lock (m_lock) { return m_list.Count; } } }
    public T this[int index] {
        get { lock (m_lock) { return m_list[index]; } }
        set { lock (m_lock) { m_list[index] = value; } }
    }
}

Now we can go back to the original sample code and write a version which can use the decision procedures safely.

lock (col.SyncLock) {
    if (col.Count > 0) {
        var first = col[0];
        ...
    }
}

This code will function correctly. But the API leaves a lot to be desired. In particular …

It provides no guidance to the user as to which procedures must be accessed with the SyncLock object locked. They can just as easily write the original bad sample code.
All procedures used within the lock reacquire the lock recursively which is definitely not advisable. We could provide properties which do not acquire the lock such as CountNoLock that work around this problem. While ok in small doses, it's just a matter of time before you see this snippet in the middle of a huge mostly undocumented function
```
// Lock should be held at this point
int count = col.CountNoLock;
```
This code makes my eyes bleed
The API provides 0 information to the user on exactly what the rules are for this lock. It would be left as an artifact in documentation (which you simply cannot count on users reading).
There is really nothing telling the user that they ever have to unlock the collection. Surely, any user entering into the world of threading should know this but if they do a Monitor.Enter call without a corresponding Monitor.Exit, they will receive no indication this is a bad idea.
Overall this collection requires a lot of new knowledge about the collection to use

This design though is exactly how a “synchronized” collection in 1.0 version of the BCL worked. This code is essentially what you would get by passing an ArrayList instance to ArrayList.Synchronized (and most other BCL 1.0 collections). It was problematic enough that all of the new collections in 2.0 did not implement this feature. Here’s the BCL team’s explanation on this http://blogs.msdn.com/bclteam/archive/2005/03/15/396399.aspx

Overall this design poses several problems because it exposes internal implementation details directly to the consumer. An improved design should seek to hide the lock from direct access. What we really want is a way to not even provide API’s like Count and Contains unless the object is already in a locked state. This prevents them from being used at all in an incorrect scenario.

Lets run with this idea to design a more usable thread safe queue. First we’ll divide the interface for a queue into two parts.

All procedures that have 0 reliance on the internal state of the collection. Namely Enqueue, and Clear. No state is required to use these methods
All procedures that rely on the internal state of the collection to function correctly.

The ThreadSafeQueue class will contain all of the methods in category #1. It will also provide a method which returns an instance of an interface which has all of the methods in category #2.

public interface ILockedQueue<T> : IDisposable{
    int Count { get; }
    bool Contains(T value);
    T Dequeue();
}

The implementation of this interface object will acquire the internal lock of the original ThreadSafeQueue during construction and hold it for the duration if it’s lifetime. This effectively freezes the queue allowing for decision procedures to be used reliably. Implementing IDisposable and releasing the lock in the Dispose method provides a measure of lifetime management.

The rest of the code sample is below.

public sealed class ThreadSafeQueue<T> {

    #region LockedQueue
    private sealed class LockedQueue : ILockedQueue<T> {
        private ThreadSafeQueue<T> m_outer;
        internal LockedQueue(ThreadSafeQueue<T> outer) {
            m_outer = outer;
            Monitor.Enter(m_outer.m_lock);
        }

        #region ILockedQueue<T> Members
        public int Count { 
            get { return m_outer.m_queue.Count; }
        }
        public bool Contains(T value) {
            return m_outer.m_queue.Contains(value);
        }
        public T Dequeue() {
            return m_outer.m_queue.Dequeue();
        }
        #endregion
        #region IDisposable Members
        public void Dispose() {
            Dispose(true);
            GC.SuppressFinalize(this);
        }
        private void Dispose(bool disposing) {
            Debug.Assert(disposing, "ILockedQueue implementations must be explicitly disposed"); 
            if (disposing) {
                Monitor.Exit(m_outer.m_lock);
            }
        }
        ~LockedQueue() {
            Dispose(false);
        }
        #endregion
    }
    #endregion

    private Queue<T> m_queue = new Queue<T>();
    private object m_lock = new object();

    public ThreadSafeQueue() { }
    public void Enqueue(T value) {
        lock (m_lock) {
            m_queue.Enqueue(value);
        }
    }

    public void Clear() {
        lock (m_lock) {
            m_queue.Clear();
        }
    }

    public ILockedQueue<T> Lock() {
        return new LockedQueue(this);
    }
}

This design now cleanly separates out the two modes by which the collection can be asked. It completely hides the explicit synchronization aspects from the users and replaces it with design patterns (such as IDisposable) that they are likely already familiar with. Now our original bad sample can be rewritten as follows.

static void Example1(ThreadSafeQueue<int> queue) {
    using (var locked = queue.Lock()) {
        if (locked.Count > 0) {
            var first = locked.Dequeue();
        }
    }
}

No explicit synchronization code is needed by the user. This design makes it much harder for the user to make incorrect assumptions or misuses of the collection. The “decision procedures” are simply not available unless the collection is in a locked state.

As with most thread safe designs, there are ways in which this code can be used incorrectly

Using an instance of ILockedQueue<T> after it’s been disposed. This though is already considered taboo though and we can rely on existing user knowledge to help alleviate this problem. Additionally, static analysis tools, such as FxCop, will flag this as an error.

With a bit more rigor this can also be prevented. Simply add a disposed flag and check it on entry into every method.
It’s possible for the user to maintain values, such as Count, between calls to Lock and use it to make an incorrect assumption about the state of the list.
If the user fails to dispose the ILockedQueue<T> instance it will be forever locked. Luckily FxCop will also flag this as an error since it’s an IDisposable. It’s not a foolproof mechanism though.
There is nothing that explicitly says to the user “please only use ILockedQueue<T> for a very short time”. IDisposable conveys this message to a point but it’s certainly not perfect.
The actual ILockedQueue<T> implementation is not thread safe. Ideally users won’t pass instances of IDisposable between threads but it is something to think about.

The good news is that two of these flaws (1 and 3) are issues with existing types and tools are already designed to weed them out. FxCop will catch common cases for both of them.

Also, many of these cases are considered bad code in the absence of a thread safe collection. This allows users to rely on existing knowledge instead of forcing them to learn new design patterns for mutable thread safe collections.

Overall I feel like this design is a real win over the other versions. It provides an API which helps to limit the mistakes a user can make with a mutable thread safe collection without requiring a huge deal of new patterns in order to use.

Why are thread safe collections so hard?

Jared Parsons — Wed, 11 Feb 2009 16:00:00 GMT

Writing a collection which is mutable, thread safe and usable is an extremely difficult process. At least that’s what you’ve likely been told all through your schooling. But then you get out on the web and see a multitude of thread safe lists, maps and queues. If it’s so hard, why are there so many examples?

The problem is there are several levels of thread safe collections. I find that when most people say thread safe collection what they really mean “a collection that will not be corrupted when modified and accessed from multiple threads”. Lets call this “data thread safe” for brevity. This type of collection is rather easy to build. Virtually any collection that is not thread safe can be made “data thread safe” by synchronizing access via a simple locking mechanism.

For Example, lets build a data thread safe List<T>.

public sealed class ThreadSafeList<T> : IEnumerable<T> {
    private List<T> m_list = new List<T>();
    private object m_lock = new object();

    public void Add(T value) {
        lock (m_lock) {
            m_list.Add(value);
        }
    }
    public void Remove(T value) {
        lock (m_lock) {
            m_list.Remove(value);
        }
    }
    public bool Contains(T value) {
        lock (m_lock) {
            return m_list.Contains(value);
        }
    }
    public int Count { get { lock (m_lock) { return m_list.Count; } } }
    public T this[int index] {
        get { lock (m_lock) { return m_list[index]; } }
        set { lock (m_lock) { m_list[index] = value; } }
    }
    // IEnumerable<T> left out
}

And there you have it. The lock statement prevents concurrent access from multiple threads. So the actual m_list instance is only ever accessed by a single thread at a time which is all it’s designed to do. This means instances of ThreadSafeList<T> can be used from any thread without fear of corrupting the underlying data.

But if building a data thread safe list is so easy, why doesn’t Microsoft add these standard collections in the framework?

Answer: ThreadSafeList<T> is a virtually unusable class because the design leads you down the path to bad code.

The flaws in this design are not apparent until you examine how lists are commonly used. For example, take the following code which attempts to grab the first element out of the list if there is one.

static int GetFirstOrDefault(ThreadSafeList<int> list) {
    if (list.Count > 0) {
        return list[0];
    }
    return 0;
}

This code is a classic race condition. Consider the case where there is only one element in the list. If another thread removes that element in between the if statement and the return statement, the return statement will throw an exception because it’s trying to access an invalid index in the list. Even though ThreadSafeList<T> is data thread safe, there is nothing guaranteeing the validity of a return value of one call across the next call to the same object.

I refer to procedures like Count as decision procedures. They server only to allow you to make a decision about the underlying object. Decision procedures on a concurrent object are virtually useless. As soon as the decision is returned, you must assume the object has changed and hence you cannot use the result to take any action.

Decision procedures are one of the reasons why Immutable Collections are so attractive. They are both data thread safe and allow you to reason about there APIs. Immutable Collections don’t change ever. Hence it’s perfectly ok to have decision procedures on them because the result won’t get invalidated.

The fundamental issue with ThreadSafeList<T> is it is designed to act like a List<T>. Yet List<T> is not designed for concurrent access. When building a mutable concurrent collection, in addition to considering the validity of the data, you must consider how design the API to deal with the constantly changing nature of the collection.

When designing a concurrent collection you should follow different guidelines than for a normal collection class. For example.

Don’t add an decision procedures. They lead users down the path to bad code.
Methods which query the object can always fail and the API should reflect this.

Based on that, lets look at a refined design for ThreadSafeList<T>

public sealed class ThreadSafeList<T> {
    private List<T> m_list = new List<T>();
    private object m_lock = new object();

    public void Add(T value) {
        lock (m_lock) {
            m_list.Add(value);
        }
    }
    public bool TryRemove(T value) {
        lock (m_lock) {
            return m_list.Remove(value);
        }
    }
    public bool TryGet(int index, out T value) {
        lock ( m_lock ) {
            if( index < m_list.Count ) {
                value = m_list[index];
                return true;
            }
            value = default(T);
            return false;
        }
    }
}

Summary of the changes

Both the Contains and Count procedures were removed because they were decision procedures
Remove was converted to TryRemove to indicate it’s potential to fail
The TryGet property was added and is reflective of the fragile nature of the method. Sure it’s possible for users to simply ignore the return value and plow on with the invalid value. However the API is not lulling the user into a false sense of security
The collection no longer implements IEnumerable<T>. IEnumerable<T> is only valid when a collection is not changing under the hood. There is no way to easily make this guarantee with a collection built this way and hence it was removed.
The indexers were removed as well. I’m a bit wishy washy in this particular point as there is nothing in the API which gives a user a false sense of security. But at the same time mutable concurrent collections are dangerous and should be treated with a heightened sense of respect so the indexers were removed.

This version of ThreadSafeList is more resilient, but not immune to, accidental user failure. The design tends to lead users on the path to better code.

But is it really usable? Would you use it in your application?

NotImplementedException vs. NotSupportedException

Jared Parsons — Fri, 12 Dec 2008 16:00:00 GMT

In responding to a recent blog post, one of the readers, Jeremy Gray, noted that I was using a NotImplementedException where I should have been using a NotSupportedException. At first I did not agree. There was a method on an interface which my underlying object could not implement therefore I felt the choice of NotImplementedException was an appropriate.

However I was also not very familiar with NotSupportedException and decided to investigate a bit more. After all, part of the fun of blogging is being wrong in a very public fashion and this was certainly a golden opportunity. The post was commenting on API design, what better way to be wrong than with a different API design issue?

After doing a bit of research I agree with Jeremy and draw the following distinction between the two exception types

NotSupportedException: Throw this exception when a type does not implement a method for which there is a corresponding property indicating whether or not the method in question is supported.

For Example:
- IColletion<T>.Add -> IsReadOnly
- Stream.Seek -> CanSeek
- Stream.Write -> CanWrite
NotImplementedException: Throw this exception when a type does not implement a method for any other reason.

For Example: ICollection.Count, ICloneable.Clone, etc ... [1]

The method in question on my previous blog post was ICollection<T>.Add(). I was dealing with an immutable collection for which Add is not possible. Since there is a property, IsReadOnly, which serves as an indicator that Add() is not allowed, NotSupportedException is the better choice.

[1] Not implementing these methods is likely a bad idea.

Immutable Collections and Compatibility with Existing Frameworks

Jared Parsons — Wed, 10 Dec 2008 16:00:00 GMT

When developing my immutable collections library, I spent a lot of time on usability. After all, if a library is not useful then what’s the point?

A big portion of usability is being able to work with existing frameworks and technologies. For .Net and collections that means items like Data binding, LINQ etc … Without integrating into popular technologies the usefulness of a particular library is severely impacted and hence usability decreases.

Most of the existing collection based infrastructures use the .Net collection interfaces as their form of abstraction. The most straight forward way to ensure compatibility is to implement these interfaces on the collections in question. In particular ICollection<T>, IList<T> and IEnumerable<T> are the main abstractions. Lets investigate which ones an Immutable collection should be implementing in order to effectively integrate into existing collection based infrastructures.

IEnumerable<T>

This is the easiest decision. IEnumerable<T> represents a read only, one element at time view on a sequence of objects. Immutable collections can easily and reliably implement a IEnumerable<T>. This is a no brainer. Implement.

ICollection<T>

This interfaces represents a general collection class. Unfortunately this interface is meant to represent a mutable collection class and implements such methods as Add, Clear and Remove. These methods cannot be implemented on an Immutable collection given the current design. All three of these methods are void returning methods because the collection is meant to be changed in place. Immutable collections can support these operations but it involves returning a new instance of the collection.

public sealed class ImmutableCollection<T> : ICollection<T> {
    public ImmutableCollection<T> Add(T item) {
        // Actually add 
        // ...
    }

    #region ICollection<T> Members

    void ICollection<T>.Add(T item) {
        var created = this.Add(item);
        // What to do with created???
    }

    ...
}

But wait! The interface does support a property named IsReadOnly. The intention of this property is to allow an interface to programmatically declare they do not support modifications. A read only collection can just implement this interface, throw a NotSupportedException for all of the mutable methods and return true for IsReadOnly and presto we have a suitable interface for an immutable collection.

Or do we?

The design for ICollection<T> with respect to read only or immutable collections is not optimal. It attempts to combine to separate behaviors into a single interface: mutable and readonly view of a collection. Dual purpose interfaces run into problems because it’s impossible to separate out the behaviors at compile time. This is especially problematic when the behaviors are conflicting. There is no way a read only collection can prevent itself from being passed to a function that expects a mutable collection at compile time. Nor can a consumer who intends to mutate a collection prevent a read-only collection from being passed.

static void DisplayForEdit<T>(ICollection<T> col) {
    // ...
    m_clearButton.Click += (x, y) => col.Clear(); 
}

static void Example1() {
    ImmutableCollection<int> col = ImmutableCollection.Create(new int[] { 1, 2, 3, 4 });
    DisplayForEdit(col);    // Will fail as soon as Clear is clicked
}

But isn’t it the responsibility of the user of ICollection<T> to verify that IsReadOnly is false before mutating a instance? Given the current design of ICollection<T> it is indeed both the responsibility of the consumer to verify this and the implementer to ensure they are not called incorrectly. The problem with putting responsibility on the consumer though is they have to 1) know about read only uses of ICollection<T> and 2) actually care about it.

A quick search of the BCL with reflector can give us evidence of how much consumers actually check for the read only scenario. For the search I used mscorlib, System, System.Xml, System.Data, System.Drawing and System.Core and System.Windows.Forms. And the number of classes which actually take into account ICollection<T>.IsReadOnly is … 1. System.Collections.ObjectModel.Collection<T>. That’s it.

So even if an immutable collection implements this interface in a read-only fashion there’s little chance anyone will be checking for it.

IList<T>

IList<T> inherits from ICollection<T> and hence suffers from all of the same problems

Decision Time

In order to facilitate usability with existing frameworks immutable collections are forced to implement interfaces for which they have no possible way of implementing properly. If collections implement these interfaces they will be trading usability for compile time validation. Even worse is the conversion is implicit which prevents even basic searches for places this conversion occurs. This is a heavy price to pay for compatibility.

After debating this for awhile I decided that loss of compile time validation was a too heavy of a price to pay for the default scenario. But trading away usability was also unacceptable. As a compromise I opted for adding a compatibility layer to the collections. Instead of implementing the ICollection<T> and IList<T> collections directly I created a set of proxy objects that implement the interfaces on behalf of the immutable collections.

In order to centralize this effort I created a factory class, CollectionUtility, which contains appropriate overloads for all of my immutable collection classes [1].

public static class CollectionUtility {
    public static IEnumerable<T> CreateEmptyEnumerable<T>();
    public static IEnumerable<T> CreateEnumerable<T>(T value);
    public static ICollection<T> CreateICollection<T>(IReadOnlyCollection<T> col);
    public static IDictionary<TKey, TValue> CreateIDictionary<TKey, TValue>(IReadOnlyMap<TKey, TValue> map);
    public static IList<T> CreateIList<T>(IReadOnlyList<T> list);
    public static ICollection CreateObjectICollection<T>(IReadOnlyCollection<T> col);
    public static IDictionary CreateObjectIDictionary<TKey, TValue>(IReadOnlyMap<TKey, TValue> map);
    public static IList CreateObjectIList<T>(IReadOnlyList<T> list);
    public static IEnumerable<int> GetRangeCount(int start, int count);
}

The proxy objects live as private inner classes inside CollectionUtility. They implement the collection interfaces in the most read-only way possible. When confronted with mutating calls, the proxies throw NotSupportedException.

So at the end of the day I have compile time validation for immutable collections. If a developer wants to use them in a less than safe scenario it requires an explicit conversion.

static void Example2() { 
  var col = ImmutableCollection.Create(new int[] { 1, 2, 3, 4 }); 
  // Still fails, but explicit conversion required 
  DisplayForEdit(CollectionUtility.CreateICollection(col)); 
  }

I feel like this as an appropriate tradeoff. In the worst case scenario, a developer can search for all accesses of the CollectionUtility class and find places where a proxy is being created.

Next time, lets take a look at a different way of approaching an interface hierarchy for a set of collections. One that will allow us to avoid this problem altogether going forward.

[1] It actually contains overloads for a set of truly read only collection interfaces that I wrote for my library but we’ll get to that another time.

Edit: Updated the exception to be NotSupportedException

Custom Exceptions: When should you create them?

Jared Parsons — Mon, 20 Oct 2008 15:00:27 GMT

I think the best answer is: rarely. It's really hard to go straight to a justification here though. I find that answering a different question will eventually shed led on when to create a new exception.

"What are the benefits of creating a new/custom exception?"

The answers I come up with or have heard before are ...

Provides a type safe mechanism for a developer to detect an error condition.
Without a custom exception a developer would be forced to compare an existing value on an existing exception class in order to determine if a particular error occurred. To ensure this was unique across applications and environments a unique identifier would need to be inserted as well (likely a GUID). The resulting code would be quite ugly and maintainability would be a question mark.
Add situation specific data to an exception
Ideally this data would help another developer track down the source of the error.

But an entirely new exception is not needed to achieve this goal. The base Exception class contains a property named Data which is an open dictionary. Any code which raises an exception is free to add custom data into the exception. This data can then be accessed by the handling code. Unique values still need to be dealt with. But in my experience, accessing a GUID based custom property is a bit more accepted than catching an exception based on some GUID property.

This is especially true now with extension methods. The lack of type safety in the dictionary and potentially constant string sharing for property names could be hidden inside an extension method
No existing exception adequately described my problem
I'd argue against this because of InvalidOperationException. Invalid operation should cover most exceptional cases

So of these reasons only #1 is a stand alone benefit of a new exception. Now lets re-state this advantage in the context of the original question.

Creating a new exception allows a developer to catch them

Simple right? But what benefit does this give to a developer? From my experience there are only two reasons to catch an exception.

It's a particular for which the underlying exceptional problem can be corrected. Perhaps the user is prompted to fix the condition by performing some outside action (like re-inserting a disk).
Logging errors for post-mortem debugging. Note: You could also use the Data dictionary and extension methods above to introduce a new method ShouldLog(). This would allow you to avoid creating a new exception type.

Now I think we can answer the original question of this blog post.

You should only create a new exception if you expect developers to take corrective action for the problem or to log for post mortem debugging.

Otherwise, what benefit does creating this exception give you?

Immutability and ReadOnlyCollection

Jared Parsons — Tue, 22 Apr 2008 15:42:00 GMT

I am a huge fan of read only/immutable collections and data. Hopefully the increased exposure through the blogosphere alerted users to the advantages of this type of programming for the appropriate scenarios. I wanted to discuss ReadOnlyCollection<T> in case devs looking around in the BCL discover it and assume it's immutable. There are two details of this class which cause gotchas and design issues for consumers who assume it is immutable.

It implements IList<T>

IList<T> is a interface describing mutable collection types which support indexing. ReadOnlyCollection is designed to be read only and cannot fulfill this contract. Therfore every mutable function will throw an exception. IMHO this is not the best design because it is implementing a contract it won't every fullfill. This has the effect of turning what should be a compile time error into a runtime exception (passing a non-mutable collection to an API expecting a mutable collection).

Unfortunately there is not a good interface to implement. The indexable interfaces are all representative of mutable collection types. It would be nice to add an immutable/read only interface which can be safely implemented.

    interface IReadOnlyList<T> : IEnumerable<T>
    {
        T this[int index] { get; }
        int Count { get; }
        int IndexOf(T value);
        bool Contains(T item);
        void CopyTo(T[] array, int arrayIndex);
    }

Ideally this would be called IImmutableList<T> but I'm having trouble getting over the double I, double M pattern to start the name. Perhaps IPersistentList.

It's not deeply ReadOnly

ReadOnlyCollection<T> is a read only facade on top of mutable collection. Read only data should be just that, read only. This means calling methods directly on the class produce the same result every single time. However because it uses a mutable backing store this is not true and can cause gotchas along the road.

Take the following sample which uses a ReadOnlyCollection to wrap a List.

            var list = new List<int>();
            list.AddRange(Enumerable.Range(1, 10));

            var roList = new ReadOnlyCollection<int>(list);
            Console.WriteLine(roList.Count);    // Outputs: 10
            list.Add(42);
            Console.WriteLine(roList.Count);    // Outputs: 11

There are ways to avoid this problem with ReadOnlyCollectionn. The simplest is to make sure you pass a copy of your list into the constructor.

            var roList2 = new ReadOnlyCollection<int>(new List<int>(list));

Design Guidelines: Provide type inference friendly Create function for generic objects

Jared Parsons — Fri, 11 Apr 2008 15:24:50 GMT

Really this guideline is a bit longer but putting it all in a blog title seemed a bit too much. The full guideline should read: "If a generic class constructor arguments contain types of all generic parameters, provide a static method named Create on a static class of the same class name as the generic class which takes the same arguments and calls the constructor." Quite a mouth full.

Lets look at a specific example with Tuples. Tuples are generic with respect to the values they are representing. Without any type inference help we would have to write the following code to create a simple tuple.

            var tuple = new Tuple<int, string>(5, "astring");

Not too bad because we are using simple types. But what happens when we are using really long type names?

            var tuple2 = new Tuple<string,Dictionary<string, List<int>>>(val1, val2);

As we can see, the code is getting quite a bit uglier. This pattern is in fact not maintainable once we start using un-namable types such as anonymous types or generics of anonymous types.

The problem here is we are not leveraging the compilers type inference capabilities. The compiler can easily infer the types of a tuple argument and hence create a tuple. We just need to provide a mechanism to do so. The best way is to define a static method on a static class with the same name as the generic. Lets call this method Create.

    public static class Tuple {
        public static Tuple<TA, TB> Create<TA, TB>(TA valueA, TB valueB) { 
            return new Tuple<TA, TB>(valueA, valueB); 
        }
    }

The method Tuple.Create still has two generic parameters. However since we are providing a set of values which contain types for every generic parameter, the compiler can infer the generic arguments. Now we can create a Tuple without specifying any generic arguments. Because no types are specified this will work with any value in the code including un-namable types.

            var tuple = Tuple.Create(6, "astring");
            var tuple2 = Tuple.Create(6, new { name = "aname", value = 42 });

Reference values in C++

Jared Parsons — Thu, 03 Apr 2008 17:24:54 GMT

Reference values are a powerful feature of C++ but I find they have one significant detractor. A developer can not look at an API call and determine if a parameter is being passed by reference or value (VB has the same problem).

IMHO this is one item that C# got 100% correct. In C# developers must say a value is out/ref or a compile error results. Forcing both the API declaration and usage to specify the reference semantics makes code much more understandable. When you look at an API call there is absolutely no question about the byref/byval/out semantics of a parameter.

Internally I've met people who are hesitant to use reference parameters in C++ because of the ambiguity. Not making it declarative in both places meant unexpected behavior could occur in a number of scenarios. I agree with this statement.

But hey we're talking about C++ here. Any C++ problem can be fixed with some macros and a template right? I thought about this over the weekend and came up with a quick sample. Note, I haven't extensively tested this sample yet so there may be bugs. However it gets the base cases right.

The goal of this API is to allow API authors to force developers to be explicit about their ByRef semantics. It will prevent developers from silently passing a value by ref and hence getting unexpected behavior. Failure to do so will result in a compile time error. Also there is a minor bit of indirection overhead for debug mode but in retail this will compile out to normal code.

#ifdef DEBUG

template <typename T>
class ByRefType
{
public:
    explicit ByRefType(T& arg) : m_ref(arg)
    {
    }

    operator T&() const 
    {
        return m_ref;
    }

    ByRefType& operator=(const T& value)
    {
        m_ref = value;
        return *this;
    }

private:
    ByRefType();

    mutable T& m_ref;
};

template <typename T>
ByRefType<T> MakeByRefType(T& expr)
{
    return ByRefType<T>(expr);
}

#define ByRef(expr) MakeByRefType(expr)
#define ByRefParam(type) ByRefType<type> 

#else

#define ByRef(expr) expr
#define ByRefParam(type) type&

#endif

All well and good. Now we can attribute byref paramaters with ByRefParam() and force callers to tag it as a ByRef argument.

void SimpleByRef(ByRefParam(int) i, int newValue)
{
    i = newValue;
}

void Test()
{
    int i1;
    SimpleByRef(ByRef(i1), 5);
    SimpleByRef(i1, 6);     // Compiler Error!!!
}

As said before, this is an initial implementation and I expect updates as I use this in code and find bugs. Please post back with any you find.

API Problems: CComObject::CreateInstance

Jared Parsons — Sat, 29 Mar 2008 02:38:00 GMT

CComObject::CreateInstance is a light weight method for creating instances of COM objects in your code. Unfortunately the design of the API makes it easy to introduce subtle errors into your code. The two problems are it encourages manually ref counting and the object initially has a ref count of 0. This means you must remember to AddRef before calling any other function. Neither of these ideas in themselves are bad but it leads to tedious, repetitive code that is too often done incorrectly.

Below is a typical example I see in code.

void AMethod()
{
    CComObject<Student> *pStudent;
    if ( SUCCEEDED(CComObject<Student>::CreateInstance(&pStudent)) )
    {
        pStudent->AddRef();
        VerifyStudent(pStudent);
        pStudent->Release();
    }
}

As a result of the manual ref counting, this code is not exception safe. If VerifyStudent or any API it calls throws, an instance of Student will be leaked.

The second problem I often see in code is the placement of the VerifyStudent function. Occasionally I see methods like VerifyStudent called before the AddRef. If you see this in your code immediately file a bug. The problem is the ref count is 0 before you call AddRef. It COM it should always be legal to AddRef/Release a COM object passed into your function. In this case while legal it will destroy the instance of Student. What's even worse is this bug can show up years after you code.

Real world example. I created a class to wrap a couple of operations. One of it's members was Student and as such I wrapped it in a CComPtr<> for ease of use. Fired up the program and everything crashed. Turns out an instance of Student was passed to a function that eventually created an instance of my object before AddRef was called (essentially move VerifyStudent up one line). As soon as my new object died CComPtr<> called Release, moved the RefCount to 0 and destroyed the object.

Writing the correct code is repetitive and begs for a wrapper function. Enter CreateWithRef

template <class T>
static 
HRESULT CreateWithRef(T** ppObject)
{
    CComObject<T> *pObject;
    HRESULT hr = CComObject<T>::CreateInstance(&pObject);
    if ( SUCCEEDED(hr) )
    {
        pObject->AddRef();
        *ppObject = pObject;
    }

    return hr; 
}

void AMethod2()
{
    CComPtr<Student> pStudent;
    if ( SUCCEEDED(CreateWithRef(&pStudent)) )
    {
        VerifyStudent(pStudent);
    }
}

As you can see, using this function takes less typing that a normal CreateInstance due to using type inference. It's also exception safer since the resource is managed.

This API still has one flaw. It allows people to pass in a raw pointer and hence violate exception safety. It could be improved by forcing a caller to pass in a class which supports RAII. In this case a good choice is CComPtrBase<>. I tend to prefer this design because it forces the caller to use safer code.

template <class T>
static 
HRESULT CreateWithRef2(CComPtrBase<T>& spPointer)
{
    CComObject<T> *pObject;
    HRESULT hr = CComObject<T>::CreateInstance(&pObject);
    if ( SUCCEEDED(hr) )
    {
        pObject->AddRef();
        spPointer.Attach(pObject);
    }

    return hr; 
}

void AMethod3()
{
    CComPtr<Student> pStudent;
    if ( SUCCEEDED(CreateWithRef2(pStudent)) )
    {
        VerifyStudent(pStudent);
    }
}