Jeremy Kuhne's Blog : Managed C++

Using /clr and __declspec(thread)

jkuhne — Wed, 19 Apr 2006 03:40:00 GMT

Sorry I haven't been writing much lately, but a lot has been going on in Expression land. I've switched over to working on build and setup development so you can expect to see the flavor of my posts change somewhat.

Here's a frustrating bit I ran into playing around with C++/CLI: __declspec(thread) isn't supported by the CLR. You may get the application to compile properly, but you'll get the following error when trying to run:

"The application failed to initialize properly (0xc000007b)."

You can still use thread locals, but you're stuck managing the TLS_ apis yourself. I'm including a simple template as one suggestion on how to do this:

template <typename T>

class ThreadLocal

{

private:

DWORD threadLocalIndex;

ThreadLocal(ThreadLocal const&);

T *GetPointer(void)

{

return static_cast<T*>(::TlsGetValue(this->threadLocalIndex));

}

void SetPointer(T *value)

{

::TlsSetValue(this->threadLocalIndex, static_cast<void*>(value));

}

public:

void SetValue(const T &value)

{

T* currentPointer = this->GetPointer();

if (currentPointer == NULL)

{

this->SetPointer(new T(value));

}

else

{

*currentPointer = value;

}

T &GetValue(void)

{

T* currentPointer = this->GetPointer();

if (currentPointer == NULL)

{

this->SetPointer(new T());

}

return *this->GetPointer();

}

void DeleteValue()

{

T* currentPointer = this->GetPointer();

if (currentPointer != NULL)

{

delete currentPointer;

this->SetPointer(NULL);

}

ThreadLocal(const T& value)

{

this->threadLocalIndex = ::TlsAlloc();

this->SetValue(value);

}

ThreadLocal()

{

this->threadLocalIndex = ::TlsAlloc();

}

virtual ~ThreadLocal()

{

this->DeleteValue();

::TlsFree(this->threadLocalIndex);

}

};

The above template can replace a __declspec(thread) variable fairly easily. It will handle allocating and deallocating for you. Simple example:

static __declspec(thread) int threadMeaning=42;

... becomes ..

static ThreadLocal<int> threadMeaning(42);

Using the ThreadLocal is done through SetValue() and GetValue() ie- threadMeaning.SetValue(2001).

The example doesn't have error checking and I haven't done anything terribly fancy. You really should try and use the framework for your thread locals if you can. If you can't, hopefully this will be of use.

Looking at double buffering and the new BufferedGraphics classes

jkuhne — Thu, 08 Sep 2005 09:59:00 GMT

I started spending some time looking at double buffering with Windows Forms a little while back and noticed that in the 2.0 framework there are a couple of new BufferedGraphics classes. I toyed around with them a bit and got them to work, but didn’t really understand what was going on. Looking into things again the past few days I found the available material somewhat lacking, so I did some investigation using Reflector and thought I’d share what I’ve found.

[What is double buffering? It’s drawing on an off-screen bitmap then copying it onto the display to help avoid redraw flickering issues.]

Double buffering will be handled automatically for you if the OptimizedDoubleBuffer style is set to true through SetStyle(). MSDN: Double Buffered Graphics.

[Double buffering will also be done if the DoubleBuffer, UserPaint, and AllPaintingInWmPaint styles are all set to true. Setting the DoubleBuffered property to true is another way to set the OptimizedDoubleBuffer style to true (as well as AllPaintingInWmPaint, but oddly it doesn’t turn off AllPaintingInWmPaint when set to false). As of Beta2 the documentation says that DoubleBuffer style is obsolete, but it is still checked in the code. (I’ve seen mention that double buffering is on by default in the 2.0 framework, but I haven’t seen this to be true in Beta2.)]

If you wish to manually manage double buffering you can do so using the new BufferedGraphics classes. MSDN: How to: Manually Manage Buffered Graphics. There are three key classes that you need to be familiar with:

These classes are what Windows Forms uses to double buffer if the appropriate styles are set. Let’s take a in-depth look at each in turn:

BufferedGraphicsManager

System.Drawing.BufferedGraphicsManager is a pretty simple class that has a static constructor that creates a BufferedGraphicsContext instance that you can obtain through the Current property. It also registers itself with the ProcessExit and DomainUnload events so that it can call Invalidate() on the created BufferedGraphicsContext as the app shuts down.

BufferedGraphicsContext

The BufferedGraphicsContext class handles allocating and releasing the off-screen bitmap that you draw to (which you access through the BufferedGraphics class it gives back to you). You can get an app-wide instance of this class from the BufferedGraphicsManager.Current property. You can also manually create a BufferedGraphicsContext class, but then you are responsible for calling Dispose() when you are finished with it to release created resources. Note that disposing of a context class will delete its BufferedGraphics object if it has one active. (An alternative to calling Dispose is calling Invalidate(), which will call Dispose() when you dispose of the BufferedGraphics object created through the context.)

Calling Allocate() from a BufferedGraphicsContext will create a compatible Graphics object / Display Device Context (DC) that wraps an off-screen bitmap for the specified Graphics object / DC. This new Graphics object is accessed through the Graphics property of the BufferedGraphics object. [Win32 Fyi: The bitmap is created using CreateDIBSection. hSection is set to NULL which allows the system to allocate the memory for the bitmap, which is then deallocated when the class later calls DeleteObject on the bitmap handle.]

Setting the MaximumBuffer property sets the threshold for the bitmap size that is kept in memory after disposing of a BufferedGraphics object. If the size requested is larger than the MaximumBuffer size a new temporary BufferedGraphicsContext is created that will automatically be disposed of when the BufferedGraphics object it returns is disposed. (Note that if the context has already created a BufferedGraphics object that has not been disposed a temporary BufferedGraphicsContext will also be created.)

BufferedGraphics

This is the object that provides you access to the off-screen bitmap that a BufferedGraphicsContext class creates (through Allocate()). You can draw to the Graphics object returned from the Graphics property just like you normally would. When you’re finished drawing, calling Render() on the BufferedGraphics object will call the Win32 BitBlt function using the SRCCOPY ROP method (just copies), positioning the bitmap based off of the Position property of the rectangle passed to the Allocate() method when creating this BufferedGraphics object. By default this copies to the Graphics object / DC specified in the Allocate() method, but you can specify any Graphics object / DC as a destination through the Render() overloads.

The Windows Forms WM_PAINT Handler

I’ve included some (very) pseudo-code here to help give you an idea of what happens when a Windows Forms control handles the WM_PAINT message from Windows. This is important to look at to understand how the different styles will affect the painting process. (Note that there are also calls to BeginPaint/EndPaint and SelectPalette. The HDC is also set up.)

if (OptimizedDoubleBuffer || (DoubleBuffer && UserPaint && AllPaintingInWmPaint))
{
create a BufferedGraphics from the context returned from the BufferedGraphicsManager
set the clipping rectangle
save the Graphics state
call OnPaintBackground (which calls PaintBackground()) if not Opaque style
restore the Graphics state
call OnPaint which then raises the Paint event
render the BufferedGraphics object
}
else
{
if (AllPaintingInWmPaint) call OnPaintBackground delegates if not Opaque style // unless an HDC is passed in WPARAM, not sure when this will happen
call OnPaint which then raises the Paint event
}

Two crucial things:

Don't turn on double buffering if you're handling it yourself. If you have double buffering turned on and you're attempting handle your own double buffering of it you'll end up copying your back buffer into another back buffer that is then copied to the screen.
The other interesting note here is that WM_ERASEBACKBROUND message handler checks for the the AllPaintingInWmPaint style. You still get the background painted for you in the WM_PAINT handler if you don't have the Opaque style set.

Key Takeaways:

Don’t bother with the BufferedGraphics classes if you want simple double buffering. Set the DoubleBuffered property to true.
If you want to handle your own double buffering:

Set the DoubleBuffered property and the DoubleBuffer style to false.
Override OnPaint(). Don’t call the base unless you deliberately want the Paint event raised.

If you are handling the background yourself set the AllPaintingInWmPaint and the Opaque styles.
If you want to minimize allocations of bitmaps:

Ensure you have created your own separate BufferedGraphicsContext classes for each BufferedGraphics you intend to use.
Ensure your MaximumBuffer property is large enough to hold the size of the off-screen bitmap.
Always call Dispose() on a BufferedGraphics class when you're done drawing. (Specifically, before you call Allocate again on it's hosting BufferedGraphicsContext.)

Call Dispose() on any BufferedGraphicsContext class you create yourself when you're finished with them.
Remember the limitations:

You can’t change where the back buffer is copied to after allocating. (The offset in the target DC, that is.)
You can’t specify the raster operation (ROP).

That's about it for now. This ended up being much more detailed than I expected and I've gotten a bit drowsy so hopefully this came through somewhat clear. Any comments/corrections are welcome.

Setting up C++ Interop (with Win32) in VS 2005.

jkuhne — Thu, 08 Sep 2005 03:17:00 GMT

I've already given the steps necessary to make this happen in an earlier post, but as this will come up so much I decided to pull it into a seperate post with more explicit details. The basic things you need again are:

/clr option set for the project. (Common Language Runtime support property under General.)
Include the appropriate Win32 headers. (#include <windows.h> is the main one)
Appropriate target OS #defines. (see Using the Windows Headers for the right values)
If the project was started from one of the CLR templates, you'll need to remove $(NoInherit) from the Additional Dependencies property under Linker:Input.

As mentioned in the earlier post, it's probably a good idea to put the Win32 #includes in a precompiled header for speedier compilation (stdafx.h typically, see Creating Precompiled Header Files for more info). Here is what this looks like (for the latest versions):

//
// Target platform defines:
//

#ifndef WINVER
#define WINVER 0x0501
#endif

#ifndef _WIN32_WINNT
#define _WIN32_WINNT 0x0501
#endif

#ifndef _WIN32_WINDOWS
#define _WIN32_WINDOWS 0x0410
#endif

#ifndef _WIN32_IE
#define _WIN32_IE 0x0500
#endif

// Disable warning for XML comments.
#pragma warning( disable : 4634 )

// Windows Header Files:
#include <windows.h>

#pragma warning( default : 4634 )

Ok, but what about the warning disable? In Beta 2, turning on XML comments would cause parsing of all included headers as well. Not really what you want given there are a number of places XML delimiters inadvertently show up (they aren't actual XML comments, so you are likely to get errors). My last word was that in the final code includes that have the #include <header.h> (as opposed to the #include "header.h") format will not be parsed to make this easier.

So... step-by-step:

Create or load a project.
Set the /clr switch.
Ensure the dependencies property isn't set to $(NoInherit).
Add the relevant Win32 #defines and #includes if needed (see above).
Code. (See my other articles [1], [2] for more details.

That's basically it. Some other useful links from MSDN:

How To: Migrate to /clr
Initialization of Mixed Assemblies (if you have a DLL with a DllMain, look at this)

Generic Collections IV

jkuhne — Mon, 25 Jul 2005 00:46:00 GMT

Back again, and as promised...

Subclassing Generic Collections

The framework provides three basic collections that are intended for derivation. They are located in System.Collections.ObjectModel:



Collection<T> 
KeyedCollection<TKey, TItem> 
ReadOnlyCollection<T>

They are all intended to provide base implementations of the following interfaces:



IList, IList<T>
ICollection, ICollection<T>
IEnumerable, IEnumerable<T>

Collection<T> stores it's data internally as IList<T> (and also takes IList<T> in one of the constructors). The methods that actually modify the internal IList<T> are virtual (and protected):



ClearItems()
InsertItem()
RemoveItem()
SetItem()

This class is intended for when you wish to handle all modifications done to the collection.

KeyedCollection<TKey, TItem> is an abstract class that derives from Collection<T>. It is meant to store values where the key is imbedded within the value. It overrides the virtual methods from Collection<T> and adds an abstract GetKeyForItem().

ReadOnlyCollection<T> supports the same interfaces as Collection<T> and also stores it's data as an IList<T>. There are no virtual methods and all of the iterface method implementations that would normally modify the stored IList<T> are private and throw if called. (Add(), Clear(), Remove(), etc.) The only time the collection is modified is when it is constructed. (i.e., you pass in an existing IList<T>)

Now all of the other collections are not sealed, so you can derive from any of them. They do not, however, have any methods marked as virtual (other than GetObjectData() and OnSerialization()). Why would you want to override them if you cannot change/intercept their behavior? There are two reasons I've come up with so far:

Attaching utility methods.
Readability.

Lets say you had a path with a number of points. You could create a List<Point> to represent said path. This works, but say you want to create a list of your paths? This turns into List<List<Point>>. Hmm. Not nice. In some cases you might even end up with List<List<List<Point>>>. Ugh. Since List<Point> represents a specific object we could subclass List<T> as follows:

public class Path : List<Point>
{
   // Need a constructor (and you'd likely want one that takes IEnumerable<T>):
   public Path() : base() {};
}

Now we can say List<Path>. Much clearer- the sort of code you'd want to read/maintain. In addition we can add useful utility methods to our new Path class such as IsClosed() or IsValid().

That's about it for subclassing for now. Lets take a look at something I hinted at earlier...

System.Array

Ends up that most of the useful methods in List<T> have static equivalents in System.Array. Very useful. Looking at a previous example we could have had:

public void SumUpMeaningDemo()
{
   int[] magicNumbers = { 7, 13, 1000, 42, 9 };
   int total = 0;

   Array.ForEach<int>(newNumbers, delegate(int number) { total += number; });
}

Since these are static methods you need to specifiy the type of the array and which array you're working on. Other than that things work pretty much the same. Happy days that the framework team added this support.

Wait a Minute...

Those that read ahead may have noticed that only List<T> and Array have methods that utilize the system delegate types. It's true. Before you get too depressed about this, in a future post I'll discuss a project that gives you loads of functionality for all of the generic interface types (IList<T>, IEnumerable<T>, ICollection<T>). It is an amazingly useful package called PowerCollections.

Till then...

Generic Collections III

jkuhne — Sun, 24 Jul 2005 05:29:00 GMT

So far I've gone over the basics of generic collections and moved on to looking at List<T> and Predicate<T>. As mentioned yesterday, this post will deal with subclassing and the other System delegate types.

The "Other" System.Delegates

We've already looked at System.Predicate<T>. Now we can turn our attention to the rest of the System deleagte types:



Action<T>
Comparison<T>
Converter<TInput, TOutput>

As a reminder, here's the signature of Predicate<T>:

   public delegate bool Predicate<T>(T obj);

Now here's Action<T>:

   public delegate void Action<T>(T obj);

The only difference from Predicate<T> is that Action<T> returns a void (nothing). One way to think of this is "just do this". The only place it's used (currently) is with List<T>.ForEach(). (Well, one other place, but that comes later.) For each? Yes, it's pretty much the same. Let's say you have a List<int> that you want to sum up:

public void SumUpMeaningDemo()
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });
   int total = 0;

   // The traditional way:
   // foreach (int number in magicNumbers)
   // {
   //    total += number;
   // }

   // A new way:
   magicNumbers.ForEach(delegate(int number){ total += number; });
}

The syntax is a little different, but not much visible difference. So what to use then? What's the not-so-visible difference, if any? Well this surprised me, but the List<T>.ForEach() is twice as fast (in this example, done a million times) as using foreach on the List<T>. Why is that? I'm not terribly great at IL (Intermediate Language) so I can't give you the final word on this, but when you do a foreach in code you actually end up with the equivalent of:

// For reference, this is the code in Enumerator<int>.MoveNext():
public bool MoveNext()
{
   if (this.version != this.list._version)
   {
      // throw;
   }
   if (this.index < this.list._size)
   {
      this.current = this.list._items[this.index];)
      this.index++;
      return true;
   }
   this.index = this.list._size + 1;
   this.current = default(int);
   return false;
}

