The Art of the State:
Adding an Event Queue

The comment stripper FSM works okay, but it has a dangerous flaw. It's a flaw that is inherent in event-driven systems, and one that also crops up in regular Visual Basic programs. The problem is re-entrant code, and you might have come across it when working with data controls, Form_Resize events, or code that uses DoEvents.

Let's have a look at a simple example of re-entrancy using a data control. The program shown in Figure 8 is about as simple as it gets, with a single data-bound list wired up through a data control to the Visual Basic sample database BIBLIO.MDB. Assume that the list contains a set of records we need to process somehow and that it doesn't matter in which order the records are processed. Clicking in the list causes a Reposition event, and the program puts up a message box that lets us simulate the kind of Jet page-locking error we might encounter in a multi-user application. You can think of the Reposition event handler as the equivalent of the DoFSM function in the comment stripper program. Here's the important bit:

Private Sub datBooks_Reposition()
    If MsgBox (…) = vbYes Then
        datBooks.Recordset.MoveNext
    EndIf
End Sub

The program works like this: inside the Reposition event, instead of directly calling MoveNext when a locked record is encountered, we post an event onto the queue and then exit the event handler. The queue manager (the timer control) then comes along and, finding an event on the queue, kindly calls MoveNext for us. Now, however, the MoveNext is called from the timer's event handler, and there's no recursion. Notice that it doesn't matter how fast we push event requests into the queue; we never get recursion because the events are processed one by one in sequence.

Adding an Event Queue to an FSM

To prevent re-entrant code, we need to add a queue to the FSM model. Strictly speaking, the comment stripper program doesn't need a queue because it doesn't do anything that will cause recursion. Because it's an example program, however, we'll add the queuing now so that we can build on it when we design real-world FSM programs later.

The queue built in the previous example worked adequately, but it needed a form to carry the list box and the timer control. This awkwardness over essentially non-visual code has dogged Visual Basic from the start, and it means, for example, that we can't define a queue inside a class or a startup module without creating a dummy form. We could dump the controls onto an existing form, of course, but that's anathema to modular design, and it means we must contrive to load the form before starting the event queue. Getting rid of the list box isn't too hard, but until Visual Basic 5 there was no getting around that timer control without doing something horrific like this:

Sub Main()
    Dim nEvent As Integer
    frmMain.Show vbModeless    ' Main program is in here.
    Do
        If bGetEventFromQueue(nEvent) Then
            DoFSM State, nEvent
        End If
        DoEvents
    Loop
End Sub

With Visual Basic 5 and 6, however, we can at last devise acceptable code-only solutions to this kind of problem – in this case, to build an event queue. By using the AddressOf operator, we can call the SetTimer API function and pass a Visual Basic routine as the timer's callback procedure. This means we can create a timer from pure code, and just like a Visual Basic Timer control, it will invoke the Visual Basic procedure asynchronously at the requested interval. Creating a timer is simple:

lTimerId = SetTimer(0&, 0&, 500&, AddressOf MyFunc)

The first two parameters are NULL values, which simply signify that the timer isn't associated with any window, and the third is the timer interval, in milliseconds. The last parameter is the interesting one; it passes a pointer to a Visual Basic function that will be invoked by Windows whenever the timer fires. Windows expects this function to have the following interface and to pass the appropriate parameters:

Sub MyFunc(ByVal lHwnd As Long, _
           ByVal nMsg As Long, _
           ByVal lEventId As Long, _
           ByVal lTime As Long)

For now, just ignore the parameters. We also need to make sure we destroy the timer when we're finished with it:

Call KillTimer (0&, lTimerId)

That takes care of the queue manager, so now all we need to do is provide a queue for it to manage. A simple way to do this is to use a Visual Basic collection:

Private m_colEventQueue As Collection

We'll see a more sophisticated use of collections later, but for now we can use one as a simple queue by defining a couple of routines:

Sub AddEventToQueue(ByVal nEvent As Integer)
    m_colEventQueue.Add nEvent
End Sub

Function bGetEventFromQueue(ByRef nEvent As Integer) As Boolean
    If m_colEventQueue.Count = 0 Then
        bGetEventFromQueue = False
    Else
        nEvent = m_colEventQueue.Item(1)
        m_colEventQueue.Remove 1
        bGetEventFromQueue = True
    End If
End Function

And that's it – a code-only asynchronous queue manager that we can build into a class or a normal module. Here's the code for the event queue. This code is actually designed to handle multiple concurrent  FSMs; the class CFSM it refers to is the class we're building here.

Next...