@neurodevs/node-lsl 17.1.0 → 18.0.0

package/src/impl/workers/inlet/LslStreamInlet.worker.ts

@@ -0,0 +1,74 @@
+import { parentPort } from 'node:worker_threads'
+import StreamInletWorker from './StreamInletWorker.js'
+
+const worker = new StreamInletWorker()
+
+parentPort?.on('message', async (msg: InletMessage) => {
+    try {
+        switch (msg.type) {
+            case 'createInlet':
+                const { payload } = msg
+                await worker.createInlet(payload)
+                parentPort?.postMessage({ type: 'ready' })
+                break
+
+            case 'startPulling':
+                worker.startPulling((samples, timestamps) => {
+                    parentPort?.postMessage({
+                        type: 'data',
+                        payload: {
+                            samples,
+                            timestamps,
+                        },
+                    })
+                })
+                break
+
+            case 'stopPulling':
+                worker.stopPulling()
+                break
+            case 'flushInlet':
+                worker.flushInlet()
+                break
+
+            case 'destroyInlet':
+                worker.destroyInlet()
+                parentPort?.close()
+                break
+        }
+    } catch (err) {
+        parentPort?.postMessage({
+            type: 'error',
+            error: err instanceof Error ? err.message : String(err),
+        })
+    }
+})
+
+export type InletMessage =
+    | {
+          type: 'createInlet'
+          payload: CreateInletPayload
+      }
+    | {
+          type: 'startPulling'
+      }
+    | {
+          type: 'flushInlet'
+      }
+    | {
+          type: 'stopPulling'
+      }
+    | {
+          type: 'destroyInlet'
+      }
+
+export interface CreateInletPayload {
+    sourceId: string
+    chunkSize: number
+    maxBufferedMs: number
+    openStreamTimeoutMs: number
+    waitAfterOpenStreamMs: number
+    pullTimeoutMs: number
+    waitBetweenPullsMs: number
+    flushInletOnStop: boolean
+}

package/src/impl/workers/inlet/StreamInletWorker.ts

