Module: nupp.profile

record profile.AbortSite
    severity: profile.Severity
    count: integer
    reason: string
    location: string
    zonePath: string
end

record profile.Sample
    zonePath: string
    stack: string
    count: integer
    compiled: integer
    interpreted: integer
    cCode: integer
    collecting: integer
    compiling: integer
end

type profile.SampleOptions = {
    --- Milliseconds between samples; 10 by default, which is 100 a second. Below about
    --- 10 the timer starts taking real time away from the thread it is measuring, so
    --- lower it for a short window and read the result knowing that it was paid for.
    intervalMs: integer?,

    --- How many frames to walk per sample; 16 by default. The walk is linear in this
    --- and it happens on the interrupted thread, so raise it only when a specific
    --- question needs the depth.
    stackDepth: integer?,

    --- Keep only the samples taken under a zone path starting with this, so
    --- "frame/render" reads as that subtree alone.
    ---
    --- Applied at `stop` rather than while sampling: narrowing it costs nothing at
    --- runtime, and widening it afterwards is not possible, because the prefix is fixed
    --- when the session starts.
    zone: string?,

    --- The module the program starts at, as a stack frame names it. Everything below
    --- the outermost frame from it is dropped.
    ---
    --- A profiler samples the whole stack it is embedded in, and what is under the
    --- program — the loader that read it, the pcall that guards it — is not the
    --- program. Naming its module cuts the report back to it.
    ---
    --- Frames read "<module>:<name>", so the module is the part to give. A stack with
    --- no frame from it is kept whole rather than emptied, and two stacks that differ
    --- only below the root become one, their counts summed.
    root: string?
}

record profile.SampleReport
    intervalMs: integer
    samples: integer
    stacks: integer
    text: string

    metamethod __tostring: function(self): string
end

record profile.SampleSession is profile.Session
    associated type Report = profile.SampleReport
    intervalMs: integer
    zoneFilter: string?
    root: string?
    paused: boolean
    stopped: boolean
    aggregate: {[string]: {[string]: profile.Sample}}

    pause: function(self)
    resume: function(self)
    stop: function(self, filename: string?): self.Report
end

interface profile.Session
    associated type Report

    pause: function(self)
    resume: function(self)
    stop: function(self, filename: string?): self.Report
end

type profile.Severity = "blacklist" | "warn" | "info"

type profile.TraceOptions = {
    --- Include the aborts that are ordinary trace formation rather than a refusal —
    --- leaving a loop, recursion, an inner loop. False by default; turn it on when the
    --- question is why a particular trace never formed.
    includeBenign: boolean?
}

record profile.TraceReport
    durationSec: integer
    totalAborts: integer
    blacklisted: integer
    sites: {profile.AbortSite}

    metamethod __tostring: function(self): string
end

record profile.TraceSession is profile.Session
    associated type Report = profile.TraceReport
    includeBenign: boolean
    startedAt: integer
    paused: boolean
    stopped: boolean
    sites: {[string]: profile.AbortSite}
    totalAborts: integer
    blacklisted: integer
    callback: function(...: any)

    pause: function(self)
    resume: function(self)
    stop: function(self, filename: string?): self.Report
end

function profile.sample(options: profile.SampleOptions?): profile.SampleSession

function profile.SampleSession:pause()

function profile.SampleSession:resume()

function profile.SampleSession:stop(filename: string?): profile.SampleReport

function profile.trace(options: profile.TraceOptions?): profile.TraceSession

function profile.TraceSession:pause()

function profile.TraceSession:resume()

function profile.TraceSession:stop(filename: string?): profile.TraceReport