A Dog named dog?

Michael Geary | Mon, 2004-08-09 15:15

In many programming languages, it’s a popular convention—or even a language rule—that class names begin with a capital letter and class instances begin with a lowercase letter. For example, you might have a Dog class and a particular instance of that class named dog. In other words, you have a Dog named dog, and dog is a Dog.

I just accepted that as the normal state of affairs, until I read my daughter her new book Just Dog.

Just Dog begins:

“Dog was a dog and that’s what everyone called him. Dog. Just Dog.”

Now wait a minute. The story doesn’t say dog is a Dog, it says Dog is a dog.

Come to think of it, I’m not a Person named mike, I’m a person named Mike.

So why do we use a naming convention in programming that is the exact opposite of how we name things in the real world?

And even more puzzling, why does it feel right?

Ruby iterators and C callback functions

Michael Geary | Mon, 2004-08-09 00:00

Mike Sax wonders what’s the fuss about iterators. Aren’t they just a fancy use of function pointers? Indeed, Mike has hit the nail on the head. Consider the window iterator that’s been built into Windows since 1.0:

BOOL EnumWindows( WNDENUMPROC lpEnumFunc, LPARAM lParam );

This function iterates through all of the top-level windows (children of the desktop window) and calls lpEnumFunc for each one, passing it the HWND of each window and the lParam that you passed to EnumWindows.

So lParam is how you get to provide some state that the enumeration function can make use of. Suppose you wanted to write a function that counted the number of visible top-level windows. Your C code might look like this:

struct MyEnumWindowState
    int nVisible;

BOOL CALLBACK MyEnumWindowsProc( HWND hwnd, LPARAM lParam )
    MyEnumWindowState* pState = (MyEnumWindowState*)lParam;
    if( IsWindowVisible(hwnd) )

int CountVisibleWindows()
    MyEnumWindowState state;
    state.nVisible = 0;

    EnumWindows( MyEnumWindowsProc, (LPARAM)&state );
    return state.nVisible;

This works, but it is rather tedious. So Windows 2.0 added the GetWindow function, which lets you simply ask for a window’s child or next sibling. That simplifies the overall structure of the code, especially if you use the GetFirstChild and GetNextSibling macros defined in windowsx.h:

int CountVisibleWindows()
    int nVisible = 0;
    HWND hwnd = GetDesktopWindow();

    for( hwnd = GetFirstChild(hwnd);
         hwnd = GetNextSibling(hwnd) )
        if( IsWindowVisible(hwnd) )

    return nVisible;

That’s it, just one function, no callback function or struct definition needed. We don’t need the struct because the code inside the loop can directly reference the nVisible variable defined in the function.

But the simplification came at a price: We had to write the loop ourselves, asking explicitly for the first child of the desktop window and then the next sibling of each child window.

Also, it doesn’t work.

What if another application creates or destroys a top-level window, or just changes a window’s Z-order, while you’re in the loop? You’ll either miss a window, count one twice, or crash with an invalid window handle.

To handle these cases, you need a bit more complexity. If you had a way to temporarily lock all window creation and destruction, you could quickly create a list of all the windows and then release the lock, then enumerate from that list, perhaps also doing a last-minute check when you enumerate each window to skip any that get destroyed during enumeration. Or, you might set a Windows hook to notify you of any windows created, destroyed, or moved in the Z-order, so you could deal with them appropriately.

Whatever you did, it would be enough code that you wouldn’t want to duplicate it each time you wanted to write a window loop. The GetFirstChild/GetNextSibling style of loop doesn’t really facilitate that kind of code isolation. The EnumWindows style enumerator completely separates the code that does the iterating (EnumWindows itself) from the code that receives the iteration (your callback function). But, it makes it harder to share state between the callback function and the code that called EnumWindows.

If you had a way to use a callback function, but have it more easily share state with the calling function, you’d have a winner. In C# and JavaScript, you can do this by using an anonymous callback function nested inside the surrounding code. Because of lexical scoping, the callback function can access variables in the parent function as easily as it can access its own.

Both those language have enough extra syntactic cruft that when you look at a simple example using nested anonymous functions, it’s easy to be unimpressed. The payoff shows up in more complicated, real-life coding situations.

Code blocks in Ruby simplify this technique down to its essence, making it useful even for simple cases. Assuming a good Rubyesque Windows interface library, our function might be something like:

def countVisibleWindows()
    nVisible = 0

    Win.enumWindows do |window|
        nVisible += 1 if window.visible?


