@neurodevs/node-lsl 18.1.0 → 20.0.0

package/src/impl/LslStreamInlet.ts

@@ -1,36 +1,75 @@
-import { Worker } from 'node:worker_threads'
+import {
+    handleLslError,
+    InfoHandle,
+    InletHandle,
+    LiblslAdapter,
+} from '@neurodevs/ndx-native'
+import {
+    JsExternal,
+    unwrapPointer,
+    createPointer,
+    DataType,
+    freePointer,
+    PointerType,
+} from 'ffi-rs'
 
-export default class LslStreamInlet implements StreamInlet {
-    public static Class?: StreamInletConstructor
-    public static Worker = Worker
+export default class LslStreamInlet implements LslInlet {
+    public static Class?: LslInletConstructor
     public static waitAfterOpenStreamMs = 100
+    public static lsl = LiblslAdapter.getInstance()
+    public static handleLslError = handleLslError
+    public static freePointer = freePointer
+
+    public isRunning = false
 
     private sourceId: string
     private chunkSize: number
     private maxBufferedMs: number
     private pullTimeoutMs: number
     private openStreamTimeoutMs: number
-    private waitAfterOpenStreamMs: number
     private waitBetweenPullsMs: number
     private flushInletOnStop: boolean
     private onData: OnDataCallback
 
-    private worker!: Worker
-    private workerReady = false
+    private infoHandle!: InfoHandle
+    private inletHandle!: InletHandle
+    private channelCount!: number
+
+    private pullMethod!: () => {
+        samples: number[] | undefined
+        timestamps: number[] | undefined
+    }
+
+    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 readonly sixMinutesInMs = 360 * 1000
     private readonly aboutOneYearInMs = 32000000 * 1000
 
-    public isRunning = false
+    private readonly bytesPerFloat = 4
+    private readonly bytesPerDouble = 8
+    private readonly bytesPerI32 = 4
 
-    protected constructor(options: StreamInletOptions, onData: OnDataCallback) {
+    protected constructor(options: LslInletOptions, onData: OnDataCallback) {
         const {
             sourceId,
             chunkSize,
             maxBufferedMs,
             pullTimeoutMs,
             openStreamTimeoutMs,
-            waitAfterOpenStreamMs,
             waitBetweenPullsMs,
             flushInletOnStop,
         } = options ?? {}
@@ -40,112 +79,301 @@ export default class LslStreamInlet implements StreamInlet {
         this.maxBufferedMs = maxBufferedMs ?? this.sixMinutesInMs
         this.pullTimeoutMs = pullTimeoutMs ?? 0
         this.openStreamTimeoutMs = openStreamTimeoutMs ?? this.aboutOneYearInMs
-        this.waitAfterOpenStreamMs = waitAfterOpenStreamMs ?? this.defaultWaitMs
         this.waitBetweenPullsMs = waitBetweenPullsMs ?? 1
         this.flushInletOnStop = flushInletOnStop ?? true
         this.onData = onData
-
-        this.createWorkerThread()
     }
 
     public static async Create(
-        options: StreamInletOptions,
+        options: LslInletOptions,
         onData: OnDataCallback
     ) {
         return new (this.Class ?? this)(options, onData)
     }
 
-    private createWorkerThread() {
-        this.worker = new this.Worker(
-            new URL('./workers/inlet/LslStreamInlet.worker.js', import.meta.url)
+    public async startPulling() {
+        if (this.isRunning) {
+            console.warn('Skipping startPulling: inlet is already running!')
+            return
+        }
+
+        this.isRunning = true
+
+        await this.createInlet()
+        void this.pullLoop()
+    }
+
+    private async createInlet() {
+        this.infoHandle = this.resolveInfoHandle()
+        this.inletHandle = this.doCreateInlet()
+        this.channelCount = this.getChannelCount()
+
+        this.allocateWritableBuffers()
+        this.setPullMethod()
+
+        this.openStream()
+    }
+
+    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.`
         )
+    }
 
-        this.worker.on('message', (msg) => {
-            const { type } = msg
-
-            switch (type) {
-                case 'ready': {
-                    this.workerReady = true
-                    break
-                }
-                case 'data': {
-                    const { payload } = msg
-                    const { samples, timestamps } = payload
-
-                    this.onData(samples, timestamps)
-                    break
-                }
-                case 'error': {
-                    const { error } = msg
-                    throw new Error(error)
-                }
-                default:
-                    throw new Error(`Unknown message type: ${type}`)
-            }
+    private doCreateInlet() {
+        return this.lsl.createInlet({
+            infoHandle: this.infoHandle,
+            maxBufferedMs: this.maxBufferedMs,
         })
     }
 
-    public async startPulling() {
-        if (!this.isRunning) {
-            this.isRunning = true
-            this.postCreate()
+    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)
 
-            while (!this.workerReady) {
-                await new Promise((resolve) => setTimeout(resolve, 10))
+        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 timestampSec = this.doPullsample()
+
+        if (timestampSec > 0) {
+            return {
+                samples: this.readSamplesFromBuffer(),
+                timestamps: [timestampSec],
             }
+        }
+        return { samples: undefined, timestamps: undefined }
+    }
 
-            this.postStartPulling()
-        } else {
-            console.warn('Skipping startPulling: inlet is already running!')
+    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 firstTimestampSec = this.doPullChunk()
+
+        if (firstTimestampSec > 0) {
+            return {
+                samples: this.readSamplesFromBuffer(),
+                timestamps: this.readTimestampsFromBuffer(),
+            }
         }
+        return { samples: undefined, timestamps: undefined }
     }
 
-    private postCreate() {
-        this.worker.postMessage({
-            type: 'createInlet',
-            payload: {
-                sourceId: this.sourceId,
-                chunkSize: this.chunkSize,
-                maxBufferedMs: this.maxBufferedMs,
-                openStreamTimeoutMs: this.openStreamTimeoutMs,
-                waitAfterOpenStreamMs: this.waitAfterOpenStreamMs,
-                pullTimeoutMs: this.pullTimeoutMs,
-                waitBetweenPullsMs: this.waitBetweenPullsMs,
-                flushInletOnStop: this.flushInletOnStop,
-            },
+    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 postStartPulling() {
-        this.worker.postMessage({ type: 'startPulling' })
+    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 pullLoop() {
+        while (this.isRunning) {
+            await this.pullDataOnce()
+            await this.waitBetweenPulls()
+        }
+    }
+
+    private async pullDataOnce() {
+        const { samples, timestamps } = this.pullMethod()
+        this.handleLslErrorIfPresent()
+
+        if (samples && timestamps) {
+            this.onData(samples, timestamps)
+        }
+    }
+
+    private handleLslErrorIfPresent() {
+        const errorCode = this.pullErrorBuffer.readInt32LE()
+        this.handleLslError(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.worker.postMessage({ type: 'stopPulling' })
+        this.closeStream()
+
+        if (this.flushInletOnStop) {
+            this.flushInlet()
+        }
     }
 
-    public flushInlet() {
-        this.worker.postMessage({ type: 'flushInlet' })
+    private closeStream() {
+        this.lsl.closeStream({ inletHandle: this.inletHandle })
     }
 
     public destroy() {
         if (this.isRunning) {
             this.stopPulling()
         }
-        this.worker.postMessage({ type: '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 LslStreamInlet.lsl
     }
 
-    private get defaultWaitMs() {
-        return LslStreamInlet.waitAfterOpenStreamMs
+    private get handleLslError() {
+        return LslStreamInlet.handleLslError
     }
 
-    private get Worker() {
-        return LslStreamInlet.Worker
+    private get freePointer() {
+        return LslStreamInlet.freePointer
     }
 }
 
-export interface StreamInlet {
+export interface LslInlet {
     startPulling(): Promise<void>
     stopPulling(): void
     flushInlet(): void
@@ -153,17 +381,16 @@ export interface StreamInlet {
     readonly isRunning: boolean
 }
 
-export type StreamInletConstructor = new (
-    options: StreamInletOptions,
+export type LslInletConstructor = new (
+    options: LslInletOptions,
     onData: OnDataCallback
-) => StreamInlet
+) => LslInlet
 
-export interface StreamInletOptions {
+export interface LslInletOptions {
     sourceId: string
     chunkSize: number
     maxBufferedMs?: number
     openStreamTimeoutMs?: number
-    waitAfterOpenStreamMs?: number
     pullTimeoutMs?: number
     waitBetweenPullsMs?: number
     flushInletOnStop?: boolean

package/src/impl/LslStreamOutlet.ts

@@ -1,6 +1,11 @@
-import { Worker } from 'node:worker_threads'
-
-import { ChannelFormat, Liblsl, LslSample } from '@neurodevs/ndx-native'
+import {
+    ChannelFormat,
+    LiblslAdapter,
+    LslErrorCode,
+    LslSample,
+    OutletHandle,
+    handleLslError,
+} from '@neurodevs/ndx-native'
 
 import {
     assertValidChannelCount,
@@ -9,10 +14,13 @@ import {
     assertValidMaxBufferedMs,
     assertValidSampleRateHz,
 } from '../assertions.js'
+import LslStreamInfo, { LslInfo } from './LslStreamInfo.js'
 
-export default class LslStreamOutlet implements StreamOutlet {
-    public static Class?: StreamOutletConstructor
-    public static Worker = Worker
+export default class LslStreamOutlet implements LslOutlet {
+    public static Class?: LslOutletConstructor
+    public static setTimeout = setTimeout
+    public static lsl = LiblslAdapter.getInstance()
+    public static handleLslError = handleLslError
 
     public readonly name: string
     public readonly type: string
@@ -26,9 +34,11 @@ export default class LslStreamOutlet implements StreamOutlet {
     public readonly manufacturer: string = 'N/A'
     public readonly units: string = 'N/A'
 
-    private worker!: Worker
+    private info!: LslInfo
+    private handle!: OutletHandle
+    private pushSampleToLsl!: (opts: unknown) => LslErrorCode
 
-    protected constructor(options: StreamOutletOptions) {
+    protected constructor(options: LslOutletOptions) {
         const {
             name,
             type,
@@ -55,11 +65,10 @@ export default class LslStreamOutlet implements StreamOutlet {
         this.units = units ?? this.units
 
         this.validateOptions()
-        this.createWorkerThread()
         this.createStreamOutlet()
     }
 
-    public static async Create(options: StreamOutletOptions) {
+    public static async Create(options: LslOutletOptions) {
         const { waitAfterConstructionMs = 10 } = options ?? {}
 
         const instance = new (this.Class ?? this)(options)
@@ -93,72 +102,67 @@ export default class LslStreamOutlet implements StreamOutlet {
         )
     }
 
-    private createWorkerThread() {
-        this.worker = new this.Worker(
-            new URL(
-                './workers/outlet/LslStreamOutlet.worker.js',
-                import.meta.url
-            )
-        )
-    }
-
     private createStreamOutlet() {
-        this.worker.postMessage({
-            type: 'createOutlet',
-            payload: {
-                infoOptions: {
-                    name: this.name,
-                    type: this.type,
-                    sourceId: this.sourceId,
-                    channelNames: this.channelNames,
-                    channelFormat: this.channelFormat,
-                    sampleRateHz: this.sampleRateHz,
-                    units: this.units,
-                },
-                chunkSize: this.chunkSize,
-                maxBufferedMs: this.maxBufferedMs,
-                pushMethod: this.pushMethod,
-            },
+        this.info = LslStreamInfo.Create({
+            name: this.name,
+            type: this.type,
+            sourceId: this.sourceId,
+            channelNames: this.channelNames,
+            channelFormat: this.channelFormat,
+            sampleRateHz: this.sampleRateHz,
+            units: this.units,
+        })
+
+        this.handle = this.lsl.createOutlet({
+            infoHandle: this.info.infoHandle,
+            chunkSize: this.chunkSize,
+            maxBufferedMs: this.maxBufferedMs,
         })
+
+        this.pushSampleToLsl = (
+            this.lsl[this.pushMethod] as (opts: unknown) => LslErrorCode
+        ).bind(this.lsl)
+    }
+
+    private get lsl() {
+        return LslStreamOutlet.lsl
     }
 
     private get pushMethod() {
         return this.methodMap[this.channelFormat]
     }
 
-    private readonly methodMap: Record<string, keyof Liblsl> = {
+    private readonly methodMap: Record<
+        string,
+        'pushSampleFloatTimestamp' | 'pushSampleStringTimestamp'
+    > = {
         float32: 'pushSampleFloatTimestamp',
         string: 'pushSampleStringTimestamp',
     }
 
-    public pushSample(sample: LslSample, timestampSec?: number) {
-        this.worker.postMessage({
-            type: 'pushSample',
-            payload: {
-                sample,
-                timestampSec,
-            },
+    public pushSample(sample: LslSample, timestampSec = this.lsl.localClock()) {
+        const errorCode = this.pushSampleToLsl({
+            outletHandle: this.handle,
+            sample,
+            timestampSec,
         })
-    }
 
-    public destroy() {
-        this.worker.postMessage({
-            type: 'destroyOutlet',
-        })
+        LslStreamOutlet.handleLslError(errorCode)
     }
 
-    private get Worker() {
-        return LslStreamOutlet.Worker
+    public destroy() {
+        this.lsl.destroyOutlet({ outletHandle: this.handle })
+        this.lsl.destroyStreamInfo({ infoHandle: this.info.infoHandle })
     }
 
     private static async waitForSetup(waitAfterConstructionMs: number) {
         await new Promise((resolve) =>
-            setTimeout(resolve, waitAfterConstructionMs)
+            LslStreamOutlet.setTimeout(resolve, waitAfterConstructionMs)
         )
     }
 }
 
-export interface StreamOutlet {
+export interface LslOutlet {
     pushSample(sample: LslSample, timestampSec?: number): void
     destroy(): void
     readonly name: string
@@ -174,15 +178,13 @@ export interface StreamOutlet {
     readonly manufacturer: string
 }
 
-export type StreamOutletConstructor = new (
-    options: StreamOutletOptions
-) => StreamOutlet
+export type LslOutletConstructor = new (options: LslOutletOptions) => LslOutlet
 
-export interface StreamOutletOptions extends StreamOutletConstructorOptions {
+export interface LslOutletOptions extends LslOutletConstructorOptions {
     waitAfterConstructionMs?: number
 }
 
-export interface StreamOutletConstructorOptions {
+export interface LslOutletConstructorOptions {
     name: string
     type: string
     sourceId: string