tur/errors
stdlib/errors.tur
defstruct
ScscmResult<T>
(defstruct ScscmResult<T> [])
defn
ok
(ok [value])
Create a successful result wrapping a value.
Parameters
| value | The success value to wrap. |
Example
ScscmResult with ok=true and the given value.
(ok 42) ; => {:ok true :value 42 :error :ok}
defn
err
(err [error])
Create a failed result with an error tag.
Parameters
| error | A ScscmError keyword describing the failure. |
Example
ScscmResult with ok=false and no value.
(err :send-failed) ; => {:ok false :value nil :error :send-failed}
defn
result-ok?
(result-ok? [result])
Check whether a result represents success.
Parameters
| result | A ScscmResult map. |
Example
true if the result is successful, false otherwise. (result-ok? (ok 1)) ; => true
defn
result-err?
(result-err? [result])
Check whether a result represents an error.
Parameters
| result | A ScscmResult map. |
Example
true if the result is an error, false otherwise. (result-err? (err :timeout)) ; => true
defn
result-unwrap
(result-unwrap [result])
Extract the value from a result, panicking on error.
Parameters
| result | A ScscmResult map. |
Example
The wrapped value if ok, otherwise panics with the error tag. (result-unwrap (ok 7)) ; => 7
defn
result-unwrap-or
(result-unwrap-or [result default])
Extract the value from a result, returning a default on error.
Parameters
| result | A ScscmResult map. | |
| default | Value to return when the result is an error. |
Example
The wrapped value if ok, otherwise default. (result-unwrap-or (err :timeout) 0) ; => 0
defn
safe-world-create
(safe-world-create [sample_rate block_size])
Create a hcsynth world with error handling.
Parameters
| sample_rate | Sample rate in Hz. | |
| block_size | Block size in samples. |
Example
ScscmResult wrapping the WorldHandle on success, or :connection-failed.
(safe-world-create 48000 512) ; => {:ok true :value <handle> ...}
defn
safe-synth-new
(safe-synth-new [world_id synthdef_name node_id action target_id])
Create a synth node with error handling.
Parameters
| world_id | Target world handle. | |
| synthdef_name | SynthDef name to instantiate. | |
| node_id | Node ID to assign. | |
| action | Add action (e.g. ADD_TO_TAIL). | |
| target_id | Target node ID. |
Example
ScscmResult wrapping the NodeID on success, or an error keyword. (safe-synth-new w "mySynth" 1001 2 1)
defn
safe-synth-set
(safe-synth-set [world_id node_id control_index value])
Set a synth control parameter with error handling.
Parameters
| world_id | Target world handle. | |
| node_id | Target node ID. | |
| control_index | Zero-based control index. | |
| value | Value to set. |
Example
ScscmResult wrapping nil on success, or :control-index-out-of-range. (safe-synth-set w 1001 0 440.0)
defn
safe-synth-free
(safe-synth-free [world_id node_id])
Free a synth node with error handling.
Parameters
| world_id | Target world handle. | |
| node_id | Node ID to free. |
Example
ScscmResult wrapping nil on success, or :synth-not-found. (safe-synth-free w 1001)
defn
safe-synthdef-load
(safe-synthdef-load [world_id synthdef_data & [synthdef_name nil])
Load a SynthDef from binary data with error handling.
Parameters
| world_id | Target world handle. | |
| synthdef_data | SynthDef bytecode as slice<uint8>. | |
| synthdef_name | Optional name override; nil uses the embedded name. |
Example
ScscmResult wrapping nil on success, or :invalid-synthdef. (safe-synthdef-load w my-bytes "mySynth")
defn
safe-world-destroy
(safe-world-destroy [world_id])
Destroy a hcsynth world with error handling.
Parameters
| world_id | World handle to destroy. |
Example
ScscmResult wrapping nil on success, or :world-not-found. (safe-world-destroy w)
defstruct
ConnectionMonitor
(defstruct ConnectionMonitor [])
defn
connection-monitor-new
(connection-monitor-new [world_id & [ping-interval-seconds 5 max-failures 3 on-reconnect (fn [])
Create a connection health monitor for a world.
Parameters
| world_id | World handle to monitor. | |
| ping-interval-seconds | How often to ping, in seconds (default: 5). | |
| max-failures | Max consecutive failures before triggering reconnect (default: 3). | |
| on-reconnect | Callback invoked when a reconnect is attempted. |
Example
A ConnectionMonitor map. (connection-monitor-new w 5 3 (fn [] (println "reconnecting")))
defn
check-connection
(check-connection [monitor current-samples])
Poll connection health and trigger reconnect when needed.
Parameters
| monitor | A ConnectionMonitor map. | |
| current-samples | Current time in samples. |
Example
true if the connection appears healthy. (check-connection mon (now-samples state))
defn
reconnect
(reconnect [monitor])
Attempt to reconnect by invoking the monitor's callback.
Parameters
| monitor | A ConnectionMonitor map. |
defn
connection-monitor-reset
(connection-monitor-reset [monitor])
Reset ping time and failure count on a monitor.
Parameters
| monitor | A ConnectionMonitor map. |
defstruct
NodeIDPool
(defstruct NodeIDPool [])
defn
node-id-pool-new
(node-id-pool-new [& [start types/DEFAULT_NODE_ID_START])
Create a node ID pool starting at a given ID.
Parameters
| start | First node ID to allocate (default: DEFAULT_NODE_ID_START). |
Example
A NodeIDPool map. (node-id-pool-new 1000)
defn
node-id-pool-alloc
(node-id-pool-alloc [pool])
Allocate a node ID, reusing freed IDs when available.
Parameters
| pool | A NodeIDPool map. |
Example
An integer node ID unique within this pool. (node-id-pool-alloc pool) ; => 1000
defn
node-id-pool-free
(node-id-pool-free [pool id])
Return a node ID to the pool for later reuse.
Parameters
| pool | A NodeIDPool map. | |
| id | Node ID to release. |
Example
(node-id-pool-free pool 1003)
defn
retry-with-backoff
(retry-with-backoff [fn & [max-attempts 3 initial-delay 512 max-delay 5120])
Retry a thunk with exponential backoff on failure.
Parameters
| fn | Zero-argument function that returns a ScscmResult. | |
| max-attempts | Maximum number of attempts (default: 3). | |
| initial-delay | Initial delay in samples (default: 512). | |
| max-delay | Maximum delay cap in samples (default: 5120). |
Example
The first successful ScscmResult, or an error result after all attempts. (retry-with-backoff (fn [] (safe-synth-new ...)) 3)
defn
valid-world-id?
(valid-world-id? [world_id])
Return true if world_id is a valid non-zero handle.
Parameters
| world_id | Candidate world handle. |
Returns
true if valid, false otherwise.
defn
valid-node-id?
(valid-node-id? [node_id])
Return true if node_id is a valid non-zero node ID.
Parameters
| node_id | Candidate node ID. |
Returns
true if valid, false otherwise.
defn
valid-control-index?
(valid-control-index? [index num-controls])
Return true if a control index is within range.
Parameters
| index | Zero-based control index to check. | |
| num-controls | Total number of controls on the synth. |
Returns
true if 0 <= index < num-controls.
defn
valid-synthdef-name?
(valid-synthdef-name? [name])
Return true if a SynthDef name is non-nil and non-empty.
Parameters
| name | Candidate SynthDef name string. |
Returns
true if the name can be used for lookup, false otherwise.
defn
safe-session-new
(safe-session-new [sample_rate block_size])
Create a session with error handling.
Parameters
| sample_rate | Audio sample rate in Hz. | |
| block_size | Audio block size in samples. |
Example
ScscmResult wrapping a new ScscmSession map on success. (safe-session-new 48000 512)
defn
safe-session-synth-new
(safe-session-synth-new [session synthdef_name & [params {}])
Create a synth inside a session with error handling.
Parameters
| session | An active ScscmSession map. | |
| synthdef_name | Name of the SynthDef to instantiate. | |
| params | Optional initial parameter map (control_index -> value). |
Example
ScscmResult wrapping the new NodeID on success.
(safe-session-synth-new sess "mySynth" {0 440.0})
defn
safe-session-synth-free
(safe-session-synth-free [session node_id])
Free a synth inside a session with error handling.
Parameters
| session | An active ScscmSession map. | |
| node_id | Node ID to free. |
Example
ScscmResult wrapping nil on success, or an error keyword. (safe-session-synth-free sess 1001)