public void SumUpMeaningDemo()
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });
   int total = 0;

   // What you write:
   // foreach (int number in magicNumbers)
   // {
   //    total += number;
   // }

   // What you get:
   List<int>.Enumerator enumerator = (List<int>.Enumerator)magicNumbers.GetEnumerator();
   try
   {
      while(enumerator.MoveNext())
      {
         int temp = enumerator.Current;
         total += temp;
      }
      finally
      {
         enumerator.Dispose();
      }
   }
}

There are four different calls in the above code that are marked in bold. Here's the equivalent of what you end up with if you use the List<T>.ForEach():

private void CompilerGeneratedAnonymousDelegateClass()
{
   public int total;

   private void CompilerGeneratedDelegateMethod(int number)
   {
      this.total += number;
   }
}

// For reference, this is the code in List<int>.ForEach():
public void ForEach(Action action)
{
   if (action == null)
   {
      // throw;
   }
   for (int i = 0; i < this._size; ++i)
   {
      action(this._items[i];)
   }
}

public void SumUpMeaningDemo()
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });
   int total = 0;

   // What you write:
   // int total = 0;
   // magicNumbers.ForEach(delegate(int number){ total += number; });   //    total += number;

   // What you get (plus the compiler generated class above):
   CompilerGeneratedAnonymousDelegateClass tempClass = new CompilerGeneratedAnonymousDelegateClass();
   tempClass.total = 0;
   magicNumbers.ForEach((Action<int> new Action<int>(tempClass.CompilerGeneratedDelegateMethod));
}