In this code, the enumWindows function takes a code block argument and calls that code block for each window, passing it the window as an argument. Because the code block is nested inside the countVisibleWindows function, it can access the nVisible variable directly.

This solves both our problems: The logic for iterating through the windows is separated out into the enumWindows function, and the callback function (code block) can access state variables cleanly and easily.

(In Ruby, a code block is a like a callback function, but it’s not quite a full-fledged function. A code block does not introduce a new scope for variables—it shares the scope of the enclosing function.)

Unfortunately, Ruby does not seem to have a Windows interface library that works like this. Ruby’s standard Win32 module provides a general way to call Windows DLL functions, but it doesn’t have a clean implementation of enumWindows that uses a code block.

However, MoonWolf has written a Ruby port of Perl’s Win32::GuiTest module that includes this kind of enumWindows function. It’s implemented in two parts: a low level function written in C that enumerates HWND values, and a higher level function written in Ruby that constructs Ruby window objects and enumerates them. The window object in Win32::GuiTest is a fairly thin wrapper that encapsulates an HWND and other window information.

The high-level enumWindows looks like this:

def enumWindows
    ret = []

    GuiTest::_enumWindows { |hwnd|
        win = createWindow( hwnd )
        ret << win
        yield win if block_given?


This code calls the low-level _enumWindows function, which passes an HWND to the code block enclosed in curly braces. This code block creates the window object, appends to the ret array, and also yields the window object to a code block that was provided by the caller of enumWindows.

If I were implementing this, I think I would change it a bit. Typically a function like this either yields results to a code block, or it returns a value, but not both. And I would change the confusingly named createWindow function (which has no relation to the CreateWindow function in Windows):

def enumWindows
    if block_given?
        GuiTest::_enumWindows do |hwnd|
            yield newWindow( hwnd )
        result = []
        GuiTest::_enumWindows do |hwnd|
            result << newWindow( hwnd )

Either way, our countVisibleWindows example ends up pretty much as I’d imagined:

def countVisibleWindows()
    nVisible = 0

    Win32::GuiTest.enumWindows do |window|
        nVisible += 1 if window.isWindowVisible


The low-level enumWindows function that enumerates HWND values is implemented in C. The initialization code to add the enumWindows function is simply:

rb_define_module_function( mGuiTest, "_enumWindows", guitest_enumWindows, 0 );

where mGuiTest is a reference to the Win32::GuiTest module.

The guitest_enumWindows function is:

static VALUE guitest_enumWindows( VALUE self )
    EnumWindows( &EnumWindowsProc, 0 );
    return Qnil;

and the EnumWindowsProc callback is:

BOOL CALLBACK EnumWindowsProc( HWND hwnd, LPARAM lParam )
    rb_yield( INT2NUM((DWORD)hwnd) );
    return TRUE;

This shows how easy it is to extend Ruby with C code, adding functions that work just like ones written in Ruby.

So, how do all the calls and callbacks stack up when we run the countVisibleWindows function? Something like this:

            (code block in enumWindows)
                (code block in

In everyday use, of course, you don’t worry about that whole call stack, just the part of it you’re working with.

Use elementsof(sz), not sizeof(sz)

Michael Geary | Fri, 2004-08-06 18:36

I had to fix a bug recently where my shell extension was crashing another application when you used that app’s File Open dialog.

This application has a thumbnail view of the selected file in the File Open dialog, which they generate the same way as Windows Explorer: by loading a shell extension for the selected filetype and calling its IExtractImage interface. It’s a fairly weird protocol: First they call your IPersistFile::Load to give you the filename, then you give them back the same filename when they call IExtractImage::GetLocation. Finally they call IExtractImage::Extract and that’s when you generate the thumbnail.

But, after my GetLocation method returned, the application silently exited. What could be wrong? My code worked fine in Explorer.

GetLocation is a typical function that takes a character string buffer and length along with some other parameters (omitted here):

HRESULT GetLocation(
    LPWSTR pszPathBuffer,
    DWORD cchMax, etc. );

I noticed that this other app was giving me an unusually large file pathname buffer, 520 characters or 1040 bytes to be exact. This number sounded strangely familiar (and not just because of this).

Then I realized what happened. I’ve never seen the source code for this app I was crashing, but I just know it looked like this:

    szPath, sizeof(szPath), etc. );

Oops. The cchMax argument to GetLocation is a length in characters, but sizeof gives you the size in bytes. And we’re talking WCHAR here, so each character is two bytes. MAX_PATH is 260, making szPath 520 bytes long, the number that they passed into my code.

One way to fix the problem is:

    szPath, MAX_PATH, etc. );

