Skip to main content

​
XSystemHandleTrack

Registers a callback to track handle lifetime events in the Gaming Runtime.

​
Syntax

​
Parameters

callback    _In_
Type: XSystemHandleCallback A user defined callback that will be called on handle creation and destruction. To disable handle tracking pass in NULL for the callback. context    _In_opt_
Type: void * User define context to be passed to the callback.

​
Return value

Type: HRESULT Returns S_OK if successful; otherwise, returns an error code. For a list of error codes, see Error Codes.

​
Remarks

Game developers need to have the ability to troubleshoot bugs involving incorrect handle usage. Most of the GRTS APIs utilize handles which correspond to the lifetime of internal objects in our platform implementation. Games often encounter problems caused by developers accidentally providing invalid (NULL, previously freed, etc.) handles into these APIs leading to title crashes. Developers may also inadvertently leak handles leading to excessive resource usage. The goal of the handle tracking API is to empower developers to diagnose and fix these issues. The API has two components: active and passive. All handles created by GRTS are continuously tracked for both debug and retail scenarios. Whenever handles are passed into our APIs, the platform performs validation to ensure that these handles correspond to valid internal objects. If an invalid handle is detected, the platform logs the error and invokes XErrorReport to notify the developer of the problem. The platform does not make any additional effort to suppress the invalid handle usage and allow the application to crash as it would have prior to this feature. Finally, any handle leaks at the time of XGameRuntimeUninitialize will also be reported via XErrorReport. At present, the handle tracking system does not enable the tracking of handles which are external to GRTS.

​
Requirements

Header: XSystem.h Library: xgameruntime.lib Supported platforms: Windows, XBOX One family consoles and XBOX Series consoles

​
See also

XSystem members XSystemHandleCallback
Last modified on August 20, 2026

Related topics

XSystemHandleCallbackXSystemPHEAP_TRACK_FREE_ROUTINE callbackPHEAP_TRACK_ALLOC_ROUTINE callbackPHEAP_TRACK_REALLOC_ROUTINE callback