Struct ChangePoller 

pub struct ChangePoller { /* private fields */ }

Cross-process change poller.

Tracks a cursor position in the WAL event log and returns new events on each poll() call. Each poller is independent — multiple readers can poll the same database at different rates.

Example

use std::time::Duration;
use pulsedb::{Config, ChangePoller};
use pulsedb::storage::{StorageEngine, RedbStorage};

let storage = RedbStorage::open(dir.path().join("test.db"), &Config::default())?;
let mut poller = ChangePoller::new();

loop {
    let events = poller.poll(&storage)?;
    for event in events {
        println!("Change: {:?}", event.event_type);
    }
    std::thread::sleep(Duration::from_millis(100));
}

Implementations

impl ChangePoller

pub fn new() -> Self

Creates a new poller starting from sequence 0 (receives all events).

pub fn from_sequence(seq: u64) -> Self

Creates a poller starting from a specific sequence number.

Events with sequence <= seq will not be returned. Use this to resume polling from a previously saved position.

pub fn with_batch_limit(self, limit: usize) -> Self

Creates a poller with a custom batch limit.

pub fn last_sequence(&self) -> u64

Returns the last sequence number this poller has consumed.

Save this value to resume polling after a restart.

pub fn poll(&mut self, storage: &dyn StorageEngine) -> Result<Vec<WatchEvent>>

Polls for new experience changes since the last call.

Returns new WatchEvents in sequence order and advances the internal cursor. Returns an empty vec if no new changes exist.

Backward compatibility: Only returns Experience-type events. Non-experience WAL events (relations, insights, collectives) are skipped but the cursor still advances past them.

Performance

Target: < 10ms per call. This performs a range scan on the watch_events redb table, which is O(k) where k = number of new events (not total events).

pub fn poll_sync_events( &mut self, storage: &dyn StorageEngine, ) -> Result<Vec<(u64, WatchEventRecord)>>

Available on crate feature sync only.

Polls for ALL entity changes since the last call (sync protocol).

Unlike poll() which only returns Experience events, this method returns all entity types with their WAL sequence numbers. Used by the sync pusher (Phase 3) to construct SyncChange objects.

Returns (sequence, record) pairs in ascending sequence order.

Trait Implementations

impl Default for ChangePoller

fn default() -> Self

Returns the “default value” for a type.