There are two calls (in bold, again) and two classes being constructed (the action delegate and the compiler generated class). The easiest way to differentiate the two methods is to look at the size of the resulting code. If you tear into the IL you'll see that in the loop for your .ForEach you have 53 IL bytes and one call. The standard foreach? 174 IL bytes and two calls. We could go further into it, but that should make it more than clear.

Ugh, sorry about all that. That took way more 'splaining than I expected at first. But I couldn't leave an open-ended question now, could I? ;)

Ok, where was I? Oh yes, the last two types. Here is the signature of Comparison<T>:

   public delegate int Comparison<T>(T x, T y);

Its used (no suprises here) on the Sort<T>() call. The one thing you need to know that isn't obvious is that your method must return the following:

x < y (return less than zero)
x == y (return zero)
x > y (return greater than zero)

And now the last delegate type. Here is the signature of Converter<T, U>:

   public delegate TOutput Converter<TInput, TOutput>(TInput i);

Its used with the ConvertAll<TOutput>() call. In the case of List<T>, this method returns a new List<TOutput>. There is nothing to say that TInput and TOutput can't be the same type. This could be useful for doing something like uppercasing a List<string>. (Why not use ForEach? Just like foreach you're working on a copy.) Here's the line of code to upper case a List<string>:

   myStringList = myStringList.ConvertAll<string>(delegate(string item) { return item.ToUpper(); };

That gets us through the System delegate types. That leads us to subclassing. And me running out of time (sorry, disassembling the foreach example took longer than I expected). So, until next time...

Generic Collections II

jkuhne — Sat, 23 Jul 2005 03:55:00 GMT

In yesterday's post I went over the very basics of generic collections in the 2.0 .Net framework. Today I pick up where I left off with...

Predicate<T>

System.Predicate<T> is a generic delegate that is used to specify a search condition method to pass to the generic collections. It simply takes an object of type <T> and returns a true or false if that object meets a condition that the method expects. The definition is quite simple:

   public delegate bool Predicate<T>(T obj);

Here's another (perhaps easier) way to explain it: When you use the List<T>.Find() method, it needs to know what you wish to find. It accomplishes this by taking a Predicate<T> parameter that it then calls with each element in the collection to essentially ask "Is this it? No? Is this it? ..." Here's how List<T>.Find() actually looks in code:

public T Find(Predicate<T> match)
{
   if (match == null)
   {
      // throw here...
   }

   // Iterate through the collection and return the first object that passes the specified predicate.
   for (int i = 0; i < this._size; ++i)
   {
      if (match(this._items[i]))
      {
         return this._items[i];
      }
   }

   // Nothing found, return the default object for this type.
   return default(T);
}

Pretty simple actually. The one thing you may not have encountered here is default(T). This is a new construct with generics that returns null for reference types, zero for numeric value types, and structs with their fields initialized appropriately to null or zero. The equivalent in C++ is to simply use T(). (note: null in C++ is nullptr)

Let's take a look at a sample of Predicate<T> in action:

// Our method that we'll use as a predicate.
static public bool IsMeaningOfLife(int number)
{
   return number == 42;
}

// Elsewhere …

public void FindMeaningDemo()
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });

   // Create the predicate delegate
   System.Predicate<int> findMeaning = IsMeaningOfLife;

   // Does the meaning of life exist in my magic numbers?
   if (magicNumbers.Exists(findMeaning))
   {
      // This will be hit!
      Console.WriteLine("I've found my purpose!");
   }
}

