Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 36 ยท State Machines and Design Patterns

The Queued Message Handler (QMH)

Build a queued message handler in LabVIEW: an event loop that enqueues typed messages, a message-handling loop with a Case structure, plus how to enqueue sequences and add parallel workers.

The producer/consumer pattern moves data between loops. The queued message handler (QMH) moves commands. It combines producer/consumer with a state machine: the consumer loop is a state machine whose next state arrives as a queue element, and anyone (the user interface, a timer, another state) can enqueue the next command. QMH is the standard starting template for LabVIEW applications with a user interface; the Queued Message Handler project template (File > Create Project) generates one.

LabVIEW cannot run here; the block diagram is described step by step and a Python stand-in runs the same logic.

Two loops, one queue

  1. Event handling loop (producer): contains an Event structure with a case per user action (Start button, Save button, Stop, window close). Each case enqueues a message and returns to waiting. It never does real work, so the UI always responds.
  2. Message handling loop (consumer): dequeues a message and a Case structure runs the matching state. States can enqueue further messages, so one click can trigger a chain.
flowchart LR
    E["Event loop<br/>Event structure"] -- "Enqueue message" --> Q[("Message queue")]
    Q -- "Dequeue" --> M["Message loop<br/>Case structure"]
    M -- "Enqueue follow-up" --> Q

Messages from the UI and from the handler itself share one queue, so everything runs one at a time in order.

The message

A message is a cluster of:

  • Message name: a string (for example Acquire) or typedef enum. Strings are flexible (new messages need no type change) but a typo only shows up at run time, so always include a Default case that reports unknown messages. An enum catches typos at edit time.
  • Data: a Variant carrying an optional payload, converted back with Variant To Data in the case that needs it.

You create the type once as a typedef cluster and use it as the element data type of Obtain Queue.

Many templates use a single string like Acquire:5 with the text after the colon as the argument. It is simple; parse it with Match Pattern or Scan From String.

A runnable stand-in

Python Queued message handler (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice how Acquire enqueued Analyze, which would enqueue Save: one UI click becomes a sequence without special wiring. But Bogus and Exit were already waiting in the queue, so Exit ran before Analyze and Save, and the data were never saved (saved is False). New messages go behind everything already queued. That ordering rule is a classic QMH surprise.

Queue ordering: front or back

Enqueue Element adds to the back, so a follow-up waits behind every message already in the queue. If the follow-up must run immediately (for example an error clean-up), use Enqueue Element At Opposite End (also called Enqueue At Front), which places it first.

Python Back versus front of the queue

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

For sequences that must stay together, enqueue them as one array of messages and let a state expand them to the front, or put the whole sequence into the message data.

Error handling in QMH

Wire the error cluster through the message loop on a shift register. After each case, if an error occurred, flush the queue (so queued commands do not run in a bad state), enqueue Error then Exit (or Shutdown), and let the Error case show a dialog. This stops a stale Save running after a failed Acquire.

Adding parallel workers

When a state takes a long time (a 20 s instrument sweep) the message loop blocks and cannot process Stop. Solutions:

  • Run the long operation in a separate worker loop with its own queue; the message loop sends it a Start message and receives a Done message back.
  • Use a second consumer for slow I/O (logging) with its own queue.
  • Use user events so workers talk to the Event structure without the main queue.

Large applications compose several QMHs, each a small component with Start, Stop and Status messages: this is the basis of many LabVIEW frameworks (Actor Framework, DQMH, CVI-style modules).

Good habits

  • One typedef for the message, one for the shared data cluster.
  • Every queue created by one loop, passed to others; released exactly once at the end.
  • A Default case that reports unknown messages.
  • Give messages verb names (Acquire, Save File) and keep each state short.
  • Never put a Wait longer than a few milliseconds in the message loop.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a QMH, what does the event loop do with a button click?

    The event loop stays responsive by only enqueueing messages.
  2. 2. A state enqueues a follow-up message with Enqueue Element. When does it run?

    Normal enqueue adds to the back. Use enqueue at the opposite end to run first.
  3. 3. After an error you want no queued commands to run. What do you do?

    Flushing discards pending messages that assumed a healthy state.
  4. 4. A 20-second operation prevents the Stop message from being handled. What is a good fix?

    Moving slow work to its own loop keeps the message loop free to receive Stop.

Summary

  • QMH = event loop (producer of messages) + message loop (state machine consumer) + queue.
  • Messages are a name plus variant data; states can enqueue more messages.
  • Order matters: normal enqueue goes to the back, opposite-end enqueue goes to the front.
  • Flush on error, add workers for slow tasks, and always have a Default case.

Next: Event-Driven User Interfaces