DQMH Singleton Module vs Cloneable Module Overview

The DQMH features two basic types of modules: Singletons and Cloneables.

Singleton

A Singleton DQMH module can have only one instance of its Main.vi running at any given time. Every time the Start Module.vi is called, the same DQMH Main.vi instance is used.

Cloneable

A Cloneable DQMH module can have one or more instances of its Main.vi running in parallel at the same time.

Addressing the Instances

A unique Module ID number (starting with 1) is assigned to each new instance when starting it by calling the Start Module.vi. The Module ID allows addressing each running instance separately. The calling code needs to provide the Module ID as an input to every request and broadcast VI.

DQMH 3.0 added code for cloneable modules to be executed as singletons. If the cloneable is running as a singleton, the same instance will be returned every time Start Module.vi is called, and its Module ID is set to 0).
Module ID Description

1..

Request is addressed to / broadcast is coming from a specific clone.

-1

Request is addressed to all running instances.

0

Cloneable is running as a singleton. All requests and broadcasts are sent to/from the same single instance.

Shared Event References

All instances of a cloneable module share the same single set of event references. This means that all running instances will receive a request event even if it’s addressed to a specific instance.

In order to support processing of request events in dedicated instances, the event structure inside the EHL of each running instance has to determine if a request event was sent specifically to that instance before enqueuing the message to the MHL.

Image

A request event will be enqueued for further processing in the MHL if the Module ID sent with the request…​

  • …​either matches the Module ID stored inside the Module Admin object, meaning the event was addressed to this specific clone instance

  • …​or is set to the value of -1, meaning the event was intended for all running instances of the cloneable module

The Addressed to This Module.vi will evaluate both conditions. Be aware that the boolean output Addressed to this instance? does not mean addressed to this instance only and will be true if either one of the two conditions is met.
Seeing as a request event will be received by all running instances independently of the addressed instance, sending of requests will impact not only the addressed module instance but all instances[1].

Reentrancy

For cloneable modules, the DQMH Main.vi is set to Prealloecated clone reentrant execution to allow for multiple instances in memory.

For any subVIs you use in your cloneable module, consider the effects of the different reentrancy settings: If a subVI is set to Non-reentrant execution, it will force all running instances to wait for this subVI to become available, which might result in unexpected behaviour or even starvation or deadlocks.

Clone Instance Management

A cloneable DQMH module library has a folder called Multiple Instances; this folder contains the Action Engine that manages the different instances of the module.

Image

  1. The cloneable DQMH module comes with a group of VIs to update a Module ID ring that can be used in the Tester or in the Application code to address the different instances of the module.

  2. Since the DQMH Module Main.vi owns the lifetime of the request and broadcast events, code is needed to determine if the first instance can close. Before stopping, the DQMH Module Main.vi checks to see if it was the first instance of the module that was launched (and hence, the owner of the event references). If it was the first instance launched, then the module will exit both EHL and MHL loops and hold in the Close.vi waiting for all the other instances to close. The VI continues to run (with its panel hidden) until it is the last instance running, at which point it destroys the event references and stops.

  3. The Clone Registration AE.vi is the action engine that manages all the DQMH cloneable module instances.

  4. These VIs are the public API for the Clone Registration Action Engine and are used for the following tasks:

    • Initialize the clone registry

    • Add a new clone to the registry

    • Remove a clone from the registry when it stops

    • List all the available clones

    • Check if a module was the first clone to be registered

The Clone Registration functionality resides in a library with a Public API. This allows the developer to implement the registry with a mechanism other than the default action engine if she so desires.

  1. A simple tester is included to verify that the Clone Registration AE.vi works as expected.

  2. DQMH 5.0 modifies how the DQMH modules are launched. DQMH now uses Start Asynchronous call instead of the Run VI Method. This change adds a VI Reference Management which is another action engine that manages the lifetime of the VI reference. Open VI Reference requires root loop access. Keeping the VI reference open eliminates the need for root loop access during subsequent calls to Start module.vi for this cloneable module.

  3. DQMH 5.0 replaces the code that waits for the "Last Clone Instance" notifier. This notifier fires after the last clone stops running. Seeing as all clone instances share the same set of event references, the first DQMH clone to start owns the event references. When it stops, it waits until the last clone stops before destroying the shared references (see point 2 above).