Life Cycle of a Plug-in Instance

This topic 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 the Communicator and MERLIC. It contains information about the internal processes when starting the Communicator and describes the steps that are performed when an instance of a plug-in is used, e.g., which functions are called for certain situations.

Communicator Start-up

When the Communicator is started, 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 plug-in is only recognized if the file name of its corresponding dynamic library starts with the prefix "pMV".

Initialization

If the plug-in was implemented against the Communicator 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, initializing the function pointers for the following functions of the plug-in:

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

Instantiation

When a plug-in is instantiated, its MVOpen function is called once for each instance of that particular plug-in. Currently, instantiation happens when a new instance of a plug-in is added in the MERLIC Runtime Environment Setup (MERLIC RTE Setup) or by providing the --plugin flag along with the plug-in's name when using the command line. For more information on how to add a plugin to the MERLIC RTE Setup, see the topic "Adding a Plug-in Instance" in the MERLIC Manual.

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 to do 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.

In case the MVDetails function was implemented for a plug-in, it will also be called when the plug-in is instantiated. The Communicator will call MVDetails 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.

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. For this, the configuration file is read first. 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. The plug-in configuration is written to a JSON file in the default configuration directory. It is by default the standard configuration location of your system, e.g., "%AppData%/MVTec/Communicator/conf" on Windows and "~/.config/MVTec/Communicator/conf" on Linux.

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, i.e., 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 the Communicator 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 Communicator is ended, MVStop followed by MVClose will be called for all running plug-in instances.

Communicator 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_QueueAction()
• MV_GetRecipeList()
• MV_QueueAction_WithInfo()
• MV_GetSystemStatus()
• MV_GetResultById()
• MV_GetResultListFiltered()

The timeout interval can be customized by providing the flag '–command_timeout' when starting merlic_communicator, followed by the desired timeout duration in milliseconds. A negative value can also be provided which will cause pending command functions to block indefinitely.