pub struct CScriptInstance { /* private fields */ }Expand description
One block instance’s own state, from one call to cscript_start() on a shared
CScriptLibrary. Drop calls cscript_free if the library exported one.
Implementations§
Source§impl CScriptInstance
impl CScriptInstance
Sourcepub fn call(&mut self, input: &[f64], dt: f64, out_len: usize) -> Vec<f64>
pub fn call(&mut self, input: &[f64], dt: f64, out_len: usize) -> Vec<f64>
Calls cscript_output with this instance’s own state, input and dt as given, and
an out_len-length zero-initialized output buffer, returning it filled in.
§Panics
If this instance’s library doesn’t export cscript_output — unreachable in practice,
since CScriptRegistry::instantiate (the only way to obtain an instance meant to use
this method) already requires it up front, the same “checked once, up front” discipline
Clone’s own cscript_clone requirement uses.
Sourcepub fn call_xc(
&mut self,
input: &[f64],
dt: f64,
xc: &[f64],
out_len: usize,
) -> Vec<f64>
pub fn call_xc( &mut self, input: &[f64], dt: f64, xc: &[f64], out_len: usize, ) -> Vec<f64>
Calls cscript_output_xc with this instance’s own state, input/dt as given, xc as
this step’s own already-integrated continuous-state vector, and an out_len-length
zero-initialized output buffer, returning it filled in — the xc-owning counterpart to
Self::call. See the module doc comment, “The optional continuous-state (xc)
contract.”
§Panics
If this instance’s library doesn’t export cscript_output_xc — unreachable in
practice, since CScriptRegistry::instantiate_xc already requires it up front.
Sourcepub fn update(&mut self, input: &[f64], dt: f64, xc: &[f64])
pub fn update(&mut self, input: &[f64], dt: f64, xc: &[f64])
Calls cscript_update with this instance’s own state, input/dt/xc as given – a
no-op if this instance’s library didn’t export it (see the module doc comment, “The
optional discrete-state update function”). Unlike Self::call/Self::call_xc, this
is genuinely optional for both contracts, so there’s no panic path: call it every
step it’s due exactly like output, and it simply does nothing if the author never wrote
one.
Sourcepub fn supports_next_sample_hit(&self) -> bool
pub fn supports_next_sample_hit(&self) -> bool
Whether this instance’s library exported cscript_next_sample_hit — check this once, up
front, when this block’s netlist line declares ts=variable (see the module doc
comment, “The optional block-controlled sample time”) and reject the netlist with a
clear error if not, before ever calling Self::next_sample_hit.
Sourcepub fn declared_arity(&self) -> Option<DeclaredArity>
pub fn declared_arity(&self) -> Option<DeclaredArity>
What this library declares its own arity to be, if it declares one.
None when cscript_arity is absent, or present and returns non-zero — a library may
decline, and declining is not an error. Some carries each side separately, because a
negative value means “not declaring this one”.
This crate only asks the question. Comparing the answer against a netlist’s declared
port counts is dae-runtime’s, since nothing here knows what a netlist is.
Sourcepub fn next_sample_hit(&self, input: &[f64], xc: &[f64]) -> f64
pub fn next_sample_hit(&self, input: &[f64], xc: &[f64]) -> f64
Calls cscript_next_sample_hit, returning the number of seconds (relative to this call)
until this block should next be executed.
§Panics
If this instance’s library doesn’t export cscript_next_sample_hit — unreachable in
practice, since a caller is expected to check Self::supports_next_sample_hit once,
up front, before ever using ts=variable for this block at all.
Sourcepub fn derivative(&self, input: &[f64], xc: &[f64]) -> Vec<f64>
pub fn derivative(&self, input: &[f64], xc: &[f64]) -> Vec<f64>
Evaluates cscript_derivative once: given this step’s already-resolved inputs and a
candidate continuous-state vector xc, returns dxc/dt. Takes &self rather than
&mut self — the C-side contract documents (but, like every other rule in this crate,
cannot enforce) that this call must not mutate state, so the Rust type keeps that
intent honest even though the raw pointer underneath is technically mutable.
§Panics
If this instance’s library doesn’t export cscript_derivative — unreachable in
practice, since CScriptRegistry::instantiate_xc already requires it up front.
Sourcepub fn rk4_step_xc(&self, xc: &[f64], input: &[f64], dt: f64) -> Vec<f64>
pub fn rk4_step_xc(&self, xc: &[f64], input: &[f64], dt: f64) -> Vec<f64>
RK4-integrates xc forward by dt, holding input fixed across all four stages — the
same zero-order-hold convention continuous_blocks::StateSpace::rk4_step uses for every
other dynamic block in this workspace, so a cscript block’s own continuous state
integrates exactly like a Pid/StateSpace/Pmsm’s does, not by some separate rule.
Calls Self::derivative up to four times (k1..k4) — see that method’s own #Panics.
Sourcepub fn supports_clone(&self) -> bool
pub fn supports_clone(&self) -> bool
Whether this instance’s library exported cscript_clone — check this once, up front,
before deciding whether a netlist using this block is eligible for adaptive step-size
control (see the module doc comment, “Adaptive step-size control and instance cloning”).
Sourcepub fn try_clone(&self) -> Option<CScriptInstance>
pub fn try_clone(&self) -> Option<CScriptInstance>
A real, independent deep copy of this instance’s state via cscript_clone, or None
if the library didn’t export it. Prefer this over Clone::clone wherever a missing
cscript_clone should be handled as an ordinary error rather than a panic.
Sourcepub fn supports_state_io(&self) -> bool
pub fn supports_state_io(&self) -> bool
Whether this instance’s library exported the
cscript_state_size/cscript_state_write/cscript_state_read triple — check this once,
up front, before deciding whether a run containing this block can be checkpointed (see
the module doc comment, “The optional checkpoint state contract”). A library exporting
none of the three is the “no” case; a partial set never loads at all.
Sourcepub fn state_bytes(&self) -> Result<Vec<u8>, CScriptError>
pub fn state_bytes(&self) -> Result<Vec<u8>, CScriptError>
This instance’s opaque state, serialized by the library’s own cscript_state_write into
exactly cscript_state_size bytes — the save half of the checkpoint state contract.
Empty for a state the library reports as zero-sized (a NULL state, typically).
Sourcepub fn restore_state(&mut self, bytes: &[u8]) -> Result<(), CScriptError>
pub fn restore_state(&mut self, bytes: &[u8]) -> Result<(), CScriptError>
Replaces this instance’s state with one rebuilt by the library’s own cscript_state_read
from bytes (as produced by Self::state_bytes, possibly in another process) — the
load half of the checkpoint state contract. The previous state is released through
cscript_free if the library exported it, exactly as on drop.
Trait Implementations§
Source§impl Clone for CScriptInstance
impl Clone for CScriptInstance
Source§fn clone(&self) -> Self
fn clone(&self) -> Self
§Panics
If this instance’s library didn’t export cscript_clone. See the module doc comment,
“Adaptive step-size control and instance cloning” — callers that need to handle this
without panicking should check CScriptInstance::supports_clone first, or use
CScriptInstance::try_clone directly.
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more