bus

bus.Capabilities

bus.Capabilities() -> int

Returns the plugin's capability bitmask matching the asyncmeta constants.

This function takes no arguments.

asyncmeta.ProfileRouteService (=4095): every asyncmeta bit (the entire vocabulary supported).

printf("%d\n", bus.Capabilities());
printf("%d\n", (bus.Capabilities() ==
asyncmeta.ProfileRouteService()));

4095
1

bus.Open

bus.Open(callback, timeoutMs) -> int

Opens a subscription (callback registration) and returns the subscriptionId.

The subscriptionId (positive i64) to pass to other operations. Bad arguments or a closed plugin raises a runtime error.

callback i32 Echo(ref blob $X) { return(1); }
i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", ($sub > 0));

1

bus.OpenCount

bus.OpenCount() -> int

Returns the count of currently open subscriptions (plugin-wide, global view).

This function takes no arguments.

The number of open subscriptions (0 if none).

printf("%d\n", bus.OpenCount());
i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.OpenCount());

0
1

bus.Close

bus.Close() -> int

Plugin-wide shutdown: close every subscription and stop the background thread.

This function takes no arguments.

0 (always).

bus.Close();
print.Line("Close done");

Close done

bus.Send

bus.Send(request) -> int

Schedules an async job on the single open subscription (legacy: fails with multiple subs).

The jobId (positive i64). Multiple subs or no open sub raises a runtime error.

i64 $sub;
i64 $jobId;
blob $req[3];
$req[0] = 65;
$req[1] = 66;
$req[2] = 67;
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
printf("%d\n", ($jobId > 0));

1

bus.SendTo

bus.SendTo(subscriptionId, request) -> int

Schedules an async job to a SPECIFIC subscription.

The jobId (positive i64). An invalid subscriptionId or closed subscription raises a runtime error.

i64 $sub;
i64 $jobId;
blob $req[3];
$req[0] = 65;
$req[1] = 66;
$req[2] = 67;
$sub = bus.Open("Echo", 5000);
$jobId = bus.SendTo($sub, $req);
printf("%d\n", ($jobId > 0));

1

bus.SendBorrowedText

bus.SendBorrowedText(text) -> int

Schedules an async job with text input to the single open subscription.

The jobId (positive i64). Multiple subs or no open sub raises a runtime error.

i64 $sub;
i64 $jobId;
$sub = bus.Open("Echo", 5000);
$jobId = bus.SendBorrowedText("hi");
printf("%d\n", ($jobId > 0));

1

bus.SendBorrowedTextTo

bus.SendBorrowedTextTo(subscriptionId, text) ->
int

Schedules an async job with text input to a SPECIFIC subscription.

The jobId (positive i64).

i64 $sub;
i64 $jobId;
$sub = bus.Open("Echo", 5000);
$jobId = bus.SendBorrowedTextTo($sub, "world");
printf("%d\n", ($jobId > 0));

1

bus.WaitComplete

bus.WaitComplete(jobId, timeoutMs) -> int

Blocks until the job completes (jobId!), but does NOT destroy the job — status and result remain queryable.

1 if the job completed; 0 if the timeout expired and the job is still running.

i64 $sub;
i64 $jobId;
blob $req[3];
$req[0] = 65;
$req[1] = 66;
$req[2] = 67;
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
printf("%d\n", bus.WaitComplete($jobId, 5000));

1

bus.Take

bus.Take(jobId) -> blob

Returns the response blob of an already-completed job and destroys the job. Synonym for TakeBlob.

The response blob (the callback-modified request bytes). If the job has not completed, a runtime error.

i64 $sub;
i64 $jobId;
blob $req[3];
blob $resp[8];
$req[0] = 65;
$req[1] = 66;
$req[2] = 67;
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
$resp = bus.Take($jobId);
printf("%d\n", $resp.Length);

3

bus.TakeBlob

bus.TakeBlob(jobId) -> blob

Returns the response blob of an already-completed job and destroys the job. Synonym for Take.

The response blob.

i64 $sub;
i64 $jobId;
blob $req[3];
blob $resp[8];
$req[0] = 65;
$req[1] = 66;
$req[2] = 67;
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
$resp = bus.TakeBlob($jobId);
printf("%d %d %d\n", $resp[0], $resp[1], $resp[2]);

65 66 67

bus.Cancel

bus.Cancel(jobId) -> int

