Home/Book/XServer Layer API Reference
23 APIs · in-process direct calls (resolved by address via tcc_add_symbol)

XServer Layer API Reference

Implemented inside the host's single process; scripts call them directly by address. Every other capability is an xrt or extension symbol — beyond this page, see the xrt group index.

Topology queries (7)

The retained-lease discipline: xsServerFind returns a lease with a reference, which must be paired with xsServerRelease; enumeration callback parameters are borrowed for the callback only — xsServerRetain before storing them. A host is jointly protected by its server lease.

xsServerFind query

Find a server by its globally unique name; returns a retained lease.

XS_ServerInfo* xsServerFind(const char* sName);
Returns: NULL = not foundOwnership: retained; must be Released
Example
XS_ServerInfo* pSrv = xsServerFind("demo");
if ( pSrv != NULL ) {
    /* use the topology info ... */
    xsServerRelease(pSrv);
}

xsServerRetain / xsServerRelease query

Extend a server lease / return the reference. Retain for the lifetime of a connection, and before storing anything beyond an enumeration callback.

XS_ServerInfo* xsServerRetain(XS_ServerInfo* pServer); void xsServerRelease(XS_ServerInfo* pServer);
Pairing: one Release per RetainPurpose: keep the topology alive across generation swaps

xsHostFind query

Find a host by name within a server; the result is jointly protected by the passed-in server lease (no separate release needed).

XS_HostInfo* xsHostFind(XS_ServerInfo* pServer, const char* sName);
Precondition: pServer is a lease you holdReturns: NULL = not found

xsEnumServers / xsEnumHosts query

Enumerate all servers / all hosts of a server. Parameters are borrowed for the callback only.

void xsEnumServers(XS_ServerEnumProc procEach, void* pUserData); void xsEnumHosts(XS_ServerInfo* pServer, XS_HostEnumProc procEach, void* pUserData);
Callback returns: false = stop enumeratingBorrowing: Retain before storing beyond the callback
Example
static bool PrintServer(XS_ServerInfo* pServer, void* pUserData)
{
    printf("server: %s (%s)\n", pServer->Name, pServer->Class);
    return true;   /* keep enumerating */
}
xsEnumServers(PrintServer, NULL);

xsConfigRoot query

Returns xs.json's top-level Custom (everything beyond the preset fields), for the application to read its custom knobs.

xvalue* xsConfigRoot(void);
Ownership: retained; needs xrtValueReleaseContents: root-level non-preset fields

Hot reload (7)

reload is a desired-state reconciliation task, not a synchronous command. The terminal-state machine: ACCEPTED → PREPARING → SUCCEEDED / FAILED / SUPERSEDED / CANCELLED; a new intent on the same server overrides unexecuted older ones; the pending cap is 64.

xsReloadHostSubmit reload

Submit a reload intent for one host (its owning server is the publishing unit).

XS_ReloadId xsReloadHostSubmit(XS_HostInfo* pHost);
Returns: 0 = not accepted; non-zero = stable IDSemantics: asynchronous; query with xsReloadQuery

xsReloadServerSubmit reload

Submit a reload intent for a whole server, by name.

XS_ReloadId xsReloadServerSubmit(const char* sName);
Returns: 0 = not accepted

xsReloadAllSubmit reload

A batch transaction: candidates of every server are precompiled; any failure rolls the whole thing back.

XS_ReloadId xsReloadAllSubmit(void);
Transactional: all or nothing

xsReloadQuery reload

Query an intent's terminal state; the result carries the content fingerprint Revision and the target description.

bool xsReloadQuery(XS_ReloadId iId, XS_ReloadResult* pResult);
XS_ReloadResult fieldNotes
Id / Statethe intent ID and one of the seven states
Revisioncontent fingerprint of the immutable input snapshot (includes the script fingerprint when there is no config input)
Target[160] / Message[256]target description and result message (the failure reason)
Example · the admin-route pattern
XS_ReloadId iId = xsReloadHostSubmit(pHost);
XS_ReloadResult tRes;
if ( iId != 0 && xsReloadQuery(iId, &tRes) )
    printf("reload #%llu: %d\n",
        (unsigned long long)tRes.Id, (int)tRes.State);