@@ -0,0 +1,348 @@
+import {
+    handleError,
+    InfoHandle,
+    InletHandle,
+    LiblslAdapter,
+} from '@neurodevs/ndx-native'
+import {
+    JsExternal,
+    unwrapPointer,
+    createPointer,
+    DataType,
+    freePointer,
+    PointerType,
+} from 'ffi-rs'
+
+import { OnDataCallback } from '../../LslStreamInlet.js'
+import { CreateInletPayload } from './LslStreamInlet.worker.js'
+
+export default class StreamInletWorker {
+    public static lsl = LiblslAdapter.getInstance()
+    public static handleError = handleError
+    public static freePointer = freePointer
+
+    private sourceId!: string
+    private chunkSize!: number
+    private maxBufferedMs!: number
+    private openStreamTimeoutMs!: number
+    private waitAfterOpenStreamMs!: number
+    private waitBetweenPullsMs!: number
+    private pullTimeoutMs!: number
+    private flushInletOnStop!: boolean
+
+    private pullMethod!: () => {
+        samples: number[] | undefined
+        timestamps: number[] | undefined
+    }
+
+    protected infoHandle!: InfoHandle
+    protected inletHandle!: InletHandle
+    private channelCount!: number
+
+    private sampleBuffer!: Buffer<ArrayBuffer>
+    private sampleBufferRef!: JsExternal[]
+    private sampleBufferPtr!: JsExternal
+
+    private timestampBuffer!: Buffer<ArrayBuffer>
+    private timestampBufferRef!: JsExternal[]
+    private timestampBufferPtr!: JsExternal
+
+    private pullErrorBuffer!: Buffer<ArrayBuffer>
+    private pullErrorBufferRef!: JsExternal[]
+    private pullErrorBufferPtr!: JsExternal
+
+    private openStreamErrorBuffer!: Buffer<ArrayBuffer>
+    private openStreamErrorBufferRef!: JsExternal[]
+    private openStreamErrorBufferPtr!: JsExternal
+
+    private onData!: OnDataCallback
+
+    private readonly bytesPerFloat = 4
+    private readonly bytesPerDouble = 8
+    private readonly bytesPerI32 = 4
+
+    private isRunning = false
+
+    public async createInlet(payload: CreateInletPayload) {
+        Object.assign(this, payload)
+
+        this.infoHandle = this.resolveInfoHandle()
+        this.inletHandle = this.doCreateInlet()
+        this.channelCount = this.getChannelCount()
+
+        this.allocateWritableBuffers()
+        this.setPullMethod()
+
+        this.openStream()
+        await this.waitForSetup()
+    }
+
+    private resolveInfoHandle() {
+        const handles = this.resolveByProp()
+
+        if (handles.length === 0) {
+            this.throwNoStreamFound()
+        } else if (handles.length > 1) {
+            this.warnMultipleStreamsFound()
+        }
+        return handles[0]
+    }
+
+    private resolveByProp() {
+        return this.lsl.resolveByProp({
+            prop: 'source_id',
+            value: this.sourceId,
+        })
+    }
+
+    private throwNoStreamFound() {
+        throw new Error(`No stream info for sourceId "${this.sourceId}"`)
+    }
+
+    private warnMultipleStreamsFound() {
+        console.warn(
+            `Multiple stream infos for sourceId "${this.sourceId}", using the first one.`
+        )
+    }
+
+    private doCreateInlet() {
+        return this.lsl.createInlet({
+            infoHandle: this.infoHandle,
+            maxBufferedMs: this.maxBufferedMs,
+        })
+    }
+
+    private getChannelCount() {
+        return this.lsl.getChannelCount({ infoHandle: this.infoHandle })
+    }
+
+    private allocateWritableBuffers() {
+        this.allocateDataBuffer()
+        this.allocateTimestampBuffer()
+        this.allocatePullErrorBuffer()
+        this.allocateOpenStreamErrorBuffer()
+    }
+
+    private allocateDataBuffer() {
+        this.sampleBuffer = Buffer.alloc(
+            this.channelCount * this.chunkSize * this.bytesPerFloat
+        )
+
+        this.sampleBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.sampleBuffer],
+        })
+
+        this.sampleBufferPtr = unwrapPointer(this.sampleBufferRef)[0]
+    }
+
+    private allocateTimestampBuffer() {
+        this.timestampBuffer = Buffer.alloc(
+            this.chunkSize * this.bytesPerDouble
+        )
+
+        this.timestampBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.timestampBuffer],
+        })
+
+        this.timestampBufferPtr = unwrapPointer(this.timestampBufferRef)[0]
+    }
+
+    private allocatePullErrorBuffer() {
+        this.pullErrorBuffer = Buffer.alloc(this.bytesPerI32)
+
+        this.pullErrorBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.pullErrorBuffer],
+        })
+
+        this.pullErrorBufferPtr = unwrapPointer(this.pullErrorBufferRef)[0]
+    }
+
+    private allocateOpenStreamErrorBuffer() {
+        this.openStreamErrorBuffer = Buffer.alloc(this.bytesPerI32)
+
+        this.openStreamErrorBufferRef = createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [this.openStreamErrorBuffer],
+        })
+
+        this.openStreamErrorBufferPtr = unwrapPointer(
+            this.openStreamErrorBufferRef
+        )[0]
+    }
+
+    private setPullMethod() {
+        this.pullMethod =
+            this.chunkSize === 1 ? this.pullSample : this.pullChunk
+    }
+
+    private pullSample = () => {
+        const timestamp = this.doPullsample()
+
+        if (timestamp > 0) {
+            return {
+                samples: this.readSamplesFromBuffer(),
+                timestamps: [timestamp],
+            }
+        }
+        return { samples: undefined, timestamps: undefined }
+    }
+
+    private doPullsample() {
+        return this.lsl.pullSample({
+            inletHandle: this.inletHandle,
+            sampleBufferPtr: this.sampleBufferPtr,
+            sampleBufferElements: this.channelCount,
+            timeoutMs: this.pullTimeoutMs,
+            errorCodePtr: this.pullErrorBufferPtr,
+        })
+    }
+
+    private readSamplesFromBuffer() {
+        const floats = new Float32Array(
+            this.sampleBuffer.buffer,
+            this.sampleBuffer.byteOffset,
+            this.chunkSize * this.channelCount
+        )
+        return Array.from(floats)
+    }
+
+    private pullChunk = () => {
+        const firstTimestamp = this.doPullChunk()
+
+        if (firstTimestamp > 0) {
+            return {
+                samples: this.readSamplesFromBuffer(),
+                timestamps: this.readTimestampsFromBuffer(),
+            }
+        }
+        return { samples: undefined, timestamps: undefined }
+    }
+
+    private doPullChunk() {
+        return this.lsl.pullChunk({
+            inletHandle: this.inletHandle,
+            sampleBufferPtr: this.sampleBufferPtr,
+            sampleBufferElements: this.chunkSize * this.channelCount,
+            timestampBufferPtr: this.timestampBufferPtr,
+            timestampBufferElements: this.chunkSize,
+            timeoutMs: this.pullTimeoutMs,
+            errorCodePtr: this.pullErrorBufferPtr,
+        })
+    }
+
+    private readTimestampsFromBuffer() {
+        const doubles = new Float64Array(
+            this.timestampBuffer.buffer,
+            this.timestampBuffer.byteOffset,
+            this.chunkSize
+        )
+        return Array.from(doubles)
+    }
+
+    private openStream() {
+        this.lsl.openStream({
+            inletHandle: this.inletHandle,
+            timeoutMs: this.openStreamTimeoutMs,
+            errorCodePtr: this.openStreamErrorBufferPtr,
+        })
+    }
+
+    private async waitForSetup() {
+        return new Promise((r) => setTimeout(r, this.waitAfterOpenStreamMs))
+    }
+
+    public startPulling(onData: OnDataCallback) {
+        if (this.isRunning) {
+            console.warn('StreamInletWorker is already running.')
+            return
+        }
+        this.isRunning = true
+        this.onData = onData
+
+        void this.pullLoop()
+    }
+
+    private async pullLoop() {
+        while (this.isRunning) {
+            await this.pullDataOnce()
+            await this.waitBetweenPulls()
+        }
+    }
+
+    private async pullDataOnce() {
+        const { samples, timestamps } = this.pullMethod()
+        this.handleErrorIfPresent()
+
+        if (samples && timestamps) {
+            this.onData(samples, timestamps)
+        }
+    }
+
+    private handleErrorIfPresent() {
+        const errorCode = this.pullErrorBuffer.readInt32LE()
+        this.handleError(errorCode)
+    }
+
+    private async waitBetweenPulls() {
+        await new Promise((r) => setTimeout(r, this.waitBetweenPullsMs))
+    }
+
+    public flushInlet() {
+        this.lsl.flushInlet({ inletHandle: this.inletHandle })
+    }
+
+    public stopPulling() {
+        this.isRunning = false
+        this.closeStream()
+
+        if (this.flushInletOnStop) {
+            this.flushInlet()
+        }
+    }
+
+    private closeStream() {
+        this.lsl.closeStream({ inletHandle: this.inletHandle })
+    }
+
+    public destroyInlet() {
+        this.doDestroyInlet()
+        this.freeNativePointers()
+    }
+
+    private doDestroyInlet() {
+        this.lsl.destroyInlet({ inletHandle: this.inletHandle })
+    }
+
+    private freeNativePointers() {
+        this.freePointer({
+            paramsType: [
+                DataType.U8Array,
+                DataType.U8Array,
+                DataType.U8Array,
+                DataType.U8Array,
+            ],
+            paramsValue: [
+                this.openStreamErrorBufferPtr,
+                this.sampleBufferPtr,
+                this.timestampBufferPtr,
+                this.pullErrorBufferPtr,
+            ],
+            pointerType: PointerType.CPointer,
+        })
+    }
+
+    private get lsl() {
+        return StreamInletWorker.lsl
+    }
+
+    private get handleError() {
+        return StreamInletWorker.handleError
+    }
+
+    private get freePointer() {
+        return StreamInletWorker.freePointer
+    }
+}