Attempts to remove a queued (not yet started) job.

1 if the job was removed from the queue; 0 if it is already running or has completed.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
printf("%d\n", bus.Cancel($jobId));

0

bus.SubscriptionState

bus.SubscriptionState(subscriptionId) -> int

Returns the subscription's state (open/closed).

1 (open, asyncmeta.RouteStateOpen), 0 (closed, RouteStateClosed).

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.SubscriptionState($sub));

1

bus.RouteState

bus.RouteState(subscriptionId) -> int

Synonym of SubscriptionState: returns the subscription state under the asyncmeta vocabulary.

asyncmeta.RouteStateOpen (=1) or RouteStateClosed (=0).

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.RouteState($sub));

1

bus.SubscriptionStateText

bus.SubscriptionStateText(subscriptionId) ->
string

Human-readable text of the state.

“open” or “closed”.

i64 $sub;
$sub = bus.Open("Echo", 5000);
print.Line(bus.SubscriptionStateText($sub));

open

bus.RouteStateText

bus.RouteStateText(subscriptionId) -> string

Synonym of SubscriptionStateText.

“open” or “closed”.

i64 $sub;
$sub = bus.Open("Echo", 5000);
print.Line(bus.RouteStateText($sub));

open

bus.SubscriptionCallback

bus.SubscriptionCallback(subscriptionId) ->
string

Returns the callback name passed at Open.

The callback name as text.

i64 $sub;
$sub = bus.Open("Echo", 5000);
print.Line(bus.SubscriptionCallback($sub));

Echo

bus.RouteCallback

bus.RouteCallback(subscriptionId) -> string

Synonym of SubscriptionCallback.

The callback name as text.

i64 $sub;
$sub = bus.Open("Echo", 5000);
print.Line(bus.RouteCallback($sub));

Echo

bus.SubscriptionTimeout

bus.SubscriptionTimeout(subscriptionId) -> int

Returns the timeout value passed at Open, in ms.

The timeoutMs value; -1 for infinite.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.SubscriptionTimeout($sub));

5000

bus.RouteTimeout

bus.RouteTimeout(subscriptionId) -> int

Synonym of SubscriptionTimeout.

The timeoutMs value.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.RouteTimeout($sub));

5000

bus.RouteKnown

bus.RouteKnown(subscriptionId) -> int

Tells whether the subscriptionId is known (still open in the plugin).

1 if known (open); 0 if not.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.RouteKnown($sub));

1

bus.RouteMeta

bus.RouteMeta(routeId, metaKey) -> int

Returns a specific meta field of the subscription by asyncmeta.RouteMeta* keys.

The value for the field.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.RouteMeta($sub,
asyncmeta.RouteMetaState()));
printf("%d\n", bus.RouteMeta($sub,
asyncmeta.RouteMetaDrained()));

1
1

bus.SubscriptionInfo

bus.SubscriptionInfo(subscriptionId) -> string

Returns the subscription state as a key=value diagnostic string.

A space-separated key=value list.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", (str.Len(bus.SubscriptionInfo($sub)) >
0));

1

bus.RouteInfo

bus.RouteInfo(subscriptionId) -> string

Synonym of SubscriptionInfo.

A key=value diagnostic string.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", (str.Len(bus.RouteInfo($sub)) >
0));

1

bus.SubscriptionPending

bus.SubscriptionPending(subscriptionId) -> int

Returns the number of pending (not yet started) jobs on the subscription.

The number of pending jobs.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.SubscriptionPending($sub));

0

bus.RoutePending

bus.RoutePending(subscriptionId) -> int

Synonym of SubscriptionPending.

The number of pending jobs.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.RoutePending($sub));

0

bus.SubscriptionQueued

bus.SubscriptionQueued(subscriptionId) -> int

Returns the number of queued jobs on the subscription.

The number of queued jobs.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.SubscriptionQueued($sub));

0

bus.RouteQueued

bus.RouteQueued(subscriptionId) -> int

Synonym of SubscriptionQueued.

The number of queued jobs.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.RouteQueued($sub));

0

bus.SubscriptionRunning

bus.SubscriptionRunning(subscriptionId) -> int

Returns the number of currently running jobs on the subscription.

The number of running jobs.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.SubscriptionRunning($sub));

0

bus.RouteRunning

bus.RouteRunning(subscriptionId) -> int

Synonym of SubscriptionRunning.

