shmmap 🐏

Native bindings for mmap complemented with POSIX shm for creating (and safely destroying) actual shared memory segments for sharing large data between node.js processes beneath things like Buffer / Uint8Array.

``bash
$ npm install --save shmmap
`

Example


In parent.js:
`js
const cp = require('child_process');
const shmmap = require('shmmap');

// create a 4 MiB buffer
let nl_test = 4 1024 1024;
let [s_key, at_test] = shmmap.create(nl_test);

// write some data to it
let nl_half = nl_test>>1;
for(let i_write=0; i_write at_test[i_write] = i_write % 255;;
}

// spawn another process
let u_proc = cp.fork(__dirname+'/child.js', [s_key, at_test.byteLength, nl_half]);

// wait for process to exit
u_proc.on('exit', () => {
// count the sum
let c_sum = 0;
for(let i_read=0; i_read c_sum += at_test[i_read];
}

// output sum to console
console.log('parent sum: '+c_sum);

// sanity check that zero-th position has special value set
console.log('parent 0: '+at_test[0]);
});
`

In child.js:
`js
const shmmap = require('shmmap');

// open shared memory segment
let at_shared = shmmap.read_write(process.argv[2], +process.argv[3]);

// count sum
let c_sum = 0;
let nl_half = +process.argv[4];
for(let i_read=0; i_read c_sum += at_shared[i_read];
}

// write a value to zero-th position
at_shared[0] = 100;

// output sum to console
console.log('child sum: '+c_sum);
`

#### Results

`
child sum: 2097152
parent sum: 2097251
parent 0: 100
`

As we can see, the 'child' successfully mutates the zero-th value in the buffer that is shared between the two processes.

API

shmmap.create(byteLength: uint) -- creates a Buffer with the given byteLength atop a new shared memory segment.
- returns an Array of [key: path, data: buffer] -- where key is the string you would pass over IPC to another process to open the shared memory segment somewhere else.


shmmap.read(key: path, byteLength: uint) -- creates a Buffer with the given byteLength atop an existing shared memory segment, in read-only mode.
- returns the Buffer


shmmap.read_write(key: path, byteLength: uint) -- creates a Buffer with the given byteLength atop an existing shared memory segment, in read-write mode.
- returns the Buffer


shmmap.release(key: path) -- releases the current process' hold on the shared memory segment at key.
- returns undefined`