Written from a line-by-line source review; every example output is from a real run.
Introduction
The asyncmeta plugin is a constants catalog for DominScript's async callback plugins (callback_worker, callback_listener, callback_*_listener, etc.). It does not start threads and does no I/O — every function returns a well-known integer (a phase identifier, status, capability bit, profile bitmask, field key, or route state). It is the central “shared vocabulary” so that cooperation across plugins refers to the same numbers.
What it is for (and what it is not for)
This plugin is purely DEFINITIONAL: it provides constants and bitmask helpers. On its own it does nothing — the matching WORKING plugins (callback_worker for running async jobs, callback_*_listener for network services) must be loaded in the script the usual way. asyncmeta is the bridge between them: when a backend returns a JobMeta field or a phase, you find its name and code here.
Six concepts
The catalog covers six concepts. (1) PHASE: an async job's life cycle — Queued, Running, Completed. (2) STATUS: the job's current state of completion (Pending). (3) CAPABILITY: a single capability bit that a backend may support (WaitComplete, JobMeta, RouteClose, etc.). (4) CAPABILITY PROFILE: typical capability packages, like JobInspect, BlobJob, RouteControl, RouteService. (5) ROUTE STATE: a route surface open or closed. (6) META FIELD KEY: the field numbers for JobMeta and RouteMeta queries.
Loading the plugin
plugin "../plugins/print/PrintPlugin"; plugin "../plugins/async_meta/AsyncMetaPlugin";
A typical flow — capability check against a backend
i32 $mask; $mask = backend.Capabilities(); // the backend returns its supported bits if (asyncmeta.SupportsJobInspect($mask) == 1) { // the backend supports the whole JobInspect profile // (WaitComplete + JobMeta + PhaseText + StatusText + JobInfo + Known) }
What to know about every function (the basics)
The vast majority (38 verbs) take NO arguments — they return a known integer constant.
The remaining 6 verbs (HasAllCapabilities, HasCapability, SupportsJobInspect, SupportsBlobJob, SupportsRouteControl, SupportsRouteService) are BITMASK queries: the caller gives the capability mask to check, and gets 1/0.
PHASE ids follow the job's life cycle in order 0/1/2 (Queued → Running → Completed).
CAPABILITY bits are powers of two (1, 2, 4, …, 2048) — combined freely in a bitmask.
PROFILE bitmasks are ready-made packages: e.g. ProfileBlobJob = ProfileJobInspect | BlobTake | BlobResultMeta.
META KEYS start at 1 (0 is not a valid field key).
The whole plugin is DETERMINISTIC and purely in-process — no network, file, or thread needed.
How to read the signatures
Most verbs take no arguments and return an int. The bitmask helpers (HasAllCapabilities, HasCapability) take two integers: the mask to check and the reference mask/bit. The Supports* helpers take a single integer (the mask) and internally compare against the matching profile bitmask.
Phase and status identifiers
The phases of an async job's life cycle and the code of its current status.
asyncmeta.PhaseQueued
asyncmeta.PhaseQueued() -> int
Returns the identifier of the “QUEUED” phase (the job is waiting in the queue).
This function takes no arguments.
0.
printf("%d\n", asyncmeta.PhaseQueued());0
For comparing a job's current phase: if (value-from-asyncmeta.JobMetaPhase() == asyncmeta.PhaseQueued()), the job has not yet started.
asyncmeta.PhaseRunning
asyncmeta.PhaseRunning() -> int
Returns the identifier of the “RUNNING” phase (the job is currently executing).
This function takes no arguments.
1.
printf("%d\n", asyncmeta.PhaseRunning());1
For filtering the in-flight (not yet completed) jobs.
asyncmeta.PhaseCompleted
asyncmeta.PhaseCompleted() -> int
Returns the identifier of the “COMPLETED” phase (the job has finished executing).
This function takes no arguments.
2.
printf("%d\n", asyncmeta.PhaseCompleted());2
To check that a job has already finished — at this point the result or status can be retrieved.
asyncmeta.StatusPending
asyncmeta.StatusPending() -> int
Returns the code of the “PENDING” status (the job has not fully finished its work yet).
This function takes no arguments.
1.
printf("%d\n", asyncmeta.StatusPending());1
To recognize that a job is not currently done — alongside the phases, this is the finer state code that the backend gives.
Capability bits
A single capability bit that an async backend may support. Powers of two; freely combined in a bitmask (with bitwise or). A backend usually provides its own mask through a capabilities query.
asyncmeta.CapabilityWaitComplete
asyncmeta.CapabilityWaitComplete() -> int
Bit for supporting waiting for job completion (WaitForCompletion).
This function takes no arguments.
1.
printf("%d\n", asyncmeta.CapabilityWaitComplete());1
Comparing the inspected backend's mask with this bit, you can decide whether synchronous waiting on a job is possible.
asyncmeta.CapabilityWaitDrained
asyncmeta.CapabilityWaitDrained() -> int
Bit for waiting on a route's “drained” (all items finished) state.
This function takes no arguments.
2.
printf("%d\n", asyncmeta.CapabilityWaitDrained());2
For a route-control plugin: signals whether the backend can tell when the processing queue is empty.
asyncmeta.CapabilityJobMeta
asyncmeta.CapabilityJobMeta() -> int
Bit for supporting JobMeta queries (a job's state field by field).
This function takes no arguments.
4.
printf("%d\n", asyncmeta.CapabilityJobMeta());4
If set, you can use the JobMeta* field keys for fine-grained queries on a job's state.
asyncmeta.CapabilityRouteMeta
asyncmeta.CapabilityRouteMeta() -> int
Bit for supporting RouteMeta queries (a route's state field by field).
This function takes no arguments.
8.
printf("%d\n", asyncmeta.CapabilityRouteMeta());8
If set, you can use the RouteMeta* field keys to query a route's state.
asyncmeta.CapabilityPhaseText
asyncmeta.CapabilityPhaseText() -> int
Support for human-readable names of the phases (Queued/Running/Completed).
This function takes no arguments.
16.
printf("%d\n", asyncmeta.CapabilityPhaseText());16
For logging or UI display: if this bit is set, alongside the phase ids the backend can also give a textual name.
asyncmeta.CapabilityStatusText
asyncmeta.CapabilityStatusText() -> int
Support for human-readable names of the status codes.
This function takes no arguments.
32.
printf("%d\n", asyncmeta.CapabilityStatusText());32
The counterpart of PhaseText: gives traceable text for the status.
asyncmeta.CapabilityJobInfo
asyncmeta.CapabilityJobInfo() -> int
Support for a job's detailed info record (a summary).
This function takes no arguments.
64.
printf("%d\n", asyncmeta.CapabilityJobInfo());64
If set, the backend can give a unified “info” structure about the job's complete state.
asyncmeta.CapabilityRouteInfo
asyncmeta.CapabilityRouteInfo() -> int
Support for a route's detailed info record.
This function takes no arguments.
128.
printf("%d\n", asyncmeta.CapabilityRouteInfo());128
The counterpart of JobInfo: signals the route-level info query.
asyncmeta.CapabilityRouteClose
asyncmeta.CapabilityRouteClose() -> int
Support for programmatically closing a route.
This function takes no arguments.
256.
printf("%d\n", asyncmeta.CapabilityRouteClose());256
For a controlled shutdown: if set, the backend offers a Close operation for routes.
asyncmeta.CapabilityBlobTake
asyncmeta.CapabilityBlobTake() -> int
Support for taking a job's blob result (Take).
This function takes no arguments.
512.
printf("%d\n", asyncmeta.CapabilityBlobTake());512
For jobs that yield a blob result: the backend supports actually taking the blob (not just querying the result size).
asyncmeta.CapabilityBlobResultMeta
asyncmeta.CapabilityBlobResultMeta() -> int
Queryability of the blob result's metadata (whether it exists, how big it is).
This function takes no arguments.
1024.
printf("%d\n", asyncmeta.CapabilityBlobResultMeta());1024
Signals the valid queryability of the JobMetaHasBlobResult / JobMetaBlobResultSize field keys.
asyncmeta.CapabilityKnown
asyncmeta.CapabilityKnown() -> int
Support for the “is the field known?” (Known) probes, so you can clearly distinguish no-field from 0-value.
This function takes no arguments.
2048.
printf("%d\n", asyncmeta.CapabilityKnown());2048
If set, JobMetaKnown / RouteMetaKnown lets you ask: does the backend even know about the given field — or is the value just an accidental 0.
Capability profiles
Typical capability packages (bitmasks) that arise as the logical OR of individual bits. The backend can be queried with a single value comparison whether it supports a profile as a whole.
asyncmeta.ProfileJobInspect
asyncmeta.ProfileJobInspect() -> int
The minimum capability package needed for inspecting a job's state: WaitComplete | JobMeta | PhaseText | StatusText | JobInfo | Known.
This function takes no arguments.
2165 (the logical OR of the above bits).
printf("%d\n", asyncmeta.ProfileJobInspect());2165
For checking that the backend supports the full “query and track” pattern on a job. The SupportsJobInspect helper does the same.
asyncmeta.ProfileBlobJob
asyncmeta.ProfileBlobJob() -> int
Package needed for jobs that yield a blob result: ProfileJobInspect + BlobTake + BlobResultMeta.
This function takes no arguments.
3701.
printf("%d\n", asyncmeta.ProfileBlobJob());3701
If the backend supports it, you can confidently wait for a job's blob result: query the size in advance, then Take it.
asyncmeta.ProfileRouteControl
asyncmeta.ProfileRouteControl() -> int
Package needed for route control: WaitDrained | RouteMeta | RouteInfo | RouteClose | Known.
This function takes no arguments.
2442.
printf("%d\n", asyncmeta.ProfileRouteControl());2442
For checking the presence of route-level control: whether the backend can send Close and wait for the “drained” state.
asyncmeta.ProfileRouteService
asyncmeta.ProfileRouteService() -> int
Full service-level package: ProfileBlobJob | ProfileRouteControl (i.e. every capability together).
This function takes no arguments.
4095 (all defined bits together).
printf("%d\n", asyncmeta.ProfileRouteService());4095
The “every capability” package — the caller uses it when they want to take advantage of every function (Blob results + route control together).
Route states
The two basic states of a route.
asyncmeta.RouteStateClosed
asyncmeta.RouteStateClosed() -> int
Code of the “CLOSED” route state (the route is closed, accepting no new job).
This function takes no arguments.
0.
printf("%d\n", asyncmeta.RouteStateClosed());0
For comparing the value returned by RouteMetaState: if == RouteStateClosed(), the route no longer accepts new work.
asyncmeta.RouteStateOpen
asyncmeta.RouteStateOpen() -> int
Code of the “OPEN” route state (the route accepts new jobs).
This function takes no arguments.
1.
printf("%d\n", asyncmeta.RouteStateOpen());1
To recognize an open route: whether a job can still be submitted into the queue.
JobMeta field keys
The field numbers for a JobMeta query. 0 is NOT a valid field key — every real field starts at 1.
asyncmeta.JobMetaPhase
asyncmeta.JobMetaPhase() -> int
Field key for the job's current phase (PhaseQueued/Running/Completed).
This function takes no arguments.
1.
printf("%d\n", asyncmeta.JobMetaPhase());1
For the backend's JobMeta query: this key is used to query a job's current phase.
asyncmeta.JobMetaStatus
asyncmeta.JobMetaStatus() -> int
Field key for the job's current status (StatusPending, etc.).
This function takes no arguments.
2.
printf("%d\n", asyncmeta.JobMetaStatus());2
For querying the finer status (finer than the phase).
asyncmeta.JobMetaRoute
asyncmeta.JobMetaRoute() -> int
Field key for the route identifier the job belongs to.
This function takes no arguments.
3.
printf("%d\n", asyncmeta.JobMetaRoute());3
To determine which route is running the job — especially useful with a multi-route backend.
asyncmeta.JobMetaTimeout
asyncmeta.JobMetaTimeout() -> int
Field key for the job's configured timeout (in milliseconds).
This function takes no arguments.
4.
printf("%d\n", asyncmeta.JobMetaTimeout());4
For querying the remaining time or the configured limit.
asyncmeta.JobMetaKnown
asyncmeta.JobMetaKnown() -> int
Field key for the “is the job known?” (Known) probe.
This function takes no arguments.
5.
printf("%d\n", asyncmeta.JobMetaKnown());5
For clearly distinguishing “no such job” from “a 0-valued field”: if Known is 0, the job itself is not known.
asyncmeta.JobMetaHasBlobResult
asyncmeta.JobMetaHasBlobResult() -> int
Key of the “does the job have a blob result?” probe.
This function takes no arguments.
6.
printf("%d\n", asyncmeta.JobMetaHasBlobResult());6
After a job's completion: a quick check before querying the blob.
asyncmeta.JobMetaBlobResultSize
asyncmeta.JobMetaBlobResultSize() -> int
Field key for the blob result's size (in bytes).
This function takes no arguments.
7.
printf("%d\n", asyncmeta.JobMetaBlobResultSize());7
For a preliminary size query before taking the result — e.g. if you want to preallocate the matching blob buffer.
RouteMeta field keys
The field numbers for a RouteMeta query. They cover both the route's configuration (Timeout, State) and runtime statistics (Pending/Queued/Running/Drained).
asyncmeta.RouteMetaState
asyncmeta.RouteMetaState() -> int
Field key for the route's current state (RouteStateClosed/Open).
This function takes no arguments.
1.
printf("%d\n", asyncmeta.RouteMetaState());1
For a simple state check: whether the route is Open or Closed.
asyncmeta.RouteMetaTimeout
asyncmeta.RouteMetaTimeout() -> int
Field key for the route's configured timeout.
This function takes no arguments.
2.
printf("%d\n", asyncmeta.RouteMetaTimeout());2
For querying the route-level timeout, when the backend manages several routes separately.
asyncmeta.RouteMetaPending
asyncmeta.RouteMetaPending() -> int
Key for the number of pending (not yet started) jobs.
This function takes no arguments.
3.
printf("%d\n", asyncmeta.RouteMetaPending());3
For predicting the backend's load: how many jobs are still waiting to start.
asyncmeta.RouteMetaQueued
asyncmeta.RouteMetaQueued() -> int
Key for the number of queued jobs.
This function takes no arguments.
4.
printf("%d\n", asyncmeta.RouteMetaQueued());4
For monitoring the queue's current length: the level of congestion typically depends on this.
asyncmeta.RouteMetaRunning
asyncmeta.RouteMetaRunning() -> int
Key for the number of currently running jobs.
This function takes no arguments.
5.
printf("%d\n", asyncmeta.RouteMetaRunning());5
For the backend's parallel utilization: how many jobs are at work at the same time.
asyncmeta.RouteMetaDrained
asyncmeta.RouteMetaDrained() -> int
Key for the “is the queue drained?” probe.
This function takes no arguments.
6.
printf("%d\n", asyncmeta.RouteMetaDrained());6
For a quick check: whether every pending piece of work on the route has finished (Pending = Queued = Running = 0).
asyncmeta.RouteMetaKnown
asyncmeta.RouteMetaKnown() -> int
Field key for the “is the route known?” probe.
This function takes no arguments.
7.
printf("%d\n", asyncmeta.RouteMetaKnown());7
For distinguishing an unknown route from a 0-value: if Known is 0, the route itself is not known to the backend.
asyncmeta.RouteMetaCloseAccepted
asyncmeta.RouteMetaCloseAccepted() -> int
Key of the “did the backend accept the Close request?” probe.
This function takes no arguments.
8.
printf("%d\n", asyncmeta.RouteMetaCloseAccepted());8
For acknowledging a Close operation: whether the backend has noted the request, even if the route has not yet actually closed.
asyncmeta.RouteMetaClosedQueued
asyncmeta.RouteMetaClosedQueued() -> int
Key of the “has the Close been queued?” probe (the backend has scheduled the shutdown).
This function takes no arguments.
9.
printf("%d\n", asyncmeta.RouteMetaClosedQueued());9
For precisely tracking the shutdown phase: the Close request is already in the queue, but the route is still running its incoming jobs.
Bitmask helpers
Small bitmask operations that give a yes/no answer from a given capability mask. The first argument is the mask to inspect (the backend's capabilities); the rest are the reference.
asyncmeta.HasAllCapabilities
asyncmeta.HasAllCapabilities(mask, required) -> int
Checks whether the given mask contains ALL the required bits.
| Parameter | Type | Description |
|---|---|---|
| mask | int | The capability mask to inspect (the backend's supported bits). |
| required | int | The mask of required bits (bitwise OR of one or more bits). |
1 if (mask & required) == required (every required bit is present); otherwise 0.
printf("%d\n",
asyncmeta.HasAllCapabilities(asyncmeta.ProfileJobInspect(),
asyncmeta.ProfileJobInspect()));
printf("%d\n",
asyncmeta.HasAllCapabilities(asyncmeta.ProfileJobInspect(),
asyncmeta.CapabilityRouteMeta()));1 0
For checking full support of a composite capability package. The higher-level Supports* helpers also give a profile-level yes/no answer; they use this internally.
asyncmeta.HasCapability
asyncmeta.HasCapability(mask, capability) -> int
Checks whether a specific capability bit is in the mask.
| Parameter | Type | Description |
|---|---|---|
| mask | int | The capability mask to inspect. |
| capability | int | A single capability bit (a Capability* value). |
1 if (mask & capability) != 0; otherwise 0.
printf("%d\n", asyncmeta.HasCapability(asyncmeta.ProfileJobInspect(),
asyncmeta.CapabilityJobMeta()));
printf("%d\n", asyncmeta.HasCapability(asyncmeta.ProfileJobInspect(),
asyncmeta.CapabilityRouteMeta()));1 0
For a quick lookup of a single capability. HasAllCapabilities called with a single bit gives the same, but this form is more readable when you really only inspect one bit.
asyncmeta.SupportsJobInspect
asyncmeta.SupportsJobInspect(mask) -> int
Checks whether the given mask fully contains the ProfileJobInspect package.
| Parameter | Type | Description |
|---|---|---|
| mask | int | The capability mask to inspect. |
1 if every bit of the JobInspect profile is in; otherwise 0.
printf("%d\n",
asyncmeta.SupportsJobInspect(asyncmeta.ProfileBlobJob()));1
Use it when the backend is only suitable if it supports the whole job-query pattern. BlobJob is a superset of this, so ProfileBlobJob → 1.
asyncmeta.SupportsBlobJob
asyncmeta.SupportsBlobJob(mask) -> int
Checks whether the mask contains the ProfileBlobJob package (JobInspect + BlobTake + BlobResultMeta).
| Parameter | Type | Description |
|---|---|---|
| mask | int | The capability mask to inspect. |
1 if every required bit is in; otherwise 0.
printf("%d\n",
asyncmeta.SupportsBlobJob(asyncmeta.ProfileJobInspect()));0
Use it when blob-result handling is definitely needed. The plain JobInspect profile is not enough for this (no BlobTake in it), so the example above returns 0.
asyncmeta.SupportsRouteControl
asyncmeta.SupportsRouteControl(mask) -> int
Checks whether the mask contains the ProfileRouteControl package.
| Parameter | Type | Description |
|---|---|---|
| mask | int | The capability mask to inspect. |
1 if every required bit is in; otherwise 0.
printf("%d\n", asyncmeta.SupportsRouteControl(0));0
For preliminary checking of route-level control (Close, Drained state) availability.
asyncmeta.SupportsRouteService
asyncmeta.SupportsRouteService(mask) -> int
Checks whether the mask contains the full ProfileRouteService package (BlobJob + RouteControl).
| Parameter | Type | Description |
|---|---|---|
| mask | int | The capability mask to inspect. |
1 if every required bit is in; otherwise 0.
printf("%d\n",
asyncmeta.SupportsRouteService(asyncmeta.ProfileRouteService()));1
For checking the “full functionality” backend expectation: if 0, the backend is not suitable for the complete service.
Practical notes
What the asyncmeta plugin is good for
A uniform constants catalog for several async plugins: the phase, status, capability, and field-key numbers are defined in one place.
Inspecting a backend's capabilities: the caller does not assume but checks which functions the chosen backend supports.
Readable code: meaningful names in the source instead of magic numbers (1, 2, 4, …).
Uniform field keys for JobMeta and RouteMeta queries, so the same script works the same way with different backends.
Typical pattern — checking backend capabilities
At startup the script queries the backend's capabilities mask (a single integer), and with the Supports* helpers decides what functions it can rely on. If the full profile is supported, it uses the full functionality; if only partial, it works in a reduced mode (e.g. tracking only phase-level state). HasCapability and HasAllCapabilities are for finer, bit-level decisions.
Numeric values overview
PHASE: 0 (Queued) / 1 (Running) / 2 (Completed). STATUS: 1 (Pending). CAPABILITY bits: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048 (twelve bits total, so the maximum is 4095 = all). PROFILES: 2165 (JobInspect), 3701 (BlobJob), 2442 (RouteControl), 4095 (RouteService — every bit). ROUTE state: 0 (Closed) / 1 (Open). JobMeta keys: 1..7. RouteMeta keys: 1..9. 0 always means “none/unknown” throughout.
Deterministic and in-process
The whole plugin is purely definitional: it starts no threads, opens no files, and accesses no network. Every call is a deterministic constant return or a simple bitmask operation. So it is safely used in every environment (including headless ones), alongside any other asyncmeta-compatible plugin.
Error handling
A wrong argument count or type, or a missing result pointer, raises a runtime error (the script stops). The bitmask helpers (HasAllCapabilities, HasCapability, Supports*) give a neutral 0/1 — they do not raise an error on the value content; 0 always means “not complete / not present”.
The print formatted output plugin
Writing formatted text to standard output — complete function reference