2.1 IpcBackend Trait

IpcBackend Trait

Relevant source files

The following files were used as context for generating this wiki page:

• src/trait_def.rs

The IpcBackend trait defined in [src/trait_def.rs:29-55]() serves as the primary abstraction layer in corpus-ipc. It decouples application execution logic from concrete compute engines, enabling seamless interchangeability between native Rust implementations and external IPC-driven backends.

Trait Definition and Concurrency Requirements

Every backend implementation must conform to the IpcBackend trait contract and satisfy Send + Sync requirements [[src/trait_def.rs:29]()]. This ensures that backend instances can be transferred across thread boundaries and accessed concurrently—typically encapsulated behind a mutex. The REST server uses AppState (Mutex<Box<dyn IpcBackend>> plus an AtomicBool initialized flag) in src/server.rs.

pub trait IpcBackend: Send + Sync {
    fn process_batch(&mut self, inputs: &[f32]) -> Result<Vec<f32>, BackendError>;
    fn initialize(&mut self, model_path: Option<&str>) -> Result<(), BackendError>;
    fn save_state(&self, model_path: &str) -> Result<(), BackendError>;
    fn get_spike_states(&self) -> Vec<bool>;
    fn reset(&mut self) -> Result<(), BackendError>;
}

Sources: [[src/trait_def.rs:29-55]()]

---

Method Reference

initialize

• Signature: fn initialize(&mut self, model_path: Option<&str>) -> Result<(), BackendError> [[src/trait_def.rs:39]()]
• Purpose: Prepares the backend for processing by loading model weights, initializing internal buffers, or establishing IPC transport socket connections [[src/trait_def.rs:36-38]()].
• Contract: Must be called before process_batch. Successful executions are idempotent [[src/trait_def.rs:38()].

process_batch

• Signature: fn process_batch(&mut self, inputs: &[f32]) -> Result<Vec<f32>, BackendError> [[src/trait_def.rs:34]()]
• Purpose: Executes a forward processing pass over a dynamic slice of f32 input signals [[src/trait_def.rs:31-34]()].
• Output Contract: Returns a Vec<f32> containing the processed outputs, where the dimensionality depends on the specific concrete backend implementation [[src/trait_def.rs:25-28]()].

save_state

• Signature: fn save_state(&self, model_path: &str) -> Result<(), BackendError> [[src/trait_def.rs:42]()]
• Purpose: Persists the current model state or weights to the designated file path [[src/trait_def.rs:41]()].

get_spike_states

• Signature: fn get_spike_states(&self) -> Vec<bool> [[src/trait_def.rs:45]()]
• Purpose: Retrieves a vector of boolean flags representing per-channel spike states (where true indicates a spike occurred on the most recent evaluation tick) [[src/trait_def.rs:44-45]()].

reset

• Signature: fn reset(&mut self) -> Result<(), BackendError> [[src/trait_def.rs:54]()]
• Purpose: Resets internal volatile state, such as membrane potentials and temporal caches [[src/trait_def.rs:47-48]()].
• Transport Behavior: For connection-oriented backends like ZmqIpcBackend, reset() may drop the underlying transport socket and clear initialization flags, requiring a subsequent initialize() call before future process_batch() calls [[src/trait_def.rs:49-53]()].

Sources: [[src/trait_def.rs:29-55]()]

---

Lifecycle Contract and State Transitions

The lifecycle of an IpcBackend transitions through uninitialized, initialized, processing, and reset states as depicted below.

IpcBackend Lifecycle State Machine

stateDiagram-v2
    direction TB
    Uninitialized["Uninitialized"]
    Initialized["Initialized"]
    Processing["Processing"]
    Resetting["Resetting"]
    Saving["Saving"]
    ErrorState["Error"]

    Uninitialized --> Initialized : "initialize(model_path)"
    Initialized --> Processing : "process_batch(inputs)"
    Processing --> Initialized : "Ok(Vec<f32>)"
    Initialized --> Resetting : "reset()"
    Resetting --> Initialized : "State Cleared"
    Initialized --> Saving : "save_state(model_path)"
    Saving --> Initialized : "IO Complete"
    Uninitialized --> ErrorState : "process_batch without init"
    ErrorState --> [*]

Loading

Sources: [[src/trait_def.rs:29-55]()]

---

Compile-Time Conformance Assertions and Deprecated Aliases

To guarantee that all concrete backends adhere to the trait requirements, unit test suites employ compile-time type assertions using helper functions [[src/trait_def.rs:134-156]()]:

fn assert_ipc_backend<T: IpcBackend>() {}

Furthermore, the codebase preserves the RuntimeBackend alias for backward compatibility following rename refactors. Marked as deprecated, it maps directly to IpcBackend [[src/trait_def.rs:57-63]()]:

#[deprecated(since = "0.1.0", note = "renamed to IpcBackend")]
pub use IpcBackend as RuntimeBackend;

Sources: [[src/trait_def.rs:57-63](), [src/trait_def.rs:129-164]()]

---

Code Entity Mappings

This mapping bridges high-level architectural concepts to the concrete Rust code symbols defined in the codebase.

Natural Language Concept	Code Symbol / Entity	File Reference
Compute Backend Trait	trait IpcBackend	[[src/trait_def.rs:29]()]
Deprecated Alias	type RuntimeBackend	[[src/trait_def.rs:63]()]
Native Implementation	struct RustBackend	[[src/trait_def.rs:14]()]
ZMQ IPC Implementation	struct ZmqIpcBackend	[[src/trait_def.rs:124]()]
Factory Selector	enum BackendType	[[src/trait_def.rs:95]()]
Backend Instantiator	struct BackendFactory	[[src/trait_def.rs:109]()]

Trait-to-Implementation Architecture

classDiagram
    class IpcBackend {
        <<trait>>
        +process_batch(inputs)
        +initialize(model_path)
        +save_state(model_path)
        +get_spike_states()
        +reset()
    }

    class RuntimeBackend {
        <<deprecated alias>>
    }

    class RustBackend {
        +new()
        +process_batch(inputs)
    }

    class ZmqIpcBackend {
        +new()
        +process_batch(inputs)
    }

    class BackendFactory {
        +create(backend_type) Box<dyn IpcBackend>
    }

    class BackendType {
        <<enumeration>>
        Rust
        ZmqIpc
        ZmqRuntime
    }

    IpcBackend <|.. RustBackend : "implements"
    IpcBackend <|.. ZmqIpcBackend : "implements"
    BackendFactory ..> IpcBackend : "returns trait object"
    BackendFactory ..> BackendType : "accepts"
    RuntimeBackend ..> IpcBackend : "alias"

Loading

Sources: [[src/trait_def.rs:29-127]()]