Ozgur Ozcitak

Keep Your Async Calls Organized with Step

2010-12-23T00:00:00-08:00

Keep Your Async Calls Organized with Step

23 Dec 2010

You read all about node.js, went through the canonical hello world samples and started using node.js with a real application. Sooner or later your code will turn into an async callback jungle: you will have callbacks nested many levels deep and blocks of code with complex logic checks to determine when certain async calls are completed. When you find yourself facing this problem, know that there is a cure; and it comes as a node.js module called step.

step is written by Tim Caswell of How To Node. You can clone the github repository or install step with npm install step.

step lets you organize your async function calls in serial order, or process them in parallel. Serial processing in step looks like this:

step(
  function () {
    fs.readdir(__dirname, this);
  },
  function (err, dirs) {
    // This function will be chained with readdir above
  }
)

This could also be achieved without using step by nesting async callbacks, but this tends to get unreadable after a couple levels.

Parallel processing in step looks like this:

step(
  function () {
    db.execute('SELECT * FROM posts LIMIT 20', this.parallel());
    db.execute('SELECT COUNT(*) FROM posts', this.parallel());
  },
  function (err, posts, countRows) {
    // This function will be called after both async calls above
    // are completed
  }
)

With parallel processing, step will call the next function after all async calls from the previous step are completed. Parameters of each async callback will be passed to the next step function as separate arguments. There is also another variant of parallel processing called grouping:

step(
  function () {
    db.execute('SELECT authorid FROM posts', this);
  },
  function (err, authorids) {
    var group = this.group();
    authorids.forEach(function (id) {
      db.execute('SELECT name FROM authors WHERE id=?', id, group());
    });
  },
  function (err, authornames) {
    // This function will be called after all async calls above
    // are completed
  }
)

The difference between parallel and group is that when grouping; the results of all async callbacks will be stuffed in one result array, whereas with parallel processing, results of each async callback are kept separate.

There is also one caveat of grouping. The next step function will never be called if the group is empty; that is if there are no async callbacks from the previous step. This is probably by design but there may be times when this is not desirable. In that case, you need to add a check yourself:

step(
  function () {
    db.execute('SELECT authorid FROM posts', this);
  },
  function (err, authorids) {
    // Make sure we reach the next step
    if (authorids.length == 0) return [];

    var group = this.group();
    authorids.forEach(function (id) {
      db.execute('SELECT name FROM authors WHERE id=?', id, group());
    });
  },
  function (err, authornames) {
    // This function will be called after either all async calls above
    // are completed -OR- there were no async calls
  }
)

UPDATE: This issue is now fixed in the latest release of step.

step is a simple function but it helps simplify your code a lot. Use it.

Using GDI Objects the Right Way

2009-12-23T00:00:00-08:00

Using GDI Objects the Right Way

23 Dec 2009

Since I am writing some graphics-heavy user controls lately, I am spending a lot of time googling for GDI related topics. Looking through the samples/demonstrations it appears that there is some confusion about how and when to dispose GDI objects. It is common to see rendering routines where brushes/pens/fonts are created without being disposed, or GDI objects created in the control’s constructor, released (if at all) in the control’s Dispose method. I will try to address these issues in the form of a FAQ.

Why should GDI objects be disposed?

There is a hard limit for the total number of GDI objects available on a Windows system. For the Windows 9x family (Windows 95, 98 and ME) this limit is 1200 objects, for the NT family (Windows XP, Vista and Windows 7) the limit is 10,000. Although the number seems high, this is the total number of objects available across the system (Edit: For the NT family the limit is per process).

Whenever you create a new GDI object, you are pulling a resource out of the shared GDI resource pool, effectively decreasing the resources available to other running applications and the rest of the system. The GDI object you created cannot be used by other applications because GDI handles are private to the process that created the object.

When GDI objects are disposed, their associated handles will be freed and returned to the resource pool, to be reused when needed. This is why all GDI objects implement the IDisposable interface.

Why should I explicitly dispose GDI objects?

After all, the garbage collector will happily clean after us, right? The answer to this question is a lot longer that one would expect. I am going to give you the short version but I encourage you to read more about the CLR garbage collector.

What makes GDI objects special is that they encapsulate unmanaged handles which cannot be simply freed by the garbage collector. A managed System.Drawing.Brush object for example keeps a handle to an unmanaged brush object. When it is disposed, its Dispose method calls the GdipDeleteBrush function to clean up resources used by the unmanaged brush handle. But what happens when you do not explicitly call Dispose? In that case, sometime after the object goes out of scope, its finalizer will kick in and call the Dispose method for you. If you look at the finalizer of System.Drawing.Brush with reflector, you will see this one line:

