Creating and Closing Objects

All objects that can be created through the Concord API are created through a static ‘Create’ method that the object’s class exposes.

Objects that represent entities in the target process (DkmProcess, DkmThread, DkmRuntimeInstance, etc) will fire a create event as part of their implementation of this ‘Create’ method. Various components can receive this creation event by implementing the appropriate interface. For these objects, the Create method must be called on the event thread, and should be called when the corresponding action happened in the target process.

All objects that are data containers (derive from DkmDataContainer) have a Close method that should be called when the object is no longer valid. Having an explicit ‘Close’ is required because the logical object can exist on multiple computers, and can exist in both managed and native code, so relying on the refcount variable (native code) or the GC (managed code) is not an explicit enough gesture to indicate that the logic object should go away (though these techniques are used to indicate that the memory backing the physical object can be cleaned up). Comments in the Create and/or Close method indicate which component should be responsible a given object.

In some cases, the close method is internal and therefore will not show up in the public API. In which cases, you don’t need to worry about closing the object – this will happen automatically by Microsoft-provided components at the appropriate time. For example, DkmProcess, DkmThread, DkmRuntimeInstance and DkmModuleInstance objects are automatically closed after the object’s unload event has finished being processed.

Dispatcher objects are chained so that most objects have a parent. For example, the object that represents a target process (DkmProcess) is the parent object for threads in that process (DkmThread). When the parent object is closed, children are implicitly closed as well.

Components that wish to be informed when an object is closed can add a data item to the object. The data item class will then be notified through IDkmDisposableDataItem (when implementing the data item in native code) or by overriding DkmDataItem.OnClose (when implementing the data item in managed code).