The number of running jobs.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.RouteRunning($sub));

0

bus.SubscriptionDrained

bus.SubscriptionDrained(subscriptionId) -> int

Tells whether the subscription is drained (pending = queued = running = 0).

1 if drained; 0 if something is in progress.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.SubscriptionDrained($sub));

1

bus.RouteDrained

bus.RouteDrained(subscriptionId) -> int

Synonym of SubscriptionDrained.

1 if drained; 0 if not.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.RouteDrained($sub));

1

bus.WaitDrained

bus.WaitDrained(subscriptionId, timeoutMs) -> int

Blocks until the subscription is drained, or timeoutMs expires.

1 if drain occurred before timeoutMs expired; 0 if it expired.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.WaitDrained($sub, 50));

1

bus.WaitRouteDrained

bus.WaitRouteDrained(subscriptionId, timeoutMs) ->
int

Synonym of WaitDrained.

1 if drain occurred; 0 if expired.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.WaitRouteDrained($sub, 50));

1

bus.State

bus.State(jobId) -> int

Returns a unified state code for the job (a shorthand of phase or completion-with-error).

A state code (a combination of Phase + Status).

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
printf("%d\n", bus.State($jobId));

2

bus.Phase

bus.Phase(jobId) -> int

Returns the job phase from the asyncmeta.Phase* constants.

asyncmeta.PhaseQueued (=0), PhaseRunning (=1), or PhaseCompleted (=2).

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
printf("%d\n", bus.Phase($jobId));

2

bus.PhaseText

bus.PhaseText(jobId) -> string

Returns the phase as text.

“queued”, “running”, or “completed”.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
print.Line(bus.PhaseText($jobId));

completed

bus.Status

bus.Status(jobId) -> int

Returns the job's status: 0 = success, non-zero = error.

0 if the job ran successfully; non-zero is the error code.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
printf("%d\n", bus.Status($jobId));

0

bus.StatusText

bus.StatusText(jobId) -> string

Textual counterpart of the status.

“success” on a successful job, other text depending on the error type.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
print.Line(bus.StatusText($jobId));

success

bus.ErrorText

bus.ErrorText(jobId) -> string

Returns the job error message (empty on success).

The error message text; empty string on a successful job.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
printf("%d\n", str.Len(bus.ErrorText($jobId)));

0

bus.JobInfo

bus.JobInfo(jobId) -> string

Returns the job state as a key=value diagnostic string.

A space-separated key=value list.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
printf("%d\n", (str.Len(bus.JobInfo($jobId)) >
0));

1

bus.JobSubscription

bus.JobSubscription(jobId) -> int

Returns the id of the subscription the job belongs to.

The subscriptionId.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
printf("%d\n", (bus.JobSubscription($jobId) ==
$sub));

1

bus.JobRoute

bus.JobRoute(jobId) -> int

Synonym of JobSubscription — returns the owning subscription/route id.

The subscriptionId (= routeId).

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
printf("%d\n", (bus.JobRoute($jobId) == $sub));

1

bus.JobTimeout

bus.JobTimeout(jobId) -> int

Returns the job's configured callback timeout in ms (inherited from the subscription).

The timeoutMs value.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
printf("%d\n", bus.JobTimeout($jobId));

5000

bus.JobKnown

bus.JobKnown(jobId) -> int

Tells whether the jobId is known to the plugin.

1 if known; 0 if not (e.g. already destroyed by Take).

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
printf("%d\n", bus.JobKnown($jobId));

1

bus.JobMeta

bus.JobMeta(jobId, metaKey) -> int

Returns a specific meta field of the job by asyncmeta.JobMeta* keys.

The value matching the field. JobMetaKnown returns 0 on an unknown jobId.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
printf("%d\n", bus.JobMeta($jobId,
asyncmeta.JobMetaPhase()));

2

bus.JobHasBlobResult

bus.JobHasBlobResult(jobId) -> int

Tells whether the job has a blob result (completed and successful).

1 if yes; 0 if no.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
printf("%d\n", bus.JobHasBlobResult($jobId));

1

bus.JobBlobResultSize

bus.JobBlobResultSize(jobId) -> int

Returns the response blob size in bytes (only for a completed, successful job).

The blob size in bytes. If the job did not complete successfully, a runtime error.

