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
[db]Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
db | Reactors | Borrowed for the call | Required | The reactors owner for this operation. Keep it alive during the call. |
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
(with-open [sync-options (sd/parse "{maxWait {#dur PT5S}}" :dust)]
(sd/reactors-sync db sync-options))
(sd/reactors-status db)| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 4C 68656164 | txt "head" |
| 09 | 02 04000000000000 00 | i64 4 |
| 12 | 0F 0A 04000000 0900 0000 | map leaf, size 10: @4 → @9 |
| 1C | 6C 637572736F72 | txt "cursor" |
| 23 | 02 04000000000000 00 | i64 4 |
| 2C | 0F 0A 1C000000 2300 0000 | map leaf, size 10: @1C → @23 |
| 36 | 07 0E 04200000 1200 0000 2C000000 | map branch, size 14, depth 1, slots 2, 13: @12 → @2C |
| 44 | 7C 656E61626C6564 | txt "enabled" |
| 4C | 09 | bit true |
| 4D | 0F 0A 44000000 4C00 0000 | map leaf, size 10: @44 → @4C |
| 57 | 7C 70656E64696E67 | txt "pending" |
| 5F | 01 | bit false |
| 60 | 0F 0A 57000000 5F00 0000 | map leaf, size 10: @57 → @5F |
| 6A | 07 12 28020000 3600 0000 4D000000 6000 0000 | map branch, size 18, depth 0 (root), slots 3, 5, 9: @36 → @4D → @60 |
| 7C | 6A000000 00000000 | root → @6A; previous: none |
C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release
reactors-sync
[db][db options]Parameters
| Parameter | Type | Ownership | Default | Meaning |
|---|---|---|---|---|
db | Reactors | Borrowed for the call | Required | The reactors owner for this operation. Keep it alive during the call. |
options | Document | Borrowed for the call | Absent selects operation defaults | 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. |
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
(with-open [sync-options (sd/parse "{maxWait {#dur PT5S}}" :dust)]
(sd/reactors-sync db sync-options))
(sd/reactors-status db)| Offset (hex) | Bytes (hex) | Meaning |
|---|---|---|
| 00 | 54 52 4F 4E | magic TRON |
| 04 | 4C 68656164 | txt "head" |
| 09 | 02 04000000000000 00 | i64 4 |
| 12 | 0F 0A 04000000 0900 0000 | map leaf, size 10: @4 → @9 |
| 1C | 6C 637572736F72 | txt "cursor" |
| 23 | 02 04000000000000 00 | i64 4 |
| 2C | 0F 0A 1C000000 2300 0000 | map leaf, size 10: @1C → @23 |
| 36 | 07 0E 04200000 1200 0000 2C000000 | map branch, size 14, depth 1, slots 2, 13: @12 → @2C |
| 44 | 7C 656E61626C6564 | txt "enabled" |
| 4C | 09 | bit true |
| 4D | 0F 0A 44000000 4C00 0000 | map leaf, size 10: @44 → @4C |
| 57 | 7C 70656E64696E67 | txt "pending" |
| 5F | 01 | bit false |
| 60 | 0F 0A 57000000 5F00 0000 | map leaf, size 10: @57 → @5F |
| 6A | 07 12 28020000 3600 0000 4D000000 6000 0000 | map branch, size 18, depth 0 (root), slots 3, 5, 9: @36 → @4D → @60 |
| 7C | 6A000000 00000000 | root → @6A; previous: none |
C exports: stardust_db_plugin_call, stardust_result_take_document, stardust_result_error, stardust_result_release