Host loop and resource management
One map, one owner thread
Create the map on the thread that will drive it over its lifetime, and perform map operations there. This may be the window thread or a dedicated thread. Route input, resize, resource responses, and destruction to that owner.
Downloads may run elsewhere, but their results must return to the owner before calling map APIs. Output allocations can be read and released across threads with proper synchronization; map handles do not thereby become freely transferable between threads.
Responsibilities of the host loop
- Process host input and completed downloads, serializing map operations on the owner.
- Poll events, copy or parse the required information, and release the output. Distinguish creation, subsequent changes, and resource-loading states.
- Obtain pending resource requests and submit them to your downloader and cache. Preserve identities and generations, and enforce timeouts, cancellation, and size limits.
- Return successful or failed downloads on the owner and check whether the response was accepted. A late response after a style change or map destruction is not a current request.
- Read frames according to the host's refresh schedule, send pixels to the display layer, and release each output.
Successful validation, applied commands, and completed network loading are different states. A successful API return does not mean that all data has loaded. See Lifecycle and native resource loading.
Memory rules
| Object | Host responsibility |
|---|---|
sqsm_map_bytes_t.data | Read only while its allocation remains alive; parse JSON using len UTF-8 bytes, without assuming a terminating zero |
sqsm_map_bytes_t.allocation | Release exactly once using sqsm_map_bytes_free; do not call C free on data |
| The next output argument | Use a zeroed structure or one whose allocation was already released; do not overwrite a live allocation |
sqsm_map_last_error() | Copy or log before the next map API call; the library owns the pointer, so do not release it |
| Map handle | Stop using it after destruction; destroying a map does not release independent outputs already returned to the host |
Copying pixels is often easier to manage for an asynchronous display layer. If you transfer an allocation between threads, assign release ownership and ensure all readers finish before release.
Events and errors
Use sqsm_map_poll_events_json to obtain an event array and release the result, including an empty array. The bounded queue must be drained; otherwise later changes can return a resource-limit status. Retrying changes does not drain events.
| Status | Check first |
|---|---|
SQSM_MAP_CONFLICT | The owner thread and any current operation-state constraints |
SQSM_MAP_STALE_HANDLE | Whether the map or allocation was already destroyed or released |
SQSM_MAP_RESOURCE_LIMIT | Unconsumed events, unreleased outputs, and request budgets |
SQSM_MAP_CAPABILITY_UNAVAILABLE | Runtime capability flags, optional modules, and matching versions |
SQSM_MAP_ENGINE_ERROR | Log the thread-local error immediately and investigate initialization or rendering conditions |
On shutdown, stop submitting new host tasks, destroy the map on its owner, and release remaining host-held allocations. When persistent script sessions are enabled, also follow the native script module rules for stopping, retaining terminal state, and releasing sessions. Dropping a host reference alone does not terminate a session.