Struct CoreHandle

Source

pub struct CoreHandle { /* private fields */ }

Expand description

Handle to a core’s reactor thread.

Provides lock-free communication with the core via SPSC queues and credit-based flow control for backpressure.

Implementations§

Source §

impl CoreHandle

Source

pub fn spawn(config: CoreConfig) -> Result<Self, TpcError>

Spawns a new core thread with the given configuration.

§Errors

Returns an error if the thread cannot be spawned.

Source

pub fn spawn_with_operators( config: CoreConfig, operators: Vec<Box<dyn Operator>>, ) -> Result<Self, TpcError>

Spawns a new core thread with operators.

§Errors

Returns an error if the thread cannot be spawned.

Source

pub fn core_id(&self) -> usize

Returns the core ID.

Source

pub fn numa_node(&self) -> usize

Returns the NUMA node for this core.

Source

pub fn is_running(&self) -> bool

Returns true if the core thread is running.

Source

pub fn events_processed(&self) -> u64

Returns the number of events processed by this core.

Source

pub fn outputs_dropped(&self) -> u64

Returns the number of outputs dropped due to a full outbox.

Source

pub fn send(&self, message: CoreMessage) -> Result<(), TpcError>

Sends a message to the core with credit-based flow control.

This method respects the backpressure configuration:

Block: Spins until credits available, then sends
Drop: Returns Ok but drops the message if no credits
Error: Returns error if no credits available

§Errors

Returns an error if the inbox queue is full or credits exhausted (with Error strategy).

Source

pub fn try_send(&self, message: CoreMessage) -> Result<(), TpcError>

Tries to send a message without blocking.

Returns Err if no credits available or queue is full. Does not block regardless of overflow strategy.

§Errors

Returns an error if credits exhausted or queue full.

Source

pub fn send_event(&self, event: Event) -> Result<(), TpcError>

Sends an event to the core with credit-based flow control.

§Errors

Returns an error if the inbox queue is full or backpressure applies.

Source

pub fn try_send_event(&self, event: Event) -> Result<(), TpcError>

Tries to send an event without blocking.

§Errors

Returns an error if credits exhausted or queue full.

Source

pub fn poll_outputs(&self, max_count: usize) -> Vec<Output>

Polls the outbox for outputs.

Returns up to max_count outputs.

§Note

This method allocates memory. For zero-allocation polling, use poll_outputs_into or poll_each instead.

Source

pub fn poll_outputs_into( &self, buffer: &mut Vec<Output>, max_count: usize, ) -> usize

Polls the outbox for outputs into a pre-allocated buffer (zero-allocation).

Outputs are appended to buffer. Returns the number of outputs added. The buffer should have sufficient capacity to avoid reallocation.

§Example

let mut buffer = Vec::with_capacity(1024);

// First poll - fills buffer
let count1 = core_handle.poll_outputs_into(&mut buffer, 100);

// Process outputs...
for output in &buffer[..count1] {
    process(output);
}

// Clear and reuse buffer for next poll (no allocation)
buffer.clear();
let count2 = core_handle.poll_outputs_into(&mut buffer, 100);

Source

pub fn poll_each<F>(&self, max_count: usize, f: F) -> usize
where F: FnMut(Output) -> bool,

Polls the outbox with a callback for each output (zero-allocation).

Processing stops when:

max_count outputs have been processed
The outbox becomes empty
The callback returns false

Returns the number of outputs processed.

§Example

// Process outputs without any allocation
let count = core_handle.poll_each(100, |output| {
    match output {
        Output::Event(event) => handle_event(event),
        _ => {}
    }
    true // Continue processing
});

Source