Exists(), as you may well imagine, simply returns true if the delegate passes on any of the items in the collection. Not too shabby, but this gets even better with...

Anonymous Delegates

Anonymous delegates are a C# (sorry C++) compiler feature that allows you to write code blocks in place of a delegate parameter. The compiler will automatically create the proper type of delegate for you. Simply replace the delegate parameter with:

delegate (optional arguments) { ...code... }

If we redo the previous example using anonymous delegates we get the following:

public void AnonymousFindMeaningDemo()
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });

   // Does the meaning of life exist in my magic numbers?
   if (magicNumbers.Exists(delegate(int number){ return number == 42; }))
   {
      // This will be hit!
      Console.WriteLine("I've found my purpose!");
   }
}

This, my friends, is where the generic collections start to really show their power. And it gets even better. (No, really!) Ends up you can transparently create a delegate out of an existing variable instance:

public void AnonymousFindMeaningDemo2(int meaning)
{
   List<int> magicNumbers = new List<int>(new int[] { 7, 13, 1000, 42, 9 });

   // Does the meaning of life exist in my magic numbers?
   if (magicNumbers.Exists(meaning.Equals))
   {
      // This will be hit (IF the method was sent one of the numbers in the collection)!
      Console.WriteLine("I've found my purpose!");
   }
}

Ok, this is somewhat contrived to fit the existing example, but you can hopefully see where this could be really useful. (Have I mentioned that I love this stuff? This just rocks.)

