{"id":15011178,"url":"https://github.com/ukrbublik/shm-typed-array","last_synced_at":"2025-05-08T00:24:57.648Z","repository":{"id":13120642,"uuid":"73239666","full_name":"ukrbublik/shm-typed-array","owner":"ukrbublik","description":"IPC shared memory for NodeJs. Use as Buffer or TypedArray.","archived":false,"fork":false,"pushed_at":"2024-05-15T07:19:01.000Z","size":106,"stargazers_count":73,"open_issues_count":6,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-13T20:51:48.722Z","etag":null,"topics":["buffer","ipc","nodejs","shared-memory","sharedarraybuffer","shm","typescript"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ukrbublik.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ukrbublik"}},"created_at":"2016-11-09T00:37:36.000Z","updated_at":"2024-12-08T17:51:57.000Z","dependencies_parsed_at":"2024-06-22T22:48:57.836Z","dependency_job_id":null,"html_url":"https://github.com/ukrbublik/shm-typed-array","commit_stats":{"total_commits":64,"total_committers":6,"mean_commits":"10.666666666666666","dds":0.21875,"last_synced_commit":"0b3a09d506b5cfb0d04df819707679c7b745d6c7"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukrbublik%2Fshm-typed-array","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukrbublik%2Fshm-typed-array/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukrbublik%2Fshm-typed-array/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukrbublik%2Fshm-typed-array/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ukrbublik","download_url":"https://codeload.github.com/ukrbublik/shm-typed-array/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231468021,"owners_count":18381174,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buffer","ipc","nodejs","shared-memory","sharedarraybuffer","shm","typescript"],"created_at":"2024-09-24T19:39:28.589Z","updated_at":"2024-12-27T10:07:48.739Z","avatar_url":"https://github.com/ukrbublik.png","language":"C++","funding_links":["https://github.com/sponsors/ukrbublik"],"categories":[],"sub_categories":[],"readme":"IPC shared memory for Node.js  \nUse as `Buffer` or `TypedArray`  \nSupports System V and POSIX shared memory  \n[![npm](https://img.shields.io/npm/v/shm-typed-array.svg)](https://www.npmjs.com/package/shm-typed-array) [![travis](https://travis-ci.org/ukrbublik/shm-typed-array.svg?branch=master)](https://travis-ci.com/github/ukrbublik/shm-typed-array)\n\n\n# Install\n``` bash\n$ npm install shm-typed-array\n```\nWindows is not supported.\n\n# System V vs POSIX\n\nVersions 0.0.* support only [System V memory segments](https://man7.org/linux/man-pages/man7/sysvipc.7.html).  \nStarting from version 0.1.0 [POSIX memory objects](https://man7.org/linux/man-pages/man7/shm_overview.7.html) are also supported. \n\nSystem V is the classic way to use shared memory, stores IPC objects internally in the kernel.  \nPOSIX is newer, but not fully supported in MacOS, uses the file system interface. \n\nTo create POSIX memory objects, use string parameter `key` in [API](#api).  \nEg. `shm.create(100, 'Buffer', '/test')` will create virtual file `/dev/shm/test` in tmpfs for Linix. \n\nTo create System V memory segment, use numeric parameter `key` in [API](#api).  \nEg. `shm.create(100, 'Buffer', 1234)` or `shm.create(100)` to autogenerate key. \n\n\n# API\n\n### shm.create (count, typeKey, key?, perm?)\nCreate shared memory segment/object.  \n`count` - number of elements (not bytes),  \n`typeKey` - type of elements (`'Buffer'` by default, see list below),  \n`key` - integer/null to create System V memory segment, or string to create POSIX memory object,  \n`perm` - permissions flag (default is `660`).  \nReturns shared memory `Buffer` or descendant of `TypedArray` object, class depends on param `typeKey`.  \nOr returns `null` if shm already exists with provided key.  \n*For System V:* returned object has property `key` - integer key of created System V shared memory segment, to use in `shm.get(key)`.  \n*For POSIX:* shared memory objects are not automatically destroyed. You should call `shm.destroy(key)` manually on process cleanup or if you don't need the object anymore.\n\n### shm.get (key, typeKey)\nGet created shared memory segment/object by key.  \nReturns `null` if shm not exists with provided key.\n\n### shm.detach (key, forceDestroy?)\nDetach shared memory segment/object.  \n*For System V:* If there are no other attaches for a segment, it will be destroyed automatically (even if `forceDestroy` is not true).  \n*For POSIX:* Unlike System V segments, POSIX object will not be destroyed automatically. You need to destroy it manually by providing true to `forceDestroy` argument or using `shm.destroy(key)`.\n\n### shm.destroy (key)\nDestroy shared memory segment/object.  \nSame as `shm.detach(key, true)`\n\n### shm.detachAll ()\nDetach all created shared memory segments and objects.  \nWill be automatically called on process exit, see [Cleanup](#cleanup).\n\n### shm.getTotalSize()\nGet total size of all *used* (mapped) shared memory in bytes.\n\n### shm.getTotalCreatedSize()\nGet total size of all *created* shared memory in bytes.\n\n### shm.LengthMax\nMax length of shared memory segment (count of elements, not bytes)  \n2^31 for 64bit, 2^30 for 32bit\n\n#### Types:\n```js\nshm.BufferType = {\n\t'Buffer': shm.SHMBT_BUFFER,\n\t'Int8Array': shm.SHMBT_INT8,\n\t'Uint8Array': shm.SHMBT_UINT8,\n\t'Uint8ClampedArray': shm.SHMBT_UINT8CLAMPED,\n\t'Int16Array': shm.SHMBT_INT16,\n\t'Uint16Array': shm.SHMBT_UINT16,\n\t'Int32Array': shm.SHMBT_INT32,\n\t'Uint32Array': shm.SHMBT_UINT32,\n\t'Float32Array': shm.SHMBT_FLOAT32,\n\t'Float64Array': shm.SHMBT_FLOAT64,\n};\n```\n\n\n# Cleanup\nThis library does cleanup of created SHM segments/objects only on normal exit of process, see [`exit` event](https://nodejs.org/api/process.html#process_event_exit).  \nIf you want to do cleanup on terminate signals like `SIGINT`, `SIGTERM`, please use [node-cleanup](https://github.com/jtlapp/node-cleanup) / [node-death](https://github.com/jprichardson/node-death) and add code to exit handlers:\n```js\nshm.detachAll();\n```\n\nAlso note that POSIX shared memory objects are not automatically destroyed. \nYou should call `shm.destroy('/your_name')` manually if you don't need it anymore.\n\n\n# Usage\nSee [example.js](https://github.com/ukrbublik/shm-typed-array/blob/master/test/example.js)\n\n\nUsage of memory segments:\n``` js\nconst cluster = require('cluster');\nconst shm = require('shm-typed-array');\n\nvar buf, arr;\nif (cluster.isMaster) {\n\tbuf = shm.create(4096); //4KB\n\tarr = shm.create(1000000*100, 'Float32Array'); //100M floats\n\tbuf[0] = 1;\n\tarr[0] = 10.0;\n\tconsole.log('[Master] Typeof buf:', buf.constructor.name,\n\t\t'Typeof arr:', arr.constructor.name);\n\t\n\tvar worker = cluster.fork();\n\tworker.on('online', function() {\n\t\tthis.send({ msg: 'shm', bufKey: buf.key, arrKey: arr.key });\n\t\tvar i = 0;\n\t\tsetInterval(function() {\n\t\t\tbuf[0] += 1;\n\t\t\tarr[0] /= 2;\n\t\t\tconsole.log(i + ' [Master] Set buf[0]=', buf[0],\n\t\t\t\t' arr[0]=', arr ? arr[0] : null);\n\t\t\ti++;\n\t\t\tif (i == 5) {\n\t\t\t\tgroupSuicide();\n\t\t\t}\n\t\t}, 500);\n\t});\n} else {\n\tprocess.on('message', function(data) {\n\t\tvar msg = data.msg;\n\t\tif (msg == 'shm') {\n\t\t\tbuf = shm.get(data.bufKey);\n\t\t\tarr = shm.get(data.arrKey, 'Float32Array');\n\t\t\tconsole.log('[Worker] Typeof buf:', buf.constructor.name,\n\t\t\t\t'Typeof arr:', arr.constructor.name);\n\t\t\tvar i = 0;\n\t\t\tsetInterval(function() {\n\t\t\t\tconsole.log(i + ' [Worker] Get buf[0]=', buf[0],\n\t\t\t\t\t' arr[0]=', arr ? arr[0] : null);\n\t\t\t\ti++;\n\t\t\t\tif (i == 2) {\n\t\t\t\t\tshm.detach(data.arrKey);\n\t\t\t\t\tarr = null; //otherwise process will drop\n\t\t\t\t}\n\t\t\t}, 500);\n\t\t} else if (msg == 'exit') {\n\t\t\tprocess.exit();\n\t\t}\n\t});\n}\n\nfunction groupSuicide() {\n\tif (cluster.isMaster) {\n\t\tfor (var id in cluster.workers) {\n\t\t    cluster.workers[id].send({ msg: 'exit'});\n\t\t    cluster.workers[id].destroy();\n\t\t}\n\t\tprocess.exit();\n\t}\n}\n```\n\n**Output:**\n```\n[Master] Typeof buf: Buffer Typeof arr: Float32Array\n[Worker] Typeof buf: Buffer Typeof arr: Float32Array\n0 [Master] Set buf[0]= 2  arr[0]= 5\n0 [Worker] Get buf[0]= 2  arr[0]= 5\n1 [Master] Set buf[0]= 3  arr[0]= 2.5\n1 [Worker] Get buf[0]= 3  arr[0]= 2.5\n2 [Master] Set buf[0]= 4  arr[0]= 1.25\n2 [Worker] Get buf[0]= 4  arr[0]= null\n3 [Master] Set buf[0]= 5  arr[0]= 0.625\n3 [Worker] Get buf[0]= 5  arr[0]= null\n4 [Master] Set buf[0]= 6  arr[0]= 0.3125\nshm segments destroyed: 2\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fukrbublik%2Fshm-typed-array","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fukrbublik%2Fshm-typed-array","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fukrbublik%2Fshm-typed-array/lists"}