Reactors
The reactors plugin runs live mutations.
A live mutation is a stored mutation definition with live true and an optional integer priority.
Enable it at open with plugins {reactors {}}. It has no settings.
See plugin selection for the open options.
Store live mutations with patch_definition under the mutations kind.
After each commit, every live mutation evaluates its query as of that transaction.
Their patches commit together as one output transaction, completing a round.
When patches write different values to one path, the higher priority wins.
Equal priorities fail with Reactor_Conflict.
The combined patch must satisfy the scoped schemas of every contributing live mutation.
A schema rejection records Schema_Validation and commits no output.
A failure keeps the cursor before its source transaction until a live mutation definition changes.
Runtime status
Call status to inspect these fields:
| Field | Contents |
|---|---|
enabled | Whether the plugin is enabled |
cursor | Last processed source transaction |
head | Current database head |
pending | Whether processing remains |
reactors | Live mutations, each with id, name, priority and sinceTx |
failure | Current failure, with sourceTx, code, reactors and path; absent when no failure stands |
When to call sync
Live mutations run automatically after commits. Your write can finish before a live mutation has produced its output.
Call sync before a read that depends on that output.
For example, a live mutation can add greeted after a person is created.
A read immediately after creation can miss greeted. Synchronize the reactors before asserting that result in a test.
Applications that can observe the output later can let the runtime continue in the background.
Its options accept only the common maxWait option. Success covers source transactions committed before the call.
Later transactions can still have pending rounds. A failed round reports failed and appears in status.
Operations
| Operation | Returns | Summary |
|---|---|---|
| reactors_status | document | reactors.status() returns the reactor runtime's owned status document. |
| reactors_sync | none | reactors.sync(options) waits until live mutations processed the commits made before the call. |
reactors_status
reactors_status :: proc(
db: Database,
allocator := context.allocator,
) -> (
Document,
Error,
)Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
db | Database | Borrowed for the call | Required | The reactors owner for this operation. Keep it alive during the call. |
allocator | mem.Allocator | Value | context.allocator | Allocator for copied return values and diagnostics. The caller releases them with the same allocator. |
Errors
| Status | When |
|---|---|
.Unavailable | the database does not enable the reactors plugin |
.Closed | the database is closed |
.Out_Of_Memory | native memory is exhausted |
Notes
The document describes the cursor, pending work, live mutations and failures: see runtime status.
Examples
Describe the live mutation runtime
sync_options := stardust.parse(`{maxWait {#dur PT5S}}`, .DUST) or_return
defer stardust.close(&sync_options)
stardust.reactors_sync(db, sync_options) or_return
result := stardust.reactors_status(db) or_return
defer stardust.close(&result){
"enabled": true,
"cursor": 4,
"head": 4,
"pending": false
}C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release
reactors_sync
reactors_sync :: proc(
db: Database,
options: Document = {},
allocator := context.allocator,
) -> ErrorParameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
db | Database | Borrowed for the call | Required | The reactors owner for this operation. Keep it alive during the call. |
options | Document | Borrowed for the call | {} | The borrowed call options, or none. Optional maxWait is a nonnegative native duration, such as {maxWait {#dur PT5S}}. Without it, or with zero, the call checks once. |
allocator | mem.Allocator | Value | context.allocator | Allocator for copied return values and diagnostics. The caller releases them with the same allocator. |
Errors
| Status | When |
|---|---|
.Invalid_Argument | options is not an object, or an option is invalid, duplicated or unsupported |
.Failed | the plugin's work failed; status describes the failure |
.Timeout | maxWait passed before the work finished |
.Unavailable | the database does not enable the reactors plugin |
.Closed | the database is closed |
Notes
Database close interrupts an active wait. See when to call sync.
Examples
Wait until live mutations caught up
sync_options := stardust.parse(`{maxWait {#dur PT5S}}`, .DUST) or_return
defer stardust.close(&sync_options)
stardust.reactors_sync(db, sync_options) or_return
result := stardust.reactors_status(db) or_return
defer stardust.close(&result){
"enabled": true,
"cursor": 4,
"head": 4,
"pending": false
}C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release