Orphan Datarefs

From X-Plane SDK
Jump to: navigation, search

The Problem

A dataref becomes an orphan when the plugin that created it goes away. In the original plugin system this was not a problem: all plugins went away at the same time (during a full plugin reload), and only plugins used datarefs.

This situation has changed in two ways:

  1. X-Plane now acts as a plugin consumer of datarefs, in that the OBJ animation and generic instrument systems read datarefs.
  2. Plugins can unload and reload individually if they are installed in an aircraft package.

The problem is that client plugins do not have any generalized way to know when a dataref may have gone away due to a plugin being unloaded - reading from an unregistered dataref results in a crash.

Checking a dataref before reading fails for two reasons:

  1. Legacy plugins do not do this, so plugin-checking doesn't address a mix of legacy plugins with new airplane-based plugins.
  2. Plugin-checking of the dataref would slow down access times for all dataref reading operations across the entire system.

Orphaning Datarefs

Under the new XPLM released with X-Plane 930, a dataref that is unregistered (by a plugin unload or explicit call to XPLMUnregisterDataRef) does not go away. Instead the dataref becomes an orphan; it is marked as being owned by no plugin.

When a client tries to read/write an orphan dataref, the read/write operating is cut short when the plugin system detects that the dataref is not owned by an enabled plugin. Because the dataref itself (as an object) has not been destroyed, there is no crash when reading the dataref. (The plugin system has always checked the owner of a dataref to avoid reading datarefs from disabled plugins, so the check for orphan datarefs actually does not increase the cost of a dataref read).

When a client tries to register an orphan dataref, the register succeeds - the dataref becomes "owned" by the newly registering plugin, but the original dataref is returned. This means:

  • Plugins that read a dataref can continue to read a dataref after the publishing plugin is unloaded and reloaded. The temporary unload looks just like the plugin being disabled from a reader's perspective.
  • Theoretically a plugin might end up reading from an unexpected plugin, if one plugin unregisters and then an unrelated one re-registers. Since plugins are advised to use their own namespace for dataref names, this case is unlikely in practice.