Refactor to pinBuffer API to make garbage collection guarantees

Author: skadisch

lib/index.ts

@@ -1,16 +1,49 @@
 import { nativeBuffer2address, nativeAddress2buffer } from "./native.ts";
+import nodeAssert from "node:assert";
 
-const buffer2address = ({ buffer }: { buffer: Uint8Array }) => {
-  return nativeBuffer2address(buffer);
+let pinnedBuffers: Uint8Array[] = [];
+
+type TPinnedBuffer = {
+  address: bigint;
+  unpin: () => void;
 };
 
-const address2buffer = ({ address, size }: { address: bigint, size: number }) => {
+const pinBuffer = ({ buffer }: { buffer: Uint8Array }): TPinnedBuffer => {
+
+  pinnedBuffers = [...pinnedBuffers, buffer];
+  let pinned = true;
+
+  const unpin = () => {
+
+    if (!pinned) {
+      throw new Error("buffer already unpinned");
+    }
+    pinned = false;
+
+    // do not use filter, as one could pin the same buffer multiple times
+    const pinnedIndex = pinnedBuffers.indexOf(buffer);
+    nodeAssert.ok(pinnedIndex >= 0, "buffer should be in pinned buffers, this is a bug");
 
+    pinnedBuffers.splice(pinnedIndex, 1);
+  };
 
+  const address = nativeBuffer2address(buffer);
+
+  return {
+    address,
+    unpin
+  };
+};
+
+const address2buffer = ({ address, size }: { address: bigint, size: number }) => {
   return nativeAddress2buffer(address, BigInt(size));
 };
 
 export {
-  buffer2address,
+  pinBuffer,
   address2buffer
 };
+
+export type {
+  TPinnedBuffer
+};

test/basic.ts

@@ -2,13 +2,15 @@
 /* global it */
 
 import assert from "assert";
-import { buffer2address, address2buffer } from "../lib/index.ts";
+import { pinBuffer, address2buffer } from "../lib/index.ts";
 
 describe("buffer2address", () => {
   it("should provide address of buffer as BigInt", () => {
     const buffer = Buffer.alloc(32);
-    const addr = buffer2address({ buffer });
-    assert.equal(typeof addr, "bigint");
+
+    const pinnedBuffer = pinBuffer({ buffer });
+    assert.equal(typeof pinnedBuffer.address, "bigint");
+    pinnedBuffer.unpin();
   });
 
   // it("should throw an error when no arguments are given", () => {
@@ -25,22 +27,38 @@ describe("buffer2address", () => {
   //   // @ts-expect-error testing wrong argument type
   //   assert.throws(() => buffer2address("abc"));
   // });
+
+  it("should throw an error when unpinning twice", () => {
+    const buffer = Buffer.alloc(16);
+    const pinnedBuffer = pinBuffer({ buffer });
+
+    pinnedBuffer.unpin();
+
+    assert.throws(() => {
+      pinnedBuffer.unpin();
+    }, (err: Error) => {
+      assert.equal(err.message, "buffer already unpinned");
+      return true;
+    });
+  });
 });
 
 describe("address2buffer", () => {
   it("should create buffer from address correctly", () => {
     const size = 32;
     const buf = new Uint8Array(size);
-    const address = buffer2address({ buffer: buf });
 
-    const newBuf = address2buffer({ address, size });
+    const pinnedBuffer = pinBuffer({ buffer: buf });
+    const newBuf = address2buffer({ address: pinnedBuffer.address, size });
 
     const testValues = [0x22, 0x33, 0x44];
 
     testValues.forEach((value) => {
       buf[0] = value;
       assert.equal(newBuf[0], value);
     });
+
+    pinnedBuffer.unpin();
   });
 
   // it("should fail on missing address parameter", () => {