# Module: `nupp.zone` Gated LuaJIT profiler zones: the stack work is skipped until a profiler asks for it. Stock `jit.zone` pushes and pops whether or not anything is listening. Skipping that is worth doing, but it is not the main cost: a zone marker is a call inside the code being measured, and calls in a hot path abort traces. Mark warm paths, not the hottest ones. `jit.zone` itself is left alone. Replacing its `__call` with a no-op would silently blank every other user of the one global stack, `luajit -jp=z` included. The trade is that while a session is held this is the only writer: a direct `jit.zone` push in that window is overwritten. `acquire` and `release` are counted, so several channels can share one stack. This is process-wide, not per-coroutine. `push` and `pop` are compiler intrinsics: a call in statement position on a receiver statically known to hold this module is generated inline against the fields below, rather than made, with `pop`'s popped name also needing to be discarded — the same call a hot path would otherwise pay for is what the note above is about. The fields exist for that generated code to reach; every other call site, and every function below, still goes through the ordinary API. ## Functions ### `zone.acquire` _function_ Starts recording, or joins a recording in progress. Needs a matching `release`. The first caller clears the stack and opens a new generation, so tokens from an earlier session cannot pop into this one. ```nupp function zone.acquire(): nil ``` #### Returns | Type | Description | | --- | --- | | `nil` | | ### `zone.current` _function_ The innermost zone, without popping it. ```nupp function zone.current(): string? ``` #### Returns | Type | Description | | --- | --- | | `string?` | | ### `zone.depth` _function_ How many zones are pushed. Zero when inactive. ```nupp function zone.depth(): integer ``` #### Returns | Type | Description | | --- | --- | | `integer` | | ### `zone.enter` _function_ Pushes a zone and returns a token for `leave`, or 0 when inactive. The paired form, for a `leave` that may run after its session ended — usually a coroutine resumed after a profile stopped. The token carries the generation, so a late `leave` is discarded rather than popping someone else's zone. ```nupp function zone.enter(name: string): integer ``` #### Arguments | Name | Type | Description | | --- | --- | --- | | `name` | `string` | | #### Returns | Type | Description | | --- | --- | | `integer` | | ### `zone.isActive` _function_ Whether pushes and pops are being recorded. ```nupp function zone.isActive(): boolean ``` #### Returns | Type | Description | | --- | --- | | `boolean` | | ### `zone.leave` _function_ Closes a zone opened by `enter`. A zero token, a stale generation, or an empty stack are all ignored. ```nupp function zone.leave(token: integer): nil ``` #### Arguments | Name | Type | Description | | --- | --- | --- | | `token` | `integer` | | #### Returns | Type | Description | | --- | --- | | `nil` | | ### `zone.path` _function_ The pushed zones joined with "/", outermost first, or "" when none are. Cached until the stack next changes, so reading it repeatedly between two pushes costs a comparison. That is worth the two words it takes: a profiler reads this from the sampling callback, on the thread it interrupted, and a string built fresh there is an allocation charged to whatever the program happened to be doing — which the same profiler then reports as collector time the program did not spend. ```nupp function zone.path(): string ``` #### Returns | Type | Description | | --- | --- | | `string` | | ### `zone.pop` _function_ Pops the innermost zone, or nil when inactive or empty. Empty is not an error: a profile can start or stop part-way through a frame, leaving half a pair outside the session. Called in statement position on a receiver statically known to be this module, with the popped name discarded, this is generated inline instead — see the module comment. ```nupp function zone.pop(): string? ``` #### Returns | Type | Description | | --- | --- | | `string?` | | ### `zone.push` _function_ Pushes a zone. A no-op while inactive. Called in statement position on a receiver statically known to be this module, this is generated inline against the fields above rather than called — see the module comment. ```nupp function zone.push(name: string): nil ``` #### Arguments | Name | Type | Description | | --- | --- | --- | | `name` | `string` | | #### Returns | Type | Description | | --- | --- | | `nil` | | ### `zone.release` _function_ Releases one `acquire`; the last empties the stack. Releasing nothing is ignored, so a teardown that runs twice is harmless. ```nupp function zone.release(): nil ``` #### Returns | Type | Description | | --- | --- | | `nil` | |