nd-shmem v1.0.12

nd-shmem

• simple binding of shmget shmat shmdt shmctl

• only work in nodejs

• for fast copy json-buffer/v8-serde using

• suitable for one writer(server) , many readers(client)
• it has no sync-mechanism implemented, you need do it yourself(normally just use socket/signal is OK)

install

• npm install nd-shmem

usage

  const x   = require("nd-shmem");

example

server

			Welcome to Node.js v20.1.0.
			Type ".help" for more information.
			>

			const x1 = require("nd-shmem");
			/*
			> x1.pid_
			470134
			>
			*/
			

			var mgmt = x1.creat_shmem_mgmt("shmem5g",1024*1024*1024*5);  // alloc a 5G shared buffer

			/*
			ShmemMgmt {
			  shmid: 12,
			  maxsz: 5368709120n,
			  pathname: '/home/cu-lib/nd-shmem/TEST/shmem5g',
			  proj_id: 65
			}

			> x1._eng.get_maxsz_with_shmid(12)
			[ true, 5368709120n ]
			>
			*/

clinet A

			Welcome to Node.js v20.1.0.
			Type ".help" for more information.
			>

			const x2 = require("nd-shmem");

			/*
			> x2.pid_
			470282
			>
			*/

			var vw_0to1g = x2.creat_view(12,1024*1024*1024,0)
			vw_0to1g[10]=255

			/*
			> vw_0to1g.buffer
			ArrayBuffer {
			  [Uint8Contents]: <00 00 00 00 00 00 00 00 00 00 【ff】 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ... 1073741724 more bytes>,
			  byteLength: 1073741824
			}
			>
			*/

client B

			Welcome to Node.js v20.1.0.
			Type ".help" for more information.
			>

			const x3 = require("nd-shmem");

			/*
			> x3.pid_
			470428
			>
			*/

			var vw_10to2g = x3.creat_view(12,1024*1024*1024*2,10)

			/*
			> vw_10to2g.buffer
			ArrayBuffer {
			  [Uint8Contents]: <【ff】 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ... 2147483548 more bytes>,
			  byteLength: 2147483648
			}
			>
			>
			*/
			vw_10to2g.set(Buffer.from(JSON.stringify([10,20,30])),5);

			> vw_10to2g.buffer
			ArrayBuffer {
			  [Uint8Contents]: <【ff】 00 00 00 00 【5b 31 30 2c 32 30 2c 33 30 5d】 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ... 2147483548 more bytes>,
			  byteLength: 2147483648
			}
			>



			//GO BACK  TO PROCESS X2 :

			/*
			> x2.pid_
			470282
			>
			*/
			vw_0to1g.subarray(10+5,10+5+10)
			/*
			>
			Shmem(10) [Uint8Array] [
			  91,
			  49,
			  48,
			  44,
			  50,
			  48,
			  44,
			  51,
			  48,
			  93,
			  shmid: -1,
			  state: 0,
			  shm_offset: -1
			]
			>

			> Buffer.from(vw_0to1g.subarray(10+5,10+5+10)).toString()
			'[10,20,30]'
			>

			*/


			/*

ipcs

			------ Message Queues --------
			key        msqid      owner      perms      used-bytes   messages

			------ Shared Memory Segments --------
			key        shmid      owner      perms      bytes      nattch     status
			0x00000000 12         root       0          5368709120 3          dest

			------ Semaphore Arrays --------
			key        semid      owner      perms      nsems
			*/

METHODS

ShmemMgmt

        mgmt.creat_view(sz:<must le 4G, else ArrayBuffer detached>,  offset=0) -> Shmem   // offset  alloc-the-array-buffer-backing-store-from-shmem
		mgmt.destroy()  -> [ Boolean, <shmid> ]                                           // shmctl(shmid,IPC_RMID,NULL);
		//getter dont change them , else crash
		mgmt.shmid
		mgmt.maxsz
		mgmt.pathname
		mgmt.proj_id

Shmem

        Shmem is just a Uint8Array


		detach()       ->  [ Boolean, <u64ptr> ]             //shmdt
		is_detached()
		is_active()
		//getter dont changethem, else crash
		shmem.shmid
		shmem.state
		shmem.shm_offset

APIS

###on mgmt:
maxsz is a BigInt, must <= os.freemem())

  const  creat_shmem_mgmt               = (pathname='shmem',maxsz=1024n*1024n*1024n,proj_id=65) => new ShmemMgmt({pathname,proj_id,maxsz,force:_f});
  const  creat_shmem_mgmt_force         = (pathname='shmem',maxsz=1024n*1024n*1024n,proj_id=65) => new ShmemMgmt({pathname,proj_id,maxsz,force:_t});

on client:

   creat_view(shmid,sz:<must le 4G, else ArrayBuffer detached>, offset=0) -> Shmem

LICENSE

• ISC