xsReloadHost / xsReloadServer / xsReloadAll reload

bool-compatible wrappers — they only report whether Submit returned non-zero; they do not wait for a terminal state.

bool xsReloadHost(XS_HostInfo* pHost); bool xsReloadServer(const char* sName); bool xsReloadAll(void);
Use: simple scenarios that don't track the outcome

Timers (2)

xsTimerAfter timer

A one-shot timer, bound to the owner's generation — a generation swap invalidates the old generation's timers; they never fire into the new one.

uint64 xsTimerAfter(XS_HostInfo* pOwner, uint32 iMillisecond, XS_TimerProc proc, void* pUserData);
Callback thread: engine threadReturns: 0 = failed; non-zero = timer ID
Example
static void OnTick(void* pUserData)
{
    printf("tick: %s\n", (const char*)pUserData);
}
/* inside ServiceInit: fire once after 5 s */
(void)xsTimerAfter(pHost, 5000, OnTick, "hello");

xsTimerCancel timer

Cancel a timer. IDs that already fired or were invalidated by a generation swap return false.

bool xsTimerCancel(uint64 iTimerId);
Returns: false = no longer exists

Deploy & nesting (3)

xsAppPath deploy

The application (executable) directory, UTF-8 — identical to the config directory; the anchor for resolving relative paths.

const char* xsAppPath(void);
Ownership: static borrow; no release needed

xsExtensionEnabled deploy

Runtime probe: is an optional library compiled into this variant, by registry name (= the build argument, matching the startup banner and --version). Case-insensitive; dependencies pulled in via requires are visible too; unknown names, empty strings and NULL return false without setting an error. The compile-time equivalent is #ifdef XS_USE_<name>.

bool xsExtensionEnabled(const char* sName);
Example
if ( xsExtensionEnabled("sqlite") ) {
    /* this host carries sqlite — use it directly */
    db_open(&db);
} /* not compiled in: take the alternate path */

xsExtensionCount / xsExtensionName deploy

Enumerate the extensions compiled into this variant: count returns the number, name returns the name by index (= the build argument, same data source as the startup banner and --version). The returned pointer borrows a static constant — valid for the process lifetime, no release needed; out-of-range indexes return NULL without setting an error. Under the default variant count is 0; every enumerated name fed to xsExtensionEnabled is true.

uint32 xsExtensionCount(void); const char* xsExtensionName(uint32 iIndex);
Example
for ( uint32 i = 0; i < xsExtensionCount(); i++ ) {
    printf("%u: %s
", i, xsExtensionName(i));
}

xsCreateTCC / xsDestroyTCC nesting

Create a nested compiler with the standard include/lib paths and symbol imports preset — the foundation of the application-level plugin system.

TCCState* xsCreateTCC(void); void xsDestroyTCC(TCCState* pTcc);
Presets: VFS SDK headers + the host symbol tableVariants: extension symbols are available too

State handover (1)

xsSwapTake handover

Valid only inside the new generation's ServiceInit: take the snapshot exported by the old generation's ServiceSwap. Returns NULL when there is no handover data.

xvalue* xsSwapTake(XS_HostInfo* pHost);
Window: only the new generation's ServiceInitOwnership: yours once taken; free with xrtValueRelease
Example · the contract pattern
static void ServiceInit(XS_HostInfo* pHost)
{
    xvalue* pState = xsSwapTake(pHost);
    if ( pState != NULL ) {
        G_iCounter = xrtValueInt64(
            xrtValueObjectGet(pState, "counter"));
        xrtValueRelease(pState);   /* taken: release it yourself */
    }
}