Class ProfilerLauncher

Namespace

Typhon.Engine

Assembly

Typhon.Engine.dll

Host-side helpers that turn a parsed ProfilerLaunchConfig into the side effects the host needs: flipping the telemetry gate before TelemetryConfig is first read, building the exporter list, and printing a diagnostic banner.

public static class ProfilerLauncher

Inheritance

object

ProfilerLauncher

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Designed so that any Typhon host (AntHill, IOProfileRunner, MonitoringDemo, …) can use the same conventions and the same code paths — no copy-pasted parsing or env-var setup logic across host repos.

Methods

BeginCpuSamplerStop()

Begin stopping the CPU-sampling session asynchronously: stop the EventPipe session and parse its .nettrace capture on a background thread. Idempotent and best-effort — safe when no sampler is running or when already begun. StopCpuSampler() later awaits the result.

public static void BeginCpuSamplerStop()

Remarks

Call this just before the host tears down its engine (e.g. before bridge.Dispose()). The capture's transcode + symbol resolution is single-threaded and runs for seconds on a large session; kicking it here lets it overlap the engine-teardown work (dirty-page flush, etc.) instead of serialising on the exit path. The trade-off is that CPU samples no longer cover the engine teardown itself — a negligible slice for a statistical profile. A host that skips this call still works: StopCpuSampler() falls back to a synchronous stop+parse.

CreateExporters(ProfilerLaunchConfig, IResource)

Construct the exporter list per config. Returns an empty list when the config isn't active (no trace file, no live port). The caller attaches each via AttachExporter(IProfilerExporter) and then calls Typhon.Engine.TyphonProfiler.Start(Typhon.Engine.IResource,Typhon.Engine.ProfilerSessionMetadata,Typhon.Engine.ProfilerOptions,System.Action) — at that point each exporter's Initialize runs, which for a Typhon.Engine.Internals.TcpExporter with LiveWaitMs > 0 blocks until the first viewer connects.

public static List<IProfilerExporter> CreateExporters(ProfilerLaunchConfig config, IResource profilerParent)

Parameters

config ProfilerLaunchConfig

profilerParent IResource

Returns

List<IProfilerExporter>

EnableTelemetryGateIfActive(ProfilerLaunchConfig, ProfilerOptions)

If config requests any profiler output: set TYPHON__PROFILER__ENABLED, call EnsureInitialized(), AND eagerly allocate the spillover ring pool. Must run before any engine type JITs methods that read ProfilerActive — i.e., before constructing the bridge / runtime — otherwise the JIT bakes the gate as false and no events are emitted.

public static bool EnableTelemetryGateIfActive(ProfilerLaunchConfig config, ProfilerOptions options = null)

Parameters

config ProfilerLaunchConfig

Parsed profiler launch options.

options ProfilerOptions

Tunables for the spillover pool (and any other engine-side options consumed at this stage). Defaults to ProfilerOptions if omitted, which currently gives an 8 × 16 MiB spillover pool. The pool is allocated HERE so that events emitted between gate-open and Typhon.Engine.TyphonProfiler.Start(Typhon.Engine.IResource,Typhon.Engine.ProfilerSessionMetadata,Typhon.Engine.ProfilerOptions,System.Action) — typically during host bridge construction's spawn burst — can extend the chain instead of dropping.

Returns

bool

true if the gate was opened, false if the config wasn't active.

PrintDiagnostics(Action<string>, IList<IProfilerExporter>)

Print a multi-line diagnostic banner showing the active telemetry config + attached exporters. Useful at host startup when the operator wants visual confirmation that profiling is wired up. Logger delegate lets the host route output to its own log sink (Godot's GD.Print, Console.WriteLine, etc.).

public static void PrintDiagnostics(Action<string> log, IList<IProfilerExporter> exporters)

Parameters

log Action<string>

exporters IList<IProfilerExporter>

StartCpuSampler(ProfilerLaunchConfig)

Start an in-process CPU stack-sampling session for the profiling run, if requested. Returns the captured SamplingSessionStartQpc anchor (to be threaded into ProfilerSessionMetadata), or 0 when sampling is not active.

public static long StartCpuSampler(ProfilerLaunchConfig config)

Parameters

config ProfilerLaunchConfig

Returns

long

Remarks

A no-op returning 0 unless ProfilerCpuSamplingActive is set AND a trace file is configured — CPU sampling is file-mode only (it embeds into the .typhon-trace; live/TCP sampling is a later phase). Must be called before the host builds its ProfilerSessionMetadata, so the QPC anchor lands in the trace header.

StopCpuSampler()

Stop the CPU-sampling session started by StartCpuSampler(ProfilerLaunchConfig), parse its .nettrace capture (or await the parse already kicked by BeginCpuSamplerStop()), and hand the resolved samples to the trace-file exporter(s) so the close path embeds them as a trailer section (#351). The transient .nettrace is deleted afterwards — it is not a persisted artifact (design §2). Idempotent and best-effort: safe when no sampler is running, and a parse failure never throws into the host (the trace is simply written without CPU samples).

public static void StopCpuSampler()

Remarks

Must be called before TyphonProfiler.Stop() — the samples have to reach the Typhon.Engine.Internals.FileExporter before its Dispose writes the trace trailer.