Life Cycle of a Plug-in Instance

This page provides specific information about the life cycle of a plug-in instance. This information should be considered when implementing a plug-in to ensure that the plug-in is recognized as valid and compatible for the use with MERLIC. It contains information about the internal processes and describes the steps that are performed when an instance of a plug-in is used, for example, which functions are called for certain situations.

Start-up

When MERLIC queries the list of available plug-ins, for example, when opening the plug-in list in the MERLIC RTE Setup, all available plug-ins are probed if they are valid and compatible by running the MVInfo function and reading the _MVPluginInfo_t struct of the plug-ins.

A communication plug-in is only recognized if the following preconditions are fulfilled:

• The file name of its corresponding dynamic library is located in one of the specified plug-in directories.
• The file name of its corresponding dynamic library starts with the prefix pMV.

Initialization

If the plug-in was implemented against the plug-in API of the current major version, the respective MVInit_V* function is called. Currently, this would be MVInit_V2 for the API version 2.x.

The passed MVClass_V2_t struct is read and the function pointers for the following functions of the plug-in are initialized:

• MVOpen
• MVClose
• MVStart
• MVStop
• MVExpose (optional)
• MVValidate (optional)

Instantiation

A plug-in is instantiated when a new instance of a plug-in is added in the MERLIC Runtime Environment Setup (MERLIC RTE Setup). The instantiation triggers the following internal processes and functions:

• A new host process (merlic_communication_plugin_host.exe) is started for the plug-in instance. This process is a subprocess of the respective MERLIC RTE process.
• The MVOpen function of the plug-in is called once for each instance of that particular plug-in. MVOpen is guaranteed to be called only once in the life cycle of a plug-in instance. It can be used for one-off initialization tasks such as allocating resources or registering user data.
• The call to MVOpen is balanced by a call to MVClose with the same plug-in instance handle which may be used for the corresponding clean-up tasks. Note that the user parameters of the plug-in are still subject to change by the time MVOpen is called.
• If the MVDetails function was implemented for a plug-in, it will also be called when the plug-in is instantiated. MVDetails will be called with an opaque pointer to an object which can be filled with information about the version of the plug-in as well as a short description. The short description will be displayed as a tooltip when selecting a new plug-in instance in the MERLIC RTE Setup.

For more information on how to add a plugin to the MERLIC RTE Setup, see Adding a Plug-in Instance in the MERLIC Manual.

Configuration

In case a configuration for the plug-in has been defined and a new instance of this plug-in is added to the MERLIC RTE Setup, it will be opened and its configuration will be read and validated.

• First, the respective configuration file is read. The plug-in configuration is written to a JSON file in the configuration directory. By default, the configuration files are located in "%AppData%\MVTec\Communicator\conf" on Windows systems and "~/.config/MVTec/Communicator/conf" on Linux systems.
• Then, the MVExpose function is called if the plug-in provides an implementation for the function. The plug-in parameter description is generated, and the plug-in configuration is updated or created with the initial values from the parameter description.
• Next, the generated plug-in configuration is validated by calling MVValidate, in case the plug-in provides this function.
• The user may modify the plug-in configuration in the "Communication" tab of the MERLIC RTE Setup and both MVExpose and MVValidate may be called multiple times to provide feedback to the user during the configuration.

To get logging information about errors, the MV_Log() function can be used to display error messages in the console.

Activation and Operation

When the configuration is finished, the plug-in instance can be started in the MERLIC RTE Setup.

• The plug-in instance will be activated at which point MVStart is called. From that point onwards, the plug-in instance can use the full set of API functions to receive events from MERLIC or post actions to it. For this, it is recommended to set up an event loop or thread to handle events and/or actions.
• The configuration is immutable from the moment the MVStart function was called and may be read with MV_PluginConfig_GetUserParameter(). This remains to be true until the plug-in instance is deactivated and MVStop is called.
• While MERLIC RTE is still running, plug-in instances can be started and stopped at any time in the MERLIC RTE Setup and the configuration can be modified in between. In this case, the MVStart and MVStop will be called multiple times for the same plug-in instance, corresponding to multiple periods of being activated.

Termination

The plug-in instance is expected to cease operation by the time it returns from MVStop. At this point, the special event of type Shutdown is sent to the plug-in and may be used to break out of the event processing loop, so that the corresponding thread can be joined in MVStop if the plug-in employs such an asynchronous event processing loop. If the plug-in is stopped or MERLIC RTE is ended, MVStop followed by MVClose will be called for all running plug-in instances.

API functions which require communication with MERLIC will return with error code MV_CODE_TIMEOUT after they have been pending for 5 seconds. This affects the following functions:

• MV_FetchDataContainer()
• MV_GetRecipeList()
• MV_GetResultById()
• MV_GetResultListFiltered()
• MV_GetSystemStatus()
• MV_QueueAction()
• MV_QueueAction_WithInfo()

The timeout interval can be customized via the "CommandTimeout" setting in the INI configuration file used by MERLIC. A negative value can also be provided which will cause pending command functions to block indefinitely.