Skip to content

Game.Debug.DebugWatchDistribution

Assembly: Assembly-CSharp
Namespace: Game.Debug

Type: public class DebugWatchDistribution

Base: System.Object, System.IDisposable

Summary:
DebugWatchDistribution collects integer "distribution" samples from jobs using a NativeQueue. It is designed for use by debug/watch tooling within the game's jobified systems: job producers can add themselves as writers (JobHandle) so that a clear operation and main-thread reads can be synchronized safely. The distribution can be created in a "persistent" and/or "relative" mode (flags are stored for external tooling to interpret). The class manages a persistent NativeQueue and a JobHandle chain of dependencies that must be completed before reading or disposing the queue.

Fields

  • public struct ClearJob : Unity.Jobs.IJob
    ClearJob is a small IJob implementation used to clear the NativeQueue on a worker thread. It contains a single field m_RawData (NativeQueue) and its Execute() calls m_RawData.Clear().

  • private Unity.Collections.NativeQueue<int> m_RawData
    Holds the queue used to accumulate integer samples. Allocated with Allocator.Persistent in Enable(). IsCreated is tested by IsEnabled.

  • private Unity.Jobs.JobHandle m_Deps
    Holds the combined dependency chain of writers and internal clear jobs. Used to schedule or wait for completion before reading/disposing.

  • private bool m_Persistent
    Flag supplied by the constructor to indicate "persistent" semantics. Not enforced inside this class; intended for callers or tooling to read and act on.

  • private bool m_Relative
    Flag supplied by the constructor to indicate "relative" semantics. Not enforced inside this class; intended for callers or tooling to read and act on.

Properties

  • public bool Persistent { get; }
    Returns the m_Persistent flag passed to the constructor. Consumers can use this to decide how to interpret stored samples.

  • public bool Relative { get; }
    Returns the m_Relative flag passed to the constructor. Consumers can use this to decide how to interpret stored samples.

  • public bool IsEnabled { get; }
    True when the internal NativeQueue has been created (m_RawData.IsCreated). Most operations (GetQueue, AddWriter) will throw if IsEnabled is false.

Constructors

  • public DebugWatchDistribution(bool persistent = false, bool relative = false)
    Creates a DebugWatchDistribution and sets the Persistent and Relative flags. The internal queue is not created until Enable() is called.

Methods

  • public NativeQueue<int> GetQueue(bool clear, out JobHandle deps)
    Returns the internal NativeQueue for reading (or for passing to read jobs). Throws an Exception if the distribution is not enabled. If clear == true, schedules a ClearJob that clears the queue on a worker thread and adds that job into the internal dependency chain (m_Deps). The out parameter deps returns the current combined JobHandle that consumers should depend on/complete before reading the queue on the main thread.

Exceptions: - Throws Exception("cannot get data queue from disabled DebugWatchDistribution") if IsEnabled is false.

Notes: - Callers should complete the returned JobHandle (deps) before reading or disposing the queue. - clear = true schedules the clear job using the currently tracked m_Deps as its dependency.

  • public void AddWriter(JobHandle handle)
    Adds a job handle from a producer/writer to the internal dependency chain by combining it into m_Deps. Throws if distribution is disabled.

Exceptions: - Throws Exception("cannot add writer to disabled DebugWatchDistribution") if IsEnabled is false.

Notes: - Writers should call this to register their job handle so that subsequent clear/read operations can correctly synchronize with ongoing writes.

  • public void Enable()
    Allocates the internal NativeQueue with Allocator.Persistent and resets m_Deps to default. No-op if already enabled.

Notes: - Must be called before any AddWriter or GetQueue calls.

  • public void Disable()
    Completes the internal m_Deps JobHandle to ensure jobs finish, then disposes the NativeQueue. No-op if already disabled.

Notes: - After Disable, IsEnabled becomes false and any further use will throw until Enable() is called again.

  • public void Dispose()
    Implements IDisposable by calling Disable(). Ensure Dispose() (or Disable()) is called when the distribution is no longer needed to avoid leaking the persistent allocator.

  • public struct ClearJob.Execute()
    Method of the nested ClearJob that clears the NativeQueue. Runs on a worker thread when scheduled.

Usage Example

// Example usage on main thread / manager
var dist = new DebugWatchDistribution(persistent: true, relative: false);
dist.Enable();

// Somewhere in a job that writes distribution samples:
// - the job can capture the NativeQueue<int> instance (passed by value)
// - after scheduling the writer job, the job's handle should be registered:
dist.AddWriter(writerJobHandle);

// To read the queue on the main thread and optionally clear it:
JobHandle deps;
var queue = dist.GetQueue(clear: true, out deps);
// Ensure all producers/clear job are finished before reading:
deps.Complete();

// Read values from queue (main thread):
while (queue.TryDequeue(out int value))
{
    UnityEngine.Debug.Log($"sample: {value}");
}

// When done with the distribution:
dist.Dispose(); // internally calls Disable() which completes deps and disposes the queue

Additional notes: - The Persistent and Relative flags are stored but not acted on by this class; they exist for external tooling to decide how to display or retain the gathered samples. - Always ensure the JobHandle returned by GetQueue is completed before accessing the queue from the main thread. - Enable() must be called before any AddWriter/GetQueue calls; attempting to use a disabled distribution throws an exception.