Skip to main content

CScriptInstance

Struct CScriptInstance 

Source
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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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”).

Source

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.

Source

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.

Source

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).

Source

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

Source§

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)

Performs copy-assignment from source. Read more
Source§

impl Debug for CScriptInstance

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Drop for CScriptInstance

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more
Source§

impl Send for CScriptInstance

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.