That gives correct code, but I never like seeing MAX_PATH repeated like this. sizeof is in the right spirit, actually measuring the array length instead of repeating a constant, but it measures the wrong thing, bytes instead of characters (array elements).

I like to code this with the elementsof macro, defined as:

#define elementsof( array ) 
    ( sizeof(array) / sizeof((array)[0]) )

Then you can just use elementsof instead of sizeof:

    szPath, elementsof(szPath), etc. );

elementsof is handy anytime you need the length of a character string array or any array.

Of course, I didn’t have the luxury of fixing this code at its source (other than reporting the bug to the program’s authors). So I worked around it by checking for the bogus 520 character cchMax and cutting it back to 260 (MAX_PATH) characters.

More C#, Ruby, and Python Iterators, and JavaScript too

Michael Geary | Thu, 2004-08-05 16:55

Making a valiant attempt to post code with my comment system (Sorry, Mike! :-(), Mike Roome points out:

The ruby example isn

Iterators in C#, Python, and Ruby

Michael Geary | Mon, 2004-08-02 17:33

Matt Pietrek marvels at C# 2.0 iterators and dissects them right down to the CLR bytecode. I always learn something from Matt, and this whirlwind tour is no exception.

Matt says, “This was the beginning of my descent into the loopy world of C# 2.0 iterators. It took me awhile to wrap my head around them, and when I tried to explain them to other team members I got looks of total confusion.” I wonder if it would have been less confusing if Matt’s team had first been exposed to yield iterators in a language that makes them easier to use.

After using Python and Ruby, the iterators in C# feel right at home to me. They work the same in all three languages, but in Ruby and Python there’s not as much other code to get in the way of understanding them.

Let’s combine all of Matt’s examples into one, and compare the code in each language. First, in C#:

using System;
using System.Collections.Generic;

class SomeContainer
    public IEnumerable<string> MyIterator()
        Console.WriteLine( "Before First" );
        yield return "First";
        Console.WriteLine( "After First" );

        for ( int i = 0;  i < 3;  i++ )
            yield return i.ToString();

        Console.WriteLine( "Before Last" );
        yield return "Last";
        Console.WriteLine( "After Last" );

class foo
    static void  Main()
        SomeContainer container =
            new SomeContainer();

        foreach( string s in
                container.MyIterator() )
            Console.WriteLine( s );

When you run that, it should print:

Before First
After First
Before Last
After Last

Here’s how you would write the same code in Python:

def MyIterator():
    print "Before First"
    yield "First"
    print "After First"

    for i in xrange(3):
        yield str(i)

    print "Before Last"
    yield "Last"
    print "After Last"

for s in MyIterator():
    print s

And in Ruby, the code looks like this:

def MyIterator()
    p "Before First"
    yield "First"
    p "After First"

    3.times do |i|
        yield i.to_s

    p "Before Last"
    yield "Last"
    p "After Last"

MyIterator do |s|
    p s

The one unfamiliar thing here may be the |name| notation, which is how a code block such as the body of a loop receives its argument. And the p statements are a kind of print statement.

This Ruby version is even more concise and equally readable once you’re comfortable with the |name| notation:

def MyIterator()
    p "Before First"
    yield "First"
    p "After First"

    3.times { |i| yield i.to_s }

    p "Before Last"
    yield "Last"
    p "After Last"

MyIterator { |s| p s }

Either way, the Python and Ruby versions make it easier to see what the iterator function does and how yield interacts with the rest of the code.

You may note that the Python and Ruby versions don’t create and instantiate a SomeContainer class as the C# version does. That’s true, and it would make the code in those languages a bit longer (but still simpler than the C# code). But, if you don’t need to—and you especially don’t need to when you’re experimenting and trying to understand a radical new technique like yield iterators—why bother?

WordPress: Thanks!

Michael Geary | Sun, 2004-08-01 03:33

I needed a blog, and I needed it fast. I wanted something written in Ruby or maybe Python, but I’d heard enough good things about WordPress that I gave it a try.

Wow! This is nice work! I’ll live with it being written in PHP. ;-) It was easy to get running on my virtual Linux server, once I figured out how to add a MySQL user for WordPress. The default stylesheet stinks big-time, but the WordPress Wiki pointed me to the Style Competition, where I found the Rubric style was closest to my taste. I tweaked it a bit and here we are.