~Brush()
{
    this.Dispose(false);
}

Why the hassle then? The framework designers made sure that unmanaged resources will be cleaned up no matter how sloppy we are. The reason is, there are two problems with finalizers. First, the exact time an object’s finalizer is executed is undefined. Actually, it is not guaranteed to be executed at all! Second, finalizers are expensive. It will require at least two garbage collections to free a finalizable object. Explicitly calling dispose overcomes both of these problems: unmanaged resources will be cleaned up immediately and the object will be exempt from finalization.

When should I dispose GDI objects?

The short answer is “as soon as possible”. For most GDI objects (pens, brushes and even fonts), the overhead of creating and disposing the object is almost non-existent. I ran a quick benchmark while writing this and here are the results:

Created 10,000 fonts in 61 milliseconds.
Created 10,000 brushes in 17 milliseconds.
Created 10,000 pens in 16 milliseconds.

If your control uses 20 fonts, brushes and pens each, you will need a total of 0.2 milliseconds to create and dispose those objects. It doesn’t really make sense keeping references to such objects; it is best to create, use and dispose them on the spot.

For some graphics objects this may not be the case. Creating an Image for example, may take anywhere from a few milliseconds to many seconds. If you are continuously rendering the same large image, you may be better off holding a reference to it to avoid the overhead. Just remember to dispose your image when you no longer need it.

How should I dispose GDI objects?

C#’s using keyword was made for this purpose. It provides the additional benefit of calling Dispose even when an exception is thrown inside the using block. Its usage is as simple as this:

using (Brush brush = new SolidBrush(Color.Black))
{
    graphics.FillRectangle(brush, new Rectangle(0, 0, 100, 100));
}

It also has an additional form that can be used when creating multiple objects:

using (Font font = new Font("Arial", 10.0f))
using (Brush brush = new SolidBrush(Color.Black))
{
    graphics.DrawString("some text", font, brush, 0, 0);
}

There is another less useful form of the using keyword, limited to objects of the same type:

using (Font headingFont = new Font("Times New Roman", 12.0f),
            bodyFont = new Font("Arial", 10.0f))
{
    // ...
}

And a side note… It is perfectly fine to return from a function inside the using block. Your objects will be disposed just before the return statement is evaluated.

Summing It Up

Whenever you are creating a GDI resource (actually any object implementing IDisposable), enclose it in a using block. You can make an exception if you are sure that object creation is expensive. In that case, keep a reference to the object and explicitly dispose it at the earliest opportunity.

Control.Visible May Not Return What You Expect

2009-11-16T00:00:00-08:00

Control.Visible May Not Return What You Expect

16 Nov 2009

I encountered a curious issue while working on ImageListView. In the layout code of the control I have a check to determine whether to show the vertical scrollbar. If the scrollbar needs to be shown, the layout is recalculated since the display area will be smaller with the scrollbar shown. However, my layout code ended up being called infinitely resulting in a stack overflow eventually. Here is the relevant part of the layout code.

public void UpdateLayout()
{
    // ...
    // ...

    // Maximum number of rows and columns that can be fully displayed
    int cols = displayBounds.Width / itemSize.Width;
    int rows = displayBounds.Height / itemSize.Height;

    // Check if we need the vertical scroll bar
    bool vScrollRequired = (cols * rows < items.Count);
    if (vScrollBar.Visible != vScrollRequired)
    {
        // Show the scrollbar
        vScrollBar.Visible = vScrollRequired;

        // Recalculate the layout
        UpdateLayout();
        return;
    }

    // ...
    // ...
}

The problem was that the Visible property of the scrollbar always returned false, if the layout code was called before the parent control is displayed. This is because – as I learned the hard way -, the getter of the Control.Visible property checks whether its parent control is visible. If not, it will return false regardless of what you set.

The solution was simple though. Keep a separate variable to track scrollbar’s visibility rather than relying on Control.Visible.

Here is what I do not get. If the Visible property actually means “the control is displayed on the screen” then why does it return true when the control is hidden under another control, or the control is moved beyond the client area of its parent?

ToolStripItem circumvents the issue by introducing the Available property. In the remarks section MSDN says:

The Available property is different from the Visible property in that Available indicates whether the ToolStripItem is shown, while Visible indicates whether the ToolStripItem and its parent are shown. Setting either Available or Visible to true or false sets the other property to true or false.

This is what Control.Visible should be doing in the first place. To determine if the control is actually displayed on the screen, there should have been another read-only property (IsDisplayed perhaps?).

It may not be possible to fix Control.Visible since there are probably many applications relying on the current behavior. However, it should be possible to extend ToolStripItem.Available property to the Control class without causing many compatibility issues.