package/src/impl/workers/outlet/LslStreamOutlet.worker.ts

@@ -0,0 +1,144 @@
+import { parentPort } from 'node:worker_threads'
+
+import {
+    LiblslAdapter,
+    Liblsl,
+    OutletHandle,
+    handleError,
+    LslErrorCode,
+} from '@neurodevs/ndx-native'
+
+import LslStreamInfo, {
+    StreamInfo,
+    StreamInfoOptions,
+} from '../../LslStreamInfo.js'
+
+let lsl = LiblslAdapter.getInstance()
+
+export function setOutletLiblslAdapter(adapter: Liblsl) {
+    LiblslAdapter.setInstance(adapter)
+    lsl = LiblslAdapter.getInstance()
+}
+
+let handleErrorFn = handleError
+
+export function setOutletHandleError(fn: typeof handleError) {
+    handleErrorFn = fn
+}
+
+let info: StreamInfo
+let handle: OutletHandle
+let pushMethod: (opts: unknown) => LslErrorCode
+
+parentPort?.on('message', (msg: OutletMessage) => {
+    const { type } = msg
+
+    try {
+        switch (type) {
+            case 'createOutlet': {
+                createOutlet(msg)
+                break
+            }
+
+            case 'pushSample': {
+                pushSample(msg)
+                break
+            }
+
+            case 'destroyOutlet': {
+                destroyOutlet()
+                break
+            }
+        }
+    } catch (err) {
+        parentPort?.postMessage({
+            type: 'error',
+            error: err instanceof Error ? err.message : String(err),
+        })
+    }
+})
+
+export function createOutlet(msg: {
+    type: 'createOutlet'
+    payload: CreateOutletPayload
+}) {
+    const { payload } = msg
+
+    info = LslStreamInfo.Create(payload.infoOptions)
+
+    handle = lsl.createOutlet({
+        infoHandle: info.infoHandle,
+        chunkSize: payload.chunkSize,
+        maxBufferedMs: payload.maxBufferedMs,
+    })
+
+    pushMethod = (
+        lsl[payload.pushMethod] as (opts: unknown) => LslErrorCode
+    ).bind(lsl)
+
+    parentPort?.postMessage({ type: 'ready' })
+}
+
+export function pushSample(msg: {
+    type: 'pushSample'
+    payload: PushSamplePayload
+}) {
+    const { payload } = msg
+    const { sample, timestamp = lsl.localClock() } = payload
+
+    if (!handle || !pushMethod) {
+        throw new Error('Outlet not initialized')
+    }
+
+    const errorCode = pushMethod({
+        outletHandle: handle,
+        sample,
+        timestamp,
+    })
+
+    try {
+        handleErrorFn(errorCode)
+    } catch {
+        parentPort?.postMessage({
+            type: 'error',
+            error: `Error pushing sample: ${LslErrorCode[errorCode]}`,
+        })
+    }
+}
+
+export function destroyOutlet() {
+    if (handle) {
+        lsl.destroyOutlet({ outletHandle: handle })
+    }
+
+    if (info) {
+        lsl.destroyStreamInfo({ infoHandle: info.infoHandle })
+    }
+
+    parentPort?.close()
+}
+
+export type OutletMessage =
+    | {
+          type: 'createOutlet'
+          payload: CreateOutletPayload
+      }
+    | {
+          type: 'pushSample'
+          payload: PushSamplePayload
+      }
+    | {
+          type: 'destroyOutlet'
+      }
+
+export interface CreateOutletPayload {
+    infoOptions: StreamInfoOptions
+    chunkSize: number
+    maxBufferedMs: number
+    pushMethod: 'pushSampleFloatTimestamp' | 'pushSampleStringTimestamp'
+}
+
+export interface PushSamplePayload {
+    sample: unknown
+    timestamp?: number
+}

