2.3 BackendFactory and BackendType

BackendFactory and BackendType

Relevant source files

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

• src/trait_def.rs

This page describes the factory pattern used in corpus-ipc to abstract the instantiation of compute processing engines. It details the BackendType enumeration, the use of conditional compilation for the ZeroMQ transport, and how the BackendFactory enables runtime selection of backend implementations. This reflects the completed rename conventions per CHANGELOG guidelines src/trait_def.rs:10-12.

---

Overview of the Factory Pattern

The corpus-ipc library uses a factory pattern to decouple application logic from specific backend implementations src/trait_def.rs:16-23. This allows the system to switch between a native Rust environment and an external process (via ZeroMQ) without altering the calling code's signature src/trait_def.rs:17-23.

The factory returns a Box<dyn IpcBackend>, ensuring that callers interact exclusively through the unified trait interface src/trait_def.rs:119.

System Component Mapping

The following diagram bridges the high-level concepts of backend selection to the specific code entities responsible for implementation.

Backend Selection Logic

graph TD
    subgraph "Natural Language Space"
        A["Selection Logic"]
        B["Native Engine"]
        C["External Engine"]
    end

    subgraph "Code Entity Space"
        direction LR
        A1["BackendType"]
        B1["RustBackend"]
        C1["ZmqIpcBackend"]
        F1["BackendFactory::create"]
    end

    A --> A1
    B --> B1
    C --> C1
    
    A1 --> F1
    F1 -- "instantiates" --> B1
    F1 -- "instantiates" --> C1

Loading

Sources: src/trait_def.rs:29-55, src/trait_def.rs:90-127

---

The BackendType Enum and Deprecated Aliases

The BackendType enum serves as the discriminator for the factory src/trait_def.rs:90-106. It determines which concrete struct will be instantiated and boxed src/trait_def.rs:119-126.

Variant	Description	Feature Requirement
Rust	Pure-Rust native backend (default) src/trait_def.rs:96-98.	Always available
ZmqIpc	IPC backend via ZMQ SUB socket src/trait_def.rs:99-101.	feature = "zmq"
ZmqRuntime	Deprecated compatibility selector for ZmqIpc src/trait_def.rs:102-105.	feature = "zmq"

Sources: src/trait_def.rs:90-106

---

Conditional Compilation with cfg(feature = "zmq")

The ZmqIpc variant and the ZmqRuntime alias are gated behind the zmq feature flag src/trait_def.rs:99-106. This minimizes the dependency tree for users who only require the native RustBackend.

• In BackendType definition: Variants involving ZeroMQ are conditionally compiled using #[cfg(feature = "zmq")] src/trait_def.rs:99-106.
• In BackendFactory::create: The match arms handling ZeroMQ backends are similarly guarded, preventing compilation errors when the zmq feature is omitted src/trait_def.rs:122-125.

Sources: src/trait_def.rs:99-106, src/trait_def.rs:122-125

---

BackendFactory Implementation

The BackendFactory is a unit struct providing a static create method src/trait_def.rs:108-119. It maps the BackendType enum to the construction of concrete types such as RustBackend and ZmqIpcBackend src/trait_def.rs:120-126.

Data Flow: Runtime Selection

The sequence diagram below illustrates how a BackendType is transformed into a trait object for downstream processing.

Backend Instantiation Flow

sequenceDiagram
    participant App as "Caller"
    participant BF as "BackendFactory"
    participant RB as "RustBackend"
    participant ZB as "ZmqIpcBackend"

    App->>BF: "create(BackendType::Rust)"
    BF->>RB: "new()"
    RB-->>BF: "Instance"
    BF-->>App: "Box<dyn IpcBackend>"

    Note over App, ZB: If feature "zmq" is enabled
    App->>BF: "create(BackendType::ZmqIpc)"
    BF->>ZB: "new()"
    ZB-->>BF: "Instance"
    BF-->>App: "Box<dyn IpcBackend>"

Loading

Key Functions

• BackendFactory::create(backend_type: BackendType) -> Box<dyn IpcBackend>:
  • Accepts a BackendType discriminator src/trait_def.rs:119.
  • Matches on the variant to instantiate the underlying engine src/trait_def.rs:120-125.
  • Returns a heap-allocated trait object wrapped in a Box src/trait_def.rs:119.

Sources: src/trait_def.rs:108-127

---

Trait Requirements and Testing

Backends produced by BackendFactory must implement IpcBackend, which enforces thread safety via Send + Sync bounds src/trait_def.rs:29. This is critical for integration into asynchronous runtimes like tokio or shared concurrent state contexts.

Unit tests within src/trait_def.rs validate factory correctness and trait conformance src/trait_def.rs:129-164:

• rust_backend_implements_ipc_backend checks that RustBackend satisfies IpcBackend src/trait_def.rs:136-142.
• zmq_backend_implements_ipc_backend (when zmq feature is active) verifies ZmqIpcBackend conformance src/trait_def.rs:151-156.
• Deprecation aliases (ZmqRuntime, RuntimeBackend) are explicitly tested for backward compatibility src/trait_def.rs:144-149, src/trait_def.rs:158-163.

Sources: src/trait_def.rs:29-55, src/trait_def.rs:129-164