All objects passed between the Media Server and a plugin use reference counting. If you don't increment or decrement a reference counter correctly, two common issues occur:

• Memory leaks: An unused object is not destroyed and continues to occupy memory.

• Application crashes: The application attempts to delete an object that was already destroyed.

To detect these issues, use RefCountableRegistry. This built-in SDK tool tracks reference-countable objects, alerts you if an object is deleted twice, and reports leaked objects when the server stops.

Prerequisites and recommendations

Objects derived from the nx::sdk::RefCountable helper class automatically register with RefCountableRegistry when the registry is enabled.

To reduce manual reference management and prevent errors, use the smart pointer template nx::sdk::Ptr (src/nx/sdk/ptr.h) whenever possible.

You still need manual reference counting in two scenarios:

• Calling addRef() when receiving an object as a function argument that needs to be stored in a class field.

• Calling addRef() when a function returns an object stored in a class field.

For more information, see readme.md in the SDK or the comments in src/nx/sdk/i_ref_countable.h.

Enable and configure RefCountableRegistry

Enable and adjust RefCountableRegistry settings by editing your .ini files. For details on file locations, see the documentation on configuring via .ini files.

1. Enable the registry

To turn on tracking, add the following line to vms_server_plugins.ini and restart the server:

enableRefCountableRegistry=true

Each plugin and server instance runs its own registry. When initialized, the registry logs a startup message. When the server stops, it logs a success message if no leaks are found, or an error if leaked objects remain.

2. Configure logging output

By default, RefCountableRegistry logs issues to stderr using NX_KIT_ASSERT().

To write issues to the main server log using the INFO level instead, add this line to vms_server_plugins.ini:

useServerLogForRefCountableRegistry=true

3. Enable process crashes on assertion failure (Optional)

By default, assertion errors are logged in both Debug and Release builds, but the server process crashes only in Debug builds.

To force the server to crash on an assertion failure during Release builds, add this line to nx_utils.ini:

assertCrash=true

4. Enable verbose logging

To track down the origin of leaked objects, turn on verbose mode. Add this line to vms_server_plugins.ini:

verboseRefCountableRegistry=true

In verbose mode, the registry logs every object creation (with its memory address) and deletion attempt. You can search the log for a leaked object's address to see exactly when it was created.

Test RefCountableRegistry with the Stub Analytics Plugin

Follow these steps to observe how RefCountableRegistry logs normal operations and detects memory leaks using the provided Stub Analytics Plugin.

Set up the initial environment

1. Create an empty vms_server_plugins.ini file in your .ini directory if one doesn't exist, then restart Nx Witness Server to populate default values.

2. Open vms_server_plugins.ini and add or set the following options: enableRefCountableRegistry=true enabledNxPluginsOptional=stub_analytics_plugin

3. Restart the Media Server.

Verify standard operation

1. Open the Desktop Client and view a camera video feed on your layout.

2. Right-click the camera feed and select Camera Settings.

3. Go to the Plugins tab, select Stub Analytics Plugin, and turn the switch to On.

4. Check stderr to verify two RefCountableRegistry instances started (one for the plugin, one for the server).

5. Stop the Media Server.

6. Check stderr to confirm both registry instances stopped without detecting any leaks.

Simulate and trace a memory leak

1. Start the Media Server.

2. Open the Desktop Client, navigate to Camera Settings > Plugins > Stub Analytics Plugin, and select Force a memory leak when processing a video frame.

3. Click OK.

4. Stop the Media Server and check stderr to confirm the registry reported the leaked objects.

5. Open vms_server_plugins.ini and add: verboseRefCountableRegistry=true

6. Restart the Media Server, let it run briefly, then stop the Media Server again.

7. Open stderr, locate the address of a leaked object in the stop report, and search upward in the log for that address to find when the object was created.