i64 $sub;
i64 $jobId;
blob $req[3];
$sub = bus.Open("Echo", 5000);
$jobId = bus.Send($req);
bus.WaitComplete($jobId, 5000);
printf("%d\n", bus.JobBlobResultSize($jobId));

3

bus.CloseSubscription

bus.CloseSubscription(subscriptionId) -> int

Closes the given subscription and cancels its queued jobs.

The count of queued jobs canceled by the close (0 = clean close with nothing pending).

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.CloseSubscription($sub));

0

bus.RouteClose

bus.RouteClose(subscriptionId) -> int

Synonym of CloseSubscription — exact same handler.

The count of canceled queued jobs.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", bus.RouteClose($sub));

0

bus.RouteCloseAccepted

bus.RouteCloseAccepted(subscriptionId) -> int

Tells whether a close request has been accepted on the subscription.

1 if yes; 0 if no RouteClose / CloseSubscription has happened yet.

i64 $sub;
$sub = bus.Open("Echo", 5000);
bus.RouteClose($sub);
printf("%d\n", bus.RouteCloseAccepted($sub));

1

bus.RouteClosedQueued

bus.RouteClosedQueued(subscriptionId) -> int

Returns the count of queued jobs canceled by the most recent RouteClose / CloseSubscription.

The count of canceled queued jobs.

i64 $sub;
$sub = bus.Open("Echo", 5000);
bus.RouteClose($sub);
printf("%d\n", bus.RouteClosedQueued($sub));

0

bus.RouteCloseInfo

bus.RouteCloseInfo(subscriptionId) -> string

Returns the subscription shutdown process as a key=value diagnostic string.

A space-separated key=value list.

i64 $sub;
$sub = bus.Open("Echo", 5000);
printf("%d\n", (str.Len(bus.RouteCloseInfo($sub)) >
0));

1

Practical notes

What the bus plugin is good for

• Generic async callback channel without network protocol: the code controls when and what request to send to the callback.

• Parallel management of multiple channels: each subscription serves its own callback with separate state/traffic metrics.

• asyncmeta compatibility with the full vocabulary: Phase, Status, JobMeta, RouteMeta, WaitDrained, RouteClose — every bit supported (Capabilities = 4095).

• The subscription/route synonym pair allows stylistic choice in code — Subscription* names are direct, Route* names follow the asyncmeta convention.

Send vs SendTo usage

If your code opens only one subscription, `Send(request)` is simpler — no explicit subscriptionId needed. But if you ever open a second subscription (or some library calls Open without your knowledge), Send will fail. For defensive programming `SendTo(subscriptionId, request)` is always preferred — explicit, portable, and clearer in code about which channel you're sending to.

WaitComplete — a crucial detail

The `WaitComplete(jobId, timeoutMs)` parameter table in the registration is `gSubscriptionWaitParams` — which may suggest it takes a subscriptionId. The source code is unambiguous: `JobId = Args[0]` — it takes the JOB id. The parameter table here only encodes the argument TYPE and COUNT (one int, one int), not semantics. This is an important detail: if you accidentally pass a subscriptionId, the error message will be “job not found”. Always pass a jobId to WaitComplete.

RouteClose / CloseSubscription return value

The two calls (`RouteClose` and `CloseSubscription`) are the SAME handler — two names, identical behavior. The return value is NOT a 1/0 success flag, but the COUNT of queued jobs canceled by the close. Typically 0 (clean close with no pending jobs). A positive value: that many queued jobs were lost. A subscription closed once cannot be reopened — a second call raises a runtime error with “subscription is not open”.

Two-step shutdown pattern

(1) `RouteClose(subscriptionId)` (or `CloseSubscription`): signals the subscription is to be closed. Queued jobs are canceled; the running callback may finish. (2) `WaitRouteDrained(subscriptionId, timeoutMs)`: waits until every in-flight job is done. (3) `Close()` (plugin-wide): full plugin shutdown, including every subscription. The `RouteCloseAccepted` LATCH flips to 1 on the first RouteClose and stays — useful for diagnostics.

Error handling

An invalid jobId, subscriptionId, wrong argument count or type, out-of-range timeoutMs, touching an already-closed subscription, and touching an already-closed plugin are reported by the runtime as a runtime error, and the script stops. A WaitComplete wait-timeout is `DOMIN_STATUS_TIMEOUT`; a Close-style shutdown is `DOMIN_STATUS_SHUTDOWN`. Take/TakeBlob only accept completed (Phase=Completed) jobs.