@neurodevs/node-lsl 17.1.1 → 18.1.0

package/src/__tests__/impl/LslStreamInlet.test.ts

@@ -1,17 +1,61 @@
-import { test, assert } from '@neurodevs/node-tdd'
+import { Worker } from 'node:worker_threads'
 
-import { StreamInletOptions } from '../../impl/LslStreamInlet.js'
+import { FakeLiblsl } from '@neurodevs/ndx-native'
+import { test, assert } from '@neurodevs/node-tdd'
+import {
+    createPointer,
+    DataType,
+    FieldType,
+    JsExternal,
+    PointerType,
+    unwrapPointer,
+} from 'ffi-rs'
+
+import LslStreamInlet, {
+    StreamInletOptions,
+} from '../../impl/LslStreamInlet.js'
+import StreamInletWorker from '../../impl/workers/inlet/StreamInletWorker.js'
 import { SpyStreamInlet } from '../../testDoubles/StreamInlet/SpyStreamInlet.js'
+import FakeWorker from '../../testDoubles/WorkerThreads/FakeWorker.js'
 import AbstractPackageTest from '../AbstractPackageTest.js'
 
 export default class LslStreamInletTest extends AbstractPackageTest {
     private static instance: SpyStreamInlet
 
     private static callsToOnData: {
-        samples: Float32Array
-        timestamps: Float64Array
+        samples: number[]
+        timestamps: number[]
     }[]
 
+    private static readonly sampleBufferPtr = unwrapPointer(
+        createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [new Float32Array(this.channelCount * this.chunkSize)],
+        })
+    )[0]
+
+    private static readonly timestampBufferPtr = unwrapPointer(
+        createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [new Float64Array(this.chunkSize)],
+        })
+    )[0]
+
+    private static readonly errorCodePtr = unwrapPointer(
+        createPointer({
+            paramsType: [DataType.U8Array],
+            paramsValue: [new Int32Array(1)],
+        })
+    )[0]
+
+    protected static async beforeAll() {
+        assert.isEqual(
+            LslStreamInlet.waitAfterOpenStreamMs,
+            100,
+            'Default waitAfterOpenStreamMs should be 100!'
+        )
+    }
+
     protected static async beforeEach() {
         await super.beforeEach()
 
@@ -21,6 +65,16 @@ export default class LslStreamInletTest extends AbstractPackageTest {
 
         this.callsToOnData = []
 
+        LslStreamInlet.waitAfterOpenStreamMs = 0
+
+        LslStreamInlet.Worker = FakeWorker as unknown as typeof Worker
+        FakeWorker.resetTestDoubles()
+
+        StreamInletWorker.lsl = this.fakeLiblsl
+        StreamInletWorker.freePointer = () => {}
+
+        FakeWorker.fakeOnData = this.onData
+
         this.instance = await this.LslStreamInlet()
     }
 
@@ -31,46 +85,82 @@ export default class LslStreamInletTest extends AbstractPackageTest {
 
     @test()
     protected static async callsBindingsToCreateStreamInlet() {
-        const fakeInfo = this.instance.getStreamInfo()
+        await this.startPulling()
 
-        assert.isTruthy(fakeInfo, 'Should have created stream info!')
+        assert.isTruthy(this.inletHandle, 'Should have created stream info!')
 
         assert.isEqualDeep(
             this.fakeLiblsl.lastCreateInletOptions,
             {
-                info: fakeInfo.boundInfo,
+                infoHandle: this.inletHandle,
                 maxBufferedMs: this.maxBufferedMs,
             },
             'Should have called createInlet!'
         )
+
+        this.stopPulling()
     }
 
     @test()
-    protected static async flushQueueCallsLslBinding() {
-        this.instance.flushQueue()
+    protected static async flushInletCallsLslBinding() {
+        this.instance.flushInlet()
 
         assert.isEqualDeep(
             this.fakeLiblsl.lastFlushInletOptions,
-            { inlet: this.boundInlet },
+            { inletHandle: this.inletHandle },
             'Should have called flushInlet!'
         )
     }
 
     @test()
     protected static async destroyCallsLslBinding() {
-        this.instance.destroy()
+        await this.startPullingThenDestroy()
 
         assert.isEqualDeep(
             this.fakeLiblsl.lastDestroyInletOptions,
-            { inlet: this.boundInlet },
+            { inletHandle: this.inletHandle },
             'Did not destroy inlet!'
         )
     }
 
+    @test()
+    protected static async destroyFreesAllPointers() {
+        interface FreePointerParams {
+            paramsType: FieldType[]
+            paramsValue: JsExternal[]
+            pointerType: PointerType
+        }
+
+        let calls: FreePointerParams[] = []
+
+        StreamInletWorker.freePointer = (params: FreePointerParams) => {
+            calls.push(params)
+        }
+
+        await this.startPullingThenDestroy()
+
+        const { paramsType, pointerType } = calls[0]
+
+        assert.isEqualDeep(
+            { paramsType, pointerType },
+            {
+                paramsType: [
+                    DataType.U8Array,
+                    DataType.U8Array,
+                    DataType.U8Array,
+                    DataType.U8Array,
+                ],
+                pointerType: PointerType.CPointer,
+            },
+
+            'Destroy did not free all pointers!'
+        )
+    }
+
     @test()
     protected static async destroyCallsStopIfIsRunning() {
-        this.instance.startPulling()
-        this.instance.destroy()
+        await this.startPulling()
+        this.destroy()
 
         assert.isFalse(
             this.instance.isRunning,
@@ -98,14 +188,135 @@ export default class LslStreamInletTest extends AbstractPackageTest {
 
     @test()
     protected static async startPullingSetsIsRunningToTrue() {
-        this.startPulling()
-        await this.wait(10)
+        await this.startPulling()
 
         assert.isTrue(this.isRunning, 'isRunning should be true!')
 
         this.stopPulling()
     }
 
+    @test()
+    protected static async doesNotStartPullingTwiceIfAlreadyRunning() {
+        await this.startPulling()
+        await this.startPulling()
+
+        assert.isEqual(
+            FakeWorker.callsToPostMessage.filter(
+                (msg) => msg.type === 'startPulling'
+            ).length,
+            1,
+            'startPulling did not return early!'
+        )
+
+        this.stopPulling()
+    }
+
+    @test()
+    protected static async startPullingOpensInletStream() {
+        await this.startPulling()
+
+        const aboutOneYearInMs = 32000000 * 1000
+
+        assert.isEqualDeep(
+            this.fakeLiblsl.lastOpenStreamOptions,
+            {
+                inletHandle: this.inletHandle,
+                timeoutMs: aboutOneYearInMs,
+                errorCodePtr: this.errorCodePtr,
+            },
+            'Did not open inlet stream!'
+        )
+
+        this.stopPulling()
+    }
+
+    @test()
+    protected static async opensInletStreamWithPassedTimeout() {
+        const openStreamTimeoutMs = 1000 * Math.random()
+
+        const instance = await this.LslStreamInlet({
+            openStreamTimeoutMs,
+        })
+
+        await this.startPulling(instance)
+
+        assert.isEqualDeep(
+            this.fakeLiblsl.lastOpenStreamOptions,
+            {
+                inletHandle: this.inletHandle,
+                timeoutMs: openStreamTimeoutMs,
+                errorCodePtr: this.errorCodePtr,
+            },
+            'Did not open inlet stream with passed timeout!'
+        )
+
+        instance.stopPulling()
+    }
+
+    @test()
+    protected static async waitsAfterOpeningStreamWithPassedOption() {
+        const waitAfterOpenStreamMs = 10
+
+        const instance = await this.LslStreamInlet({
+            waitAfterOpenStreamMs,
+        })
+
+        let t0 = Date.now()
+        await this.startPulling(instance)
+        let elapsed = Date.now() - t0
+
+        instance.stopPulling()
+
+        assert.isAbove(
+            elapsed,
+            waitAfterOpenStreamMs * 0.8,
+            'Did not wait after opening stream!'
+        )
+    }
+
+    @test()
+    protected static async stopPullingClosesInletStream() {
+        await this.startPulling()
+        this.stopPulling()
+
+        assert.isEqualDeep(
+            this.fakeLiblsl.lastCloseStreamOptions,
+            {
+                inletHandle: this.inletHandle,
+            },
+            'Did not close inlet stream!'
+        )
+    }
+
+    @test()
+    protected static async stopPullingFlushesInletByDefault() {
+        await this.startPulling()
+        this.stopPulling()
+
+        assert.isEqualDeep(
+            this.fakeLiblsl.lastFlushInletOptions,
+            {
+                inletHandle: this.inletHandle,
+            },
+            'Did not flush inlet!'
+        )
+    }
+
+    @test()
+    protected static async stopPullingDoesNotFlushInletIfPassedOption() {
+        const instance = await this.LslStreamInlet({
+            flushInletOnStop: false,
+        })
+
+        await this.startPulling(instance)
+        instance.stopPulling()
+
+        assert.isUndefined(
+            this.fakeLiblsl.lastFlushInletOptions,
+            'Should not have flushed inlet!'
+        )
+    }
+
     @test()
     protected static async stopPullingSetsIsRunningToFalse() {
         await this.startThenStop()
@@ -137,16 +348,16 @@ export default class LslStreamInletTest extends AbstractPackageTest {
 
     @test()
     protected static async callsPullSampleIfChunkSizeIsOne() {
-        const inlet = await this.runChunkSizeOne()
+        await this.runChunkSizeOne()
 
         assert.isEqualDeep(
             this.fakeLiblsl.lastPullSampleOptions,
             {
-                inlet: this.boundInlet,
-                dataBufferPtr: inlet['dataBufferPtr'],
-                dataBufferElements: this.channelCount,
-                timeout: 0,
-                errcodePtr: inlet['errorCodeBufferPtr'],
+                inletHandle: this.inletHandle,
+                sampleBufferPtr: this.sampleBufferPtr,
+                sampleBufferElements: this.channelCount,
+                timeoutMs: 0,
+                errorCodePtr: this.errorCodePtr,
             },
             'Should have called pullSample!'
         )
@@ -159,46 +370,114 @@ export default class LslStreamInletTest extends AbstractPackageTest {
         assert.isEqualDeep(
             this.fakeLiblsl.lastPullChunkOptions,
             {
-                inlet: this.boundInlet,
-                dataBufferPtr: this.instance['dataBufferPtr'],
-                timestampBufferPtr: this.instance['timestampBufferPtr'],
-                dataBufferElements: this.chunkSize * this.channelCount,
+                inletHandle: this.inletHandle,
+                sampleBufferPtr: this.sampleBufferPtr,
+                timestampBufferPtr: this.timestampBufferPtr,
+                sampleBufferElements: this.chunkSize * this.channelCount,
                 timestampBufferElements: this.chunkSize,
-                timeout: 0,
-                errcodePtr: this.instance['errorCodeBufferPtr'],
+                timeoutMs: 0,
+                errorCodePtr: this.errorCodePtr,
             },
             'Should have called pullChunk!'
         )
     }
 
+    @test()
+    protected static async pushSampleHandlesErrorCode() {
+        let passedErrorCode: number | undefined
+
+        StreamInletWorker.handleLslError = (errorCode: number) => {
+            passedErrorCode = errorCode
+        }
+
+        const fakeErrorCode = [-4, -3, -2, -1, 0][Math.floor(Math.random() * 5)]
+        const worker = this.getFakeWorker()
+
+        worker['inletWorker']['pullErrorBuffer'].writeInt32LE(fakeErrorCode)
+
+        await this.startThenStop()
+
+        assert.isEqualDeep(
+            passedErrorCode,
+            FakeLiblsl.fakeErrorCode,
+            'Did not pass the expected error code to handleLslError!'
+        )
+    }
+
+    @test()
+    protected static async waitsBetweenPullsIfPassedOption() {
+        const waitBetweenPullsMs = 10
+
+        const instance = await this.LslStreamInlet({
+            waitBetweenPullsMs,
+        })
+
+        let pulls = 0
+
+        const inletWorker = this.getFakeWorker(instance)['inletWorker']
+        const original = inletWorker['pullDataOnce'].bind(inletWorker)
+
+        inletWorker['pullDataOnce'] = async () => {
+            pulls++
+            await original()
+        }
+
+        const t0 = Date.now()
+        const promise = this.startPulling(instance)
+
+        while (pulls < 2) {
+            await this.wait(1)
+        }
+
+        const elapsed = Date.now() - t0
+
+        assert.isAbove(
+            elapsed,
+            waitBetweenPullsMs * 0.8,
+            'Did not wait between pulls'
+        )
+
+        instance.stopPulling()
+        await promise
+    }
+
+    @test()
+    protected static async waitsOneMillisecondBetweenPullsIfNotPassed() {
+        assert.isEqual(
+            this.instance['waitBetweenPullsMs'],
+            1,
+            'Default waitBetweenPullsMs should be 1!'
+        )
+    }
+
     @test()
     protected static async passesTimeoutMsOptionToPullSample() {
-        const timeoutMs = 1000 * Math.random()
+        const pullTimeoutMs = 1000 * Math.random()
 
         await this.runInletWithOptions({
             chunkSize: 1,
-            timeoutMs,
+            pullTimeoutMs,
         })
 
         assert.isEqual(
-            this.fakeLiblsl.lastPullSampleOptions?.timeout,
-            timeoutMs / 1000,
-            'Did not pass timeoutMs to pullSample!'
+            this.fakeLiblsl.lastPullSampleOptions?.timeoutMs,
+            pullTimeoutMs,
+            'Did not pass pullTimeoutMs to pullSample!'
         )
     }
 
     @test()
     protected static async passesTimeoutMsOptionToPullChunk() {
-        const timeoutMs = 1000 * Math.random()
+        const pullTimeoutMs = 1000 * Math.random()
 
         await this.runInletWithOptions({
             chunkSize: this.chunkSize,
-            timeoutMs,
+            pullTimeoutMs,
         })
 
         assert.isEqual(
-            this.fakeLiblsl.lastPullChunkOptions?.timeout,
-            timeoutMs / 1000,
+            this.fakeLiblsl.lastPullChunkOptions?.timeoutMs,
+            pullTimeoutMs,
             'Did not pass timeoutMs to pullChunk!'
         )
     }
@@ -217,57 +496,9 @@ export default class LslStreamInletTest extends AbstractPackageTest {
         )
     }
 
-    @test()
-    protected static async throwsWithUnknownErrorCode() {
-        await this.assertThrowsWithErrorCode(
-            -999,
-            `An unknown liblsl error has occurred!`
-        )
-    }
-
-    @test()
-    protected static async throwsWithErrorCodeNegativeOne() {
-        await this.assertThrowsWithErrorCode(
-            -1,
-            `The liblsl operation failed due to a timeout!`
-        )
-    }
-
-    @test()
-    protected static async throwsWithErrorCodeNegativeTwo() {
-        await this.assertThrowsWithErrorCode(
-            -2,
-            `The liblsl stream has been lost!`
-        )
-    }
-
-    @test()
-    protected static async throwsWithErrorCodeNegativeThree() {
-        await this.assertThrowsWithErrorCode(
-            -3,
-            'A liblsl argument was incorrectly specified!'
-        )
-    }
-
-    @test()
-    protected static async throwsWithErrorCodeNegativeFour() {
-        await this.assertThrowsWithErrorCode(
-            -4,
-            'An internal liblsl error has occurred!'
-        )
-    }
-
-    private static async assertThrowsWithErrorCode(
-        errorCode: number,
-        message: string
-    ) {
-        await this.startThenStop()
-
-        this.instance['errorCodeBuffer'].writeInt32LE(errorCode)
-
-        assert.doesThrow(() => {
-            this.instance['handleErrorCodeIfPresent']()
-        }, message)
+    private static async startPullingThenDestroy() {
+        await this.startPulling()
+        this.destroy()
     }
 
     private static async runChunkSizeOne() {
@@ -286,31 +517,47 @@ export default class LslStreamInletTest extends AbstractPackageTest {
 
     private static async startThenStop(inlet?: SpyStreamInlet) {
         const instance = inlet || this.instance
-        instance.startPulling()
+        await this.startPulling(instance)
         await this.wait(10)
         instance.stopPulling()
     }
 
-    private static startPulling() {
-        this.instance.startPulling()
+    private static async startPulling(instance?: SpyStreamInlet) {
+        const inst = instance || this.instance
+        const startPullingPromise = inst.startPulling()
+
+        while (!this.getFakeWorker(inst).createInletPromise) {
+            await this.wait(1)
+        }
+
+        await this.getFakeWorker(inst).createInletPromise
+        inst['workerReady'] = true
+
+        await startPullingPromise
     }
 
     private static stopPulling() {
         this.instance.stopPulling()
     }
 
+    private static destroy() {
+        this.instance.destroy()
+    }
+
     private static get isRunning() {
         return this.instance.isRunning
     }
 
-    private static get boundInlet() {
-        return this.instance.getBoundInlet()
+    private static get inletHandle() {
+        return this.getFakeWorker()['inletWorker']['inletHandle']
+    }
+
+    private static getFakeWorker(instance?: SpyStreamInlet) {
+        const inst = instance || this.instance
+        return inst['worker'] as unknown as FakeWorker
     }
 
-    private static onData = (
-        samples: Float32Array,
-        timestamps: Float64Array
-    ) => {
+    private static onData = (samples: number[], timestamps: number[]) => {
         this.callsToOnData.push({ samples, timestamps })
     }