examples/memory-callbacks.mjs
GitHub// @node-skills {"added":["v26.1.0"],"flags":["--no-warnings"]}
// Native memory helpers and JS callbacks (qsort), on Linux/glibc.
import ffi from 'node:ffi';
import assert from 'node:assert/strict';
if (process.platform !== 'linux') { console.log('skip: uses glibc libc.so.6'); process.exit(77); }
using libc = new ffi.DynamicLibrary('libc.so.6');
const { malloc, free, strlen, qsort } = libc.getFunctions({
malloc: { arguments: ['uint64'], return: 'pointer' }, // uint64 accepts safe-integer numbers
free: { arguments: ['pointer'] },
strlen: { arguments: ['pointer'], return: 'uint64' },
qsort: { arguments: ['pointer', 'uint64', 'uint64', 'function'] },
});
const p = malloc(16);
assert.equal(typeof p, 'bigint');
try {
ffi.exportString('hi!', p, 16); // copies + NUL; length must cover both
assert.equal(ffi.toString(p), 'hi!');
assert.equal(strlen(p), 3n);
assert.throws(() => ffi.exportString('toolong', p, 3), { code: 'ERR_OUT_OF_RANGE' });
ffi.setInt32(p, 8, -7); // setters need an explicit offset
assert.equal(ffi.getInt32(p, 8), -7);
const copy = ffi.toBuffer(p, 4); // default: copied
copy[0] = 0x58;
assert.equal(ffi.toString(p), 'hi!');
const view = ffi.toBuffer(p, 4, false); // zero-copy view: writes hit native memory
view[0] = 0x58;
assert.equal(ffi.toString(p), 'Xi!');
assert.equal(ffi.toArrayBuffer(p, 4).byteLength, 4);
} finally {
free(p); // `view` is now dangling: never touch it again
}
// JS memory -> raw pointer (valid only while the buffer is alive and not detached/resized).
const b = Buffer.from('xyz\0');
assert.equal(strlen(ffi.getRawPointer(b)), 3n);
// Callbacks: register to get a function pointer; a plain JS function is NOT accepted.
const arr = new Int32Array([5, 1, 4, 2, 3]);
assert.throws(() => qsort(arr, arr.length, 4, () => 0), { code: 'ERR_INVALID_ARG_VALUE' });
const cmp = libc.registerCallback(
{ arguments: ['pointer', 'pointer'], return: 'int32' },
(a, b) => ffi.getInt32(a) - ffi.getInt32(b), // must not throw: a throwing callback aborts the process
);
assert.equal(typeof cmp, 'bigint');
qsort(arr, arr.length, arr.BYTES_PER_ELEMENT, cmp); // typed array passes its backing memory
assert.deepEqual([...arr], [1, 2, 3, 4, 5]);
libc.unregisterCallback(cmp); // only once native code can no longer call it