(Links to more details on anonymous delegates can be found in yesterday's post.)

Now, sadly, C++ doesn't support anonymous delegates, but I'll share a cool thing that I just haven't been able to do in C# (yet). For your predicate argument you can take advantage of the System::Predicate constructor that takes an object and a method pointer. Try this on: (gcnew System::Predicate<int^>(42, &int::Equals))

Hopefully this has been useful so far, but there is more... In my next post I'll discuss subclassing and the other System delegate types. Stay tuned and feel free to send me your feedback...

Generic Collections I

jkuhne — Fri, 22 Jul 2005 07:19:00 GMT

In one of my first posts I briefly mentioned that I would discuss a bit about what I've learned about using the new generic collections. I've been putting it off a bit because I knew it would be a bit lengthy, but I really feel this is important so I'm going to push myself to start making the effort. ;) Here's what I plan to cover (in relation to generic collections):

Advantages of generic collections
Predicates & other System delegate types
Anonymous delegates
Subclassing generic collections
Other resources (including Power Collections)

I'm not going to go over generics. If you want details on generics here are a few links:

I also won't go over anonymous delegates in detail. You can find some useful information here:

Introduction

Generic collections are the generic equivalents (I like to think of them as replacements) for the System.Collections classes. They are found in the System.Collections.Generic space.

Generic collections have a number of advantages over the old collections. Chief among them are:

They are type safe.
Better performance. (no boxing/unboxing!)
Richer functionality through System defined delegate types.

To top it off they are quite compatible with the old collections and methods that use them. Both ArrayList and List<T> support IList, ICollection, IEnumerable, and ICloneable for example. If existing methods use the old interfaces for parameters there is nothing extra you have to do to start using the generic collections. (Hey, look! A great reason to take the interface (IList) as a parameter instead of the collection class (ArrayList).) Converting is easy beyond this as the old collections take ICollection or IDictionary as a constructor parameter.

Here's a quick overview of how the new collections map to old ones (from: Generics in the .NET Framework Class Library (C# Programmers Reference))

Generic Class or Interface	Description	Corresponding Non-Generic Type
Collection<T> ICollection<T>	Provides the base class for a generic collection.	CollectionBase ICollection
Comparer<T> IComparer<T> IComparable<T>	Compares two objects of the same generic type for equivalence and for sorting.	Comparer IComparer IComparable
Dictionary<K, V> IDictionary<K,V>	Represents a collection of key/value pairs that are organized based on the key.	Hashtable IDictionary
Dictionary<K, V>.KeyCollection	Represents the collection of keys in a Dictionary<K, V>.	None.
Dictionary<K, V>.ValueCollection	Represents the collection of values in a Dictionary<K, V>.	None.
IEnumerable<T> IEnumerator<T>	Represents a collection that can be iterated using foreach.	IEnumerable IEnumerator
KeyedCollection<T, U>	Represents a keyed collection.	KeyedCollection
LinkedList<T>	Represents a doubly linked list.	None.
LinkedListNode<T>	Represents a node in a LinkedList<T>.	None.
List<T> IList<T>	Implements the IList<T> interface using an array whose size is dynamically increased as required.	ArrayList IList
Queue<T>	Represents a first-in, first-out collection of objects.	Queue
ReadOnlyCollection<T>	Provides the base class for a generic read-only collection.	ReadOnlyCollectionBase
SortedList<K, V>	Represents a collection of key/value pairs that are sorted by key based on the associated IComparer<T> implementation.	SortedList
Stack<T>	Represents a simple last-in-first-out (LIFO) collection of objects.	Stack

First Look at a Generic Collection Class

The best place to start is to look at the workhorse of the generic collection family, the generic List class, or List<T>. List<T> is meant to replace the functionality of ArrayList. It is a simple ordered collection of objects of type <T>. You can think of it as a wrapped array because that's precisely what it is--internally data is stored as private T[] _items;

As with any array, appending is usually fast (unless the array is being resized) and insertion gets proportionally slower as the number of elements grows. I've already mentioned that it supports IList, ICollection, and IEnumerable. It also supports the generic equivalents IList<T>, ICollection<T>, and IEnumerable<T>.

Lets take a look at some simple usage of List<T>, shall we? (Finally, some code!)

// Creating a List<T> (Also has constructors that take a collection or specify the initial size)
List<int> myNumbers = new List<int>();

// Adding a value
myNumbers.Add(42);

// Adding a range of values
myNumbers.AddRange(new int[]{1,2,3});

// Inserting a value
myNumbers.Insert(myNumbers.Count - 3, 0);

// Iterating
foreach (int number in myNumbers)
{
   // Output is 42, 0, 1, 2, 3
   Console.WriteLine(number.ToString());
}

The code above should be pretty self explanatory. Here is a summary of the functionality that is available to you in List<T>:

Add or insert objects of collections of type T
Removal
- Remove, RemoveAt, RemoveRange, RemoveAll
Sorting
- Sort (Comparison<T>)
- Reverse
Conversion
- ConvertAll (Converter<T,U>)
- CopyTo(T[])
Searching (Predicate<T>)
- Exists
- Find, FindAll, FindLast
- FindIndex, FindLastIndex, IndexOf, LastIndexOf
- TrueForAll
Iterating
- ForEach (Action<T>)

In bold you will see that I've called out the System delegate types. They are the key to unlocking super rich functionality within these classes. This makes a nice transition to my next blog entry where I'll start by taking a look at Predicate<T> and then this discussion will get really interesting. :)

C# or C++?

jkuhne — Mon, 13 Jun 2005 00:52:00 GMT

I just read C++ vs. C# and thought it might be worthwhile to throw up a few thoughts. I've been ranting and raving about how great the new Managed C++ (C++/CLI) is. It's true, it is great, but I still prefer to do most of my work in C#. Why?