package/src/index.ts

@@ -1,27 +1,24 @@
-// EventMarkerOutlet
+// BackpressureMonitor
 
-export { default as LslEventMarkerOutlet } from './impl/LslEventMarkerOutlet.js'
-export * from './impl/LslEventMarkerOutlet.js'
+export { default as LslBackpressureMonitor } from './impl/LslBackpressureMonitor.js'
+export * from './impl/LslBackpressureMonitor.js'
 
-export { default as FakeEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/FakeEventMarkerOutlet.js'
-export * from './testDoubles/EventMarkerOutlet/FakeEventMarkerOutlet.js'
+export { default as FakeBackpressureMonitor } from './testDoubles/BackpressureMonitor/FakeBackpressureMonitor.js'
+export * from './testDoubles/BackpressureMonitor/FakeBackpressureMonitor.js'
 
-export { default as MockEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/MockEventMarkerOutlet.js'
-export * from './testDoubles/EventMarkerOutlet/MockEventMarkerOutlet.js'
+// EventMarkerEmitter
 
-export { default as SpyEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/SpyEventMarkerOutlet.js'
-export * from './testDoubles/EventMarkerOutlet/SpyEventMarkerOutlet.js'
+export { default as LslEventMarkerEmitter } from './impl/LslEventMarkerEmitter.js'
+export * from './impl/LslEventMarkerEmitter.js'
 
-export { default as ThrowingEventMarkerOutlet } from './testDoubles/EventMarkerOutlet/ThrowingEventMarkerOutlet.js'
-export * from './testDoubles/EventMarkerOutlet/ThrowingEventMarkerOutlet.js'
+export { default as FakeEventMarkerEmitter } from './testDoubles/EventMarkerEmitter/FakeEventMarkerEmitter.js'
+export * from './testDoubles/EventMarkerEmitter/FakeEventMarkerEmitter.js'
 
-// Liblsl
+export { default as SpyEventMarkerEmitter } from './testDoubles/EventMarkerEmitter/SpyEventMarkerEmitter.js'
+export * from './testDoubles/EventMarkerEmitter/SpyEventMarkerEmitter.js'
 
-export { default as LiblslAdapter } from './impl/LiblslAdapter.js'
-export * from './impl/LiblslAdapter.js'
-
-export { default as FakeLiblsl } from './testDoubles/Liblsl/FakeLiblsl.js'
-export * from './testDoubles/Liblsl/FakeLiblsl.js'
+export { default as ThrowingEventMarkerEmitter } from './testDoubles/EventMarkerEmitter/ThrowingEventMarkerEmitter.js'
+export * from './testDoubles/EventMarkerEmitter/ThrowingEventMarkerEmitter.js'
 
 // StreamInfo
 

package/src/scripts/finalizeHandles.ts

@@ -0,0 +1,63 @@
+export type DestroyHandle = () => void // Do not make this async
+
+const destroyHandles = new Set<DestroyHandle>()
+
+let isFinalizing = false
+
+export function register(destroy: DestroyHandle) {
+    if (isFinalizing) {
+        destroy()
+        return
+    }
+
+    destroyHandles.add(destroy)
+
+    const unregister = () => {
+        destroyHandles.delete(destroy)
+    }
+
+    return unregister
+}
+
+function finalizeHandles() {
+    if (isFinalizing) {
+        return
+    }
+    isFinalizing = true
+
+    for (const destroy of destroyHandles) {
+        try {
+            destroy()
+        } catch (err) {
+            console.error('Error during finalization:', err)
+        }
+    }
+
+    destroyHandles.clear()
+}
+
+process.once('SIGINT', finalizeHandles)
+
+process.once('SIGTERM', finalizeHandles)
+
+process.once('uncaughtException', (err) => {
+    console.error('Uncaught exception:', err)
+    finalizeHandles()
+    process.exit(1)
+})
+
+process.once('unhandledRejection', (reason) => {
+    console.error('Unhandled rejection:', reason)
+    finalizeHandles()
+    process.exit(1)
+})
+
+process.once('beforeExit', () => {
+    if (destroyHandles.size > 0 && !isFinalizing) {
+        console.warn(
+            'Warning: process is exiting with active handles.\n' +
+                'Did you forget to call destroy()? Finalizing automatically.'
+        )
+        finalizeHandles()
+    }
+})

package/src/scripts/runLslEventMarkerEmitter.ts

@@ -0,0 +1,15 @@
+import LslEventMarkerEmitter from '../impl/LslEventMarkerEmitter.js'
+
+const outlet = await LslEventMarkerEmitter.Create()
+
+const markers = [
+    { name: 'phase-1-begin', waitAfterMs: 100 },
+    { name: 'phase-1-end', waitAfterMs: 100 },
+    { name: 'never-reached-marker', waitAfterMs: 100 },
+]
+
+void outlet.emitMany(markers)
+
+await new Promise((resolve) => setTimeout(resolve, 250))
+
+outlet.interrupt()