Service

moduleextensionexperimentalSource

Available on macOS, Linux, Windows, Wasm·since 0.31.0

#import "Extensions/Service";

Compile-time services.

A service is a long-lived program that compile-time code asks questions: one that keeps a database connection open, say, so #run code can learn a query's types without connecting on every compile. The compiler starts it the first time it is called (jaic <file> -interp), keeps it running between calls, and restarts it when its sources change.

The service side (service.jai):

Example↗

#import "String";
Service :: #import "Extensions/Service";
main :: () {
    Service.serve((request: string) -> Service.Status, string {
        return .OK, to_upper_copy(request);
    });
}

This one is only checked to compile, not run.

The compile-time side:

Example

SERVICE :: #run tprint("%service.jai", #filepath);
#run {
    status, answer := Service.call(SERVICE, "hello");
    if status == {
        case .OK;          print("%\n", answer);
        case .PENDING;     Service.unknown("asking the service");   // editor only
        case .UNAVAILABLE; Service.unknown(answer);
        case .FAILED;      compiler_report(answer);
    }
}

Not run: the example is marked ignore.

Not run: it works at compile time, against a running service.

In a build, call waits for the answer. In the editor (a trusted workspace) it answers .PENDING while the service works, and the editor checks the file again once the answer is in. Untrusted workspaces run no compile-time code at all.

Procedures#

callexperimentalsince 0.31.0Source

(service: string, request: string) -> (Status, string)

Asks the service in the file service (absolute, or relative to the compiler's working directory). The reply lives until the end of the compile.

unknownexperimentalsince 0.31.0Source

(message: string)

Stops the compile-time code that called it: its result is not known here (a reply was pending or unavailable). A build reports message as an error; the editor reports nothing and keeps checking the rest of the file.

serveexperimentalsince 0.31.0Source

(handler: (request: string) -> (Status, string))

The service side: answers each request with handler until the compiler closes the input. Return .OK with the reply, .FAILED with an error message, or .UNAVAILABLE with the reason the service cannot answer here (no database configured, say). Whatever the handler prints or logs goes to stderr: stdout carries the answers.

Types#

StatusenumforeignexperimentalSource

:: enum

OK: the answer is the service's reply
PENDING: editor only: the reply is not in yet; the file is checked again later
UNAVAILABLE: no service here (no jaic to run it, a sandbox, or the service gave up)
FAILED: the service crashed, timed out, ran out of memory or reported an error