C# compiles incredibly fast. I'm compiling around 80,000 lines and it takes about 20 seconds for a rebuild. That's from a cold start. (Chokes a little bit starting up intellisense.)
Partial classes. Code is so much more maintainable when you have many nested classes. (#include just doesn't compare as a solution.)
Anonymous delegates. An incredible feature for unlocking the power of the new generic collection classes. (posts to come on this.)
No headers and no need to declare before you use. Both of these can make some nasty looking code sometimes.
~~XML Documentation~~ (Heh, missed this one when I looked last time, it has been awhile... XML Documentation (C++))
Constructors can call other constructors in the same class.
I'm generally more partial to the way it looks. That's obviously a simple preference.
Generally speaking people seem to be less afraid of C#. More know it (for managed code) and it's easier to enlist a little extra help on a C# project.

What do I like about Managed C++ over C#?

Simple properties. Mmmm. Very nice for rapid prototyping.
The hat ^. I like knowing when I've got a managed heap handle.
C++ Interop is a much better way to work with unmanaged code if you have to.
Mixed assemblies.
Easier to get function pointers. (this is sometimes useful when using the generic collections, not a big thing, however)

If you have to migrate an unmanaged C++ project and want to do it piecemeal, the interop capabilities makes Managed C++ the obvious choice.

(If you have any feedback on what you prefer with either language I'd be happy to hear it.)

(What about VB? I did a lot with VB6 for awhile, but jumping back and forth between C#, C++, and C++/CLI is enough for my head at the moment. So, no comment.)

P/Invoke? No way! (Pt. 2)

jkuhne — Sun, 12 Jun 2005 18:52:00 GMT

[7/20/05: Additional comment added for Marshal::GetFunctionPointerForDelegate()]

There are some instances where Win32 requires a callback function pointer. This frequently comes up in Enumeration APIs, such as EnumWindows. In this post we’ll look at some code that makes this possible in Managed C++ (2005 -- C++/CLI).

One could create an unmanaged callback, but we’ll look at the completely managed route here. (One could also use P/Invoke, but you know how I feel about that, no?) (Don’t forget to read my earlier post on how to set up a C++ project for interop with the Win32 API if you haven’t already.)

You need to do just a few basic things:

Create a method that matches the desired callback signature.
Create a delegate type that matches the above method.
Create an instance of the delegate that points to your callback method.
Pin the delegate.
Convert the delegate into a function pointer.
Use it.

Here’s some sample code:

public ref class Window
{
private:
   // Private flag for keeping track of when we're enumerating windows.
   static bool enumeratingWindows = false;
 
   // Private list of top level windows;
   static List<IntPtr>^ topLevelWindows = gcnew List<IntPtr>();
 
   // Delegate type for the EnumWindowsProc callback.
   // Matches the required signature of the API.  Note the use of ‘BOOL’, not ‘bool’.
   delegate BOOL EnumWindowsDelegate(HWND hwnd, LPARAM lParam);
 
   // Private method used for EnumWindows calls.
   static BOOL EnumWindowsProc(HWND hwnd, LPARAM lParam)
   {
      // Not much to this.  Note the use of ‘TRUE’, not ‘true’.
      Window::topLevelWindows->Add((IntPtr)hwnd);
      return TRUE;
   }
 
public:
   // Returns the top-level window handles.
   // Will return empty List if currently enumerating.
   static property List<IntPtr>^ TopLevelWindowHandles
   {
      List<IntPtr>^ get()
      {
         List<IntPtr>^ foundWindows = gcnew List<IntPtr>();
         if (Window::enumeratingWindows == true)
         {
            return foundWindows;
         }
 
         // Flag that we're currently enumerating windows.
         Window::enumeratingWindows = true;
         Window::topLevelWindows->Clear();
 
         // Setup the managed callback.  Need to create the delegate we need.  (Step 1.)
         //  (This is a delegate to the managed method defined above.)
         EnumWindowsDelegate^ enumWindowsDelegate = gcnew EnumWindowsDelegate(Window::EnumWindowsProc);
 
         // Pin the delegate so the GC won’t move it. (Step 2.)
         pin_ptr<EnumWindowsDelegate^> pinnedDelegate = &enumWindowsDelegate;
         
         // Get the function pointer for the delegate and cast it to the type the API expects. (Step 3.)
         // 7/20: Note that you can also pass *pinnedDelegate here.  It doesn't matter as they represent the
         // same object.  Having a pin_ptr in scope is what keeps the object itself pinned.
         IntPtr delegatePointer = Marshal::GetFunctionPointerForDelegate(enumWindowsDelegate);
         WNDENUMPROC enumWindowsProc = static_cast<WNDENUMPROC>(delegatePointer.ToPointer());
      
         if (!EnumWindows(enumWindowsProc, 0))
         {
            // Failed! Throw appropriate fit here...
         }
      
         // Add what we found and return them.
         foundWindows->AddRange(Window::topLevelWindows);
         Window::enumeratingWindows = false;
         return foundWindows;
      }
   }
};

No unmanaged code used, no P/Invoke, I like it. :) Hopefully you’ll find it useful too.

Some other potentially useful links:

P/Invoke? No way!

jkuhne — Sun, 12 Jun 2005 01:52:00 GMT

[7/20/05: Added an additional comment regarding setting up for Win32]

I've mentioned in my earlier posts just how nice Managed C++ in 2005 (C++/CLI) is when it comes to interoping with unmanaged code. It makes P/Invoke downright painful by comparison. I'd rather toss 10,000 lines of P/Invoke code and restart in C++ than maintain it (and yes, I've done just that). Those legions out there that are using C# (or even VB.Net) shouldn't be afraid of C++ now, the managed syntax is so much better, it's really quite easy to work with. In this post I'm going to go through some examples of just how easy it is, specifically looking at accessing the Win32 API.

An example in C# using P/Invoke:

Lets say we want to write a wrapper base class for a window object in Win32. Lets say we want that class to do something relatively simple, like find a specific window by title and stash the handle (HWND) to it, and grab the window's coordinates. Well, first we'd have to define the necessary structs before we could get to defining the P/Invokes:

[StructLayout(LayoutKind.Sequential)]
public struct RECT
{
   public Int32 left;
   public Int32 top;
   public Int32 right;
   public Int32 bottom;
}

[StructLayout(LayoutKind.Sequential)]
public struct WINDOWINFO
{
   public UInt32 cbSize;
   public RECT rcWindow;
   public RECT rcClient;
   public UInt32 dwStyle;
   public UInt32 dwExStyle;
   public UInt32 dwWindowStatus;
   public UInt32 cxWindowBorders;
   public UInt32 cyWindowBorders;
   public UInt16 atomWindowType;
   public UInt16 wCreatorVersion;
}

Hmm, ok. Now the P/Invokes:

[DllImport("user32.dll", SetLastError = true)]
public static extern Boolean GetWindowInfo(
   IntPtr hwnd;
   out WINDOWINFO pwi);

[DllImport("user32.dll", SetLastError = true, CharSet = CharSet.Auto)]
public static extern IntPtr FindWindow(
   [MarshalAs(UnmanagedType.LPTStr)] string lpClassName;
   [MarshalAs(UnmanagedType.LPTStr)] string lpWindowName);

Ugh. Now we can finally call the appropriate APIs. This is a simple example too. It can quickly balloon into a real pain in the ass. Say, when you have an API that takes a #define value for one or more of it's arguments, such as the SendMessage api. You have to find said values, define an enum or constant, and hope desperately you manually copied the value correctly. (When you start doing hundreds or thousands this isn't too difficult to mess up.)

A few initial humps on the way to the C++ example:

Allright, I may lose some people here, but there are a few things you'll have to do on the C++ side. Native and .NET Interoperability describes in detail what you have to do. Usually you don't have to do much of anything. Strings, however, are a little different. (See How to: Marshal ANSI Strings Using C++ Interop for complete details--there is a link to Unicode & COM strings from there). I'll give you a small class here that you can use to make this easier (note that I haven't split this up into a header/declaration and a definition for clarity, but I highly recommend it):

public ref class Convert
{
private:
   // Handle for marshalling the unmanged string pointer.
   IntPtr unmanagedStringPointer;

   // Constructor for the managed to native conversion.
   Convert(String^ managedString)
   {
      this->unmanagedStringPointer = System::Runtime::InteropServices::Marshal::StringToHGlobalAnsi(managedString);
   }

   // Converts the marshalled pointer to a native string.
   char* ToNativeString()
   {
      return static_cast<char*>(this->unmanagedStringPointer.ToPointer());
   }

public:
   // Converts a managed string to a native string.
   static char* ToNativeString(String^ managedString)
   {
      return (gcnew Convert(managedString))->ToNativeString();
   }

   // Converts a native string to a managed string.
   static String^ ToString(char* nativeString)
   {
      return System::Runtime::InteropServices::Marshal::PtrToStringAnsi(static_cast<IntPtr>(nativeString));
   }

   // Destructor (implicitly implements IDisposable)
   ~Convert()
   {
      if(this.unmanagedStringPointer != IntPtr::Zero)
      {
         System::Runtime::InteropServices::Marshal::FreeHGlobal(this.unmanagedStringPointer);
      }
   }
};

This little helper will make things much easier. You should be able to add Unicode and COM string support by following the previous SDK link. The other thing you'll probably want to do is start adding helpers to convert from common Win32 datatypes to .Net datatypes (say RECT to Rectangle, etc.). You would have to do this in C# as well, of course.

Now for the C++ example:

Again, I won't break this up into a .h and a .cpp file, but this is only for clarity. I'm only using the helper above to convert strings. The rest comes straight from including the Win32 headers. (See the next section for details on how to set that up.)

public ref class Window
{
private:
   // The native HWND.
   HWND windowHwnd;

public:
   // Constructor that takes a window title.
   Window(String^ windowTitle)
   {
      HWND foundWindow = FindWindow(NULL, (LPCSTR)Convert::ToNativeString(windowTitle));
      if (foundWindow == NULL)
      {
         // didn't find the window, barf here...
      }
      else
      {
         this->windowHwnd = foundWindow;
      }   
   }

   // Returns the bounds of the window in screen coordinates.
   property Drawing::Rectangle Bounds
   {
      Drawing::Rectangle get()
      {
         RECT windowRect;
         if (GetWindowRect(this->windowHwnd, &windowRect== FALSE)
         {
            // Failed somehow.  Deal with it... (Another post.)
         }
         else
         {
            return Drawing::Rectangle::FromLTRB(windowRect.left, windowRect.top, windowRect.right, windowRect.bottom);
         }
      }
   }
};

And that's it. One small price in setting up a string helper class and you're up and running. I could create the above in a DLL and use it in all my C# projects. (Hey, I do just that.) You can read the Platform SDK and pretty much use it directly. You don't have to set up P/Invokes or redefine structs or #defines. You get intellisense... It's much more freeform to be able to see another useful API and relatively directly be able to use it. For example, when I was constructing my Window class from a specified HWND I noticed there was an API for verifying that a HWND was valid--ok, add one line of code...

Now, with everything there are always caveats. I have found two circumstances where things don't work seamlessly. If the API has a struct that has a union or bitfields I can't figure out how to access them directly from managed code. (SendInput is an example.) There is a relatively easy workaround and that is to create an unmanaged helper class. That's another post if anyone is interested.

Setting up a Managed C++ project for interop:

Dll, exe, lib, doesn't matter. Here are the key things you need:

/clr option set for the project. (One of the general settings, see my last post.)
Include the appropriate Win32 headers. (#include <windows.h> is the main one)
Appropriate target OS #defines. (see Using the Windows Headers for the right values)
[7/20/05] Note that if you have a C++ forms app you'll need to remove $(NoInherit) from the Additional Dependencies property under Linker:Input.

It's probably a good idea to put the Win32 #includes in a precompiled header for speedier compilation (stdafx.h typically, see Creating Precompiled Header Files for more info).

Acrylic Automation: Crossing the Barrier

jkuhne — Sat, 11 Jun 2005 17:10:00 GMT

Ok, so I really was chomping at the bit to blog. Now that we've gone beta I can get a lot of things off of my chest. Just too awkward to blog much before the product was announced, you know? In this post I'm going to give a bit of info on how to write a managed dll that interops with unmanaged code. (FYI: I can't really give the explicit details on how to access the Acrylic automation interfaces at this point.

This is going to be in Managed C++ in 2005. I've mentioned before that it blows P/Invoking out of the water. The syntax is radically different than the Managed Extensions for C++ that was in VS.Net and is really remarkably easy to read and use for those who know C#, so be strong! ;)

Making a project managed in C++ is simply a matter of setting the /clr switch, which you can get to in the project properties panel under "Configuration Properties: General: Project Defaults: Common Language Runtime support". There are some variations of this switch that are pretty well documented and I won't go into them here. Our configuration type is "Dynamic Library (.dll)", of course. (This is in the same properties area.)

We include the standard <windows.h> header and windows version pound defines as we need access to the Win32 api in a number of places. Here's a simplified code snippet that shows you how things work:

// Plugin.h

// You need to include the relevant headers for the interfaces you're trying to hit.
// This would be defined by the App you're trying to interact with.
#include "AppPlugginInterfaceHeaders.h"

extern "C" // Or "C++" whatever your application uses
{
   //
   // The application plugin entry point.
   // The __declspec(dllexport) specifies that this function should be exported.
   // IApplicationPluginHost is defined in the header provided by the app and included above.
   //
   __declspec(dllexport) bool PluginEntry(IApplicationPluginHost *hostAPIs);
}

// Plugin.cpp

// Or wherever else you have your windows includes if you do.. #include "Stdafx.h" #include "Plugin.h"
__declspec(dllexport) bool PluginEntry(IApplicationPluginHost *hostAPIs) { // Code to check and save the interface passed back from the application. }

That's pretty much the sum of it. From there it's using the host api pointer to grab other interfaces and access functions through those interfaces. So something like hostAPIs->SomeFunction(). We do also have a DllMain (which must be unmanaged according to the SDK) to do some thread initialization that is very app specific in our case. (This would be DLL_THREAD_ATTACH and DLL_THREAD_DETACH message processing.)

In case you're curious, putting completely unmanaged code in your /clr app requires a #pragma managed(push, off) statement before said code and a #pragma managed(pop) afterwords.

VS 2005 Managed C++ Syntax Pt. 1

jkuhne — Fri, 10 Jun 2005 23:53:00 GMT

I had very little experience in C++ when I sat down and tried my hand at using Managed C++ in Whidbey last fall (C++/CLI). Documentation was a bit more sparse back then and I found a few things a little difficult to figure out. I've looked again and I still can't easily find the things I struggled with so I thought I'd list them here in the hopes they may be easier for others to find.

One thing in particular was that I couldn't find anything on was declaring vs. defining methods/functions & properties. Here's a quick example of utilizing the syntax:

// MyClass.h
namespace Sample
{
   public ref class MyClass
   {
   public:
      // Property declaration:
      property System::String^ Value { System::String^ get(); void set(System::String^ value); }

      // Generic method declaration:
      generic <class MyValueType>
         where MyValueType: System::ValueType
         MyValueType GetValue(int index);
   };
} 




// MyClass.cpp
namespace Sample
{
   // Property definitions:
   System::String^ MyClass::Value::get()
   {
      // Getter code here:
   }


   // Property definitions:
   void MyClass::Value::set(System::String^ value)
   {
      // Setter code here:
   }


   // Generic method definition:
   generic <class MyValueType>
      where MyValueType: System::ValueType
         MyValueType MyClass::GetValue(int index)
   {
      // Generic method code here:
   }
}

You can seperate out the getter/setter declaration if you want to have different accessibility levels for each. Another tricky thing for me was overriding virtual properties:

namespace Sample
{
   public ref class MyBaseClass abstract
   {
   public:
      // Property declaration (using a simple property):
      virtual property System::String^ Value;
   };


   public ref class MyDerivedClass : MyBaseClass
   {
   public:
      // Property declaration:
      property System::String^ Value { virtual System::String^ get() override; virtual void set(System::String^ value) override; }
   };
}

That's the current syntax (Beta2).

Automating Acrylic

jkuhne — Thu, 09 Jun 2005 23:30:00 GMT

Here's the first of many posts to come out of what I've learned and experienced attempting to automate Acrylic.

As mentioned before and elsewhere, Microsoft acquired Creature House a few years ago. With this acquisition came the creative design toolset Creature House Expression. We've been working on a new version of the application and one of the challenges I faced in testing the application was finding a way to automate it.

Acrylic is a pretty large unmanaged codebase (the executable is about 10mb) with a wide variety of features. When I started working on it the application did not have automated tests running against it or an api to write tests against. We intended to change this, but the route to take took some effort to discern. Acrylic has a number of custom controls that aren't actual Windows controls (no HWND of their own). It also has standard Windows controls (in dialogs, mostly). To complicate matters, the application swallows modifier keys in mouse and keyboard messages. We really couldn't use any "off the shelf" solutions.

An api was added to the application to load & run automation dlls and expose internal state (through interface classes) and provide a method to send modifier keys with input messages. The question as to whether to write unmanaged C++ code directly against this api or put some sort of wrapper layer in to let most of our test code be written in managed code.

I pushed very hard to write as much of the test automation as possible in managed code. Why? Well, reliable code would be easier to write with the managed safety net. I didn't want to be spending too much time worrying about things like pointer "accidents" in the test code. In addition, there is a great deal of effort and experience being built up with managed tools that take advantage of things like reflection, generics, etc. Another very important thing to me was to be able to easily utilize help from others that could whenever the opportunity arose.

We did ultimately go with pushing towards mostly managed code. Visual Studio 2005 made this very possible. Here's how we did it:

We wrote a Managed C++ dll to interface with the internal test interfaces and expose those interfaces in a managed way. Our test libraries and test cases are in seperate dlls (C# mostly, some VB.Net tools). A managed harness kicks off the application with automation enabled (standard shell execute pretty much). The application loads the managed C++ dll (not knowing it is managed) and tells it to kick off tests. The dll tells the test harness to kick off tests. The test harness then starts executing attributed test methods as specified in a configuration file.

Works like a charm. Writing the interop code in the new managed C++ is incredibly straight forward. It's so straight-forward that once I learned how to really use it I threw out some 14,000 lines of Win32 interop code I had written in C# and rewrote the entire thing in managed C++ (made it much better and it took about a week and a half or so). P/Invoke is just way too painful by comparison once you've seen how well the new C++ interops.

I plan to spend some time here writing about utilizing the new C++ with a particular bent towards interoping with Win32. I'll also talk about other things that I've had to deal with that don't seem too particularly well documented yet (such as the new generic collections and anonymous delegates). If there is anything you're aching to see I'm open to feedback and will direct my efforts towards hitting the things people are interested in.