bpod_core.bpod.threads.EventThread

class bpod_core.bpod.threads.EventThread

Bases: Thread

Consumer thread that processes hardware events and builds the trial DataFrame.

Runs for the duration of one trial. ReadThread feeds raw RawEvent items into queue; EventThread drains that queue, advances the FSM state, and records every event — inputs, state transitions, and output actions — into an internal buffer.

When the trial ends (STOP_SENTINEL received), the buffer is converted to a polars.LazyFrame and pushed onto data_queue for the caller to collect via get_data().

Buffer design: events are appended to a pre-allocated NumPy structured array (_EVENT_DTYPE) that doubles in size when full. The buffer is only written at index _n_events before that counter is incremented, so indices 0.._n_events-1 are immutable once written.

Thread safety: peek_data() may be called from another thread while the trial is running. It copies the buffer view before passing it to Polars, ensuring a consistent snapshot.

__init__(*, trial, fsm, data_queue, event_lookup, action_names, time_reference) → None

Initialize the EventThread.

Parameters:

  • trial (int) – Zero-based trial index, used to populate the trial column.

  • fsm (StateMachineLookup) – Compiled state machine data for this trial.

  • data_queue (SimpleQueue[pl.LazyFrame]) – Queue to push the completed trial DataFrame into.

  • event_lookup (pl.DataFrame) – Pre-built event metadata lookup, see _build_event_lookup().

  • action_names (list of str) – Names of all output channels, indexed by action ID.

  • time_reference (TimeReferences) – Reference values for performance counters.

Return type:

None

peek_data(trigger_states=None) → LazyFrame

Return a snapshot of events recorded so far as a polars.LazyFrame.

Safe to call from a different thread while the trial is running. The returned DataFrame reflects events up to the moment _n_events was read; one in-flight event may be missed.

Parameters:

trigger_states (Collection of str, optional) – Block until at least one of the given states has been entered. If the trial ends before any of the states have been entered, returns whatever was recorded.

Returns:

A snapshot of the recorded events.

Return type:

pl.LazyFrame

Raises:

ValueError – If one or several of the trigger states are not part of the state machine.

run() → None

Execute the EventThread.

Return type:

None

stop() → None

Signal the FSM thread to stop.

Return type:

None

queue: SimpleQueue[RawEvent]

Per-trial event queue shared with ReadThread.