{"id":29164981,"url":"https://github.com/antonymei/sharedmemoryobjectstore","last_synced_at":"2025-07-01T07:08:46.695Z","repository":{"id":56933813,"uuid":"431392875","full_name":"AntonyMei/SharedMemoryObjectStore","owner":"AntonyMei","description":"A high throughput low latency shared memory object store specially optimized for RL. ","archived":false,"fork":false,"pushed_at":"2022-10-12T11:01:36.000Z","size":217,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-30T13:49:16.168Z","etag":null,"topics":["interprocess-communication-library","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AntonyMei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-24T07:50:37.000Z","updated_at":"2025-02-10T20:37:00.000Z","dependencies_parsed_at":"2022-08-21T00:40:20.116Z","dependency_job_id":null,"html_url":"https://github.com/AntonyMei/SharedMemoryObjectStore","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AntonyMei/SharedMemoryObjectStore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonyMei%2FSharedMemoryObjectStore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonyMei%2FSharedMemoryObjectStore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonyMei%2FSharedMemoryObjectStore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonyMei%2FSharedMemoryObjectStore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AntonyMei","download_url":"https://codeload.github.com/AntonyMei/SharedMemoryObjectStore/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AntonyMei%2FSharedMemoryObjectStore/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262916681,"owners_count":23383889,"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":["interprocess-communication-library","python3"],"created_at":"2025-07-01T07:08:45.227Z","updated_at":"2025-07-01T07:08:46.668Z","avatar_url":"https://github.com/AntonyMei.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SMOS\n\n## Introduction to SMOS\nSMOS is a lightweight shared memory object store written in Python, featuring high throughput and low latency.\nIt is specially optimized for reinforcement learning scenarios, where processes write large chunks of NumPy arrays\nonce but read them multiple times. SMOS can provide concurrent reads and writes of NumPy arrays with full RAM speeds\nfrom more than 64 processes (i.e., it has very little control overheads). The high efficiency of SMOS comes in the\ntwo ways, as shown in section ***Technical Details***.\n\n## Installation\nSMOS has been released as a python package to PyPI. It supports python\u003e3.8 on Linux. To install SMOS, simply run:\n\n    pip install SMOS_antony\n\n## Usage\n### A Hello World Example of Interprocess Communication with SMOS\nStep 1: Start the SMOS server. Note that `server.start()` will run the server in a separate process\nand is non-blocking.\n\n    import SMOS\n    import time\n\n    try:\n        server = SMOS.Server(SMOS.ConnectionDescriptor(ip=\"localhost\", port=12345, authkey=b\"some_key\"))\n        server.start()\n        while True:\n            time.sleep(1)\n    except KeyboardInterrupt:\n        server.stop()\n\nStep 2: Start a process that sends message:\n   \n    import SMOS\n\n    client = SMOS.Client(SMOS.ConnectionDescriptor(ip=\"localhost\", port=12345, authkey=b\"some_key\"))\n    client.put(name=\"test_obj\", data=\"Hello World!\")\n\nStep 3: Start a process that reads message:\n\n    import SMOS\n\n    client = SMOS.Client(SMOS.ConnectionDescriptor(ip=\"localhost\", port=12345, authkey=b\"some_key\"))\n    msg = client.get(name=\"test_obj\")\n    print(msg)\n\nStep 4: The message can be read by different processes multiple times until some process calls the following\ncommand to delete the underlying shared memory object:\n\n    client.remove_object(name=\"test_obj\")\n\n### Advanced Usages\nHere we show advanced APIs of SMOS. We plan to make this section into a separate documentation website with later\nmajor releases. First, we give a general descriptions about the possible workflows with SMOS. There are two general\nworkflows with shared memory objects. The two workflows are compatible with each other.\n\n    workflow 1:  create_object  -\u003e  [entry operations]  -\u003e  remove_object\n    workflow 2:  put            -\u003e  (multiple) get\n\nEach shared memory object can also be used as a shared memory queue (array, FIFO, whatever you call it) and support\nthe following entry operations:\n\n - fine-grained operations (zero copy)\n\n       create procedure:  create_entry  -\u003e  open_shm  -\u003e  commit_entry\n       r/w procedure:     open_entry    -\u003e  open_shm  -\u003e  release_entry\n       delete procedure:  delete_entry\n    \n - coarse-grained operations (queue API)\n   \n       write process: push_to_object\n       read process:  pop_from_object          -\u003e  free_handle\n                      read_from_object         -\u003e  release_entry\n                      read_latest_from_object  -\u003e  release_entry\n                      batch_read_from_object   -\u003e  batch_release_entry\n\nFor detailed usage of each function, you can refer to `/src/SMOS_client.py`. We plan to set up a website for documentation\nof SMOS in the future.\n\n## Technical Details\n\n### Four Stage Transition model\n![Four stage transition model](./static/fig_trans.png \"Four stage transition model.\")\n\nSMOS is based on the four stage transition model shown above.\n1. When a process issues a create-new-block command to the centralized SMOS server, it will get a new shared memory block \n   only visible to itself. The block it gets will be in `write` state. The process can write into the block whatever it likes.\n   \n2. Once the writer decides that all work is done with the block, it can issue a commit-to-public command to the SMOS server.\n   After this command, the block will be visible to everyone on the same machine. Now the block is in `idle` state,\n   since we have no pending readers on the block.\n\n3. When a reader process wants the data from a particular block, it issues a request-data command to the SMOS server\n   and will be replied with a handle to the target block. This command also makes the block `busy`.\n   \n4. After all readers finish the work with the block and release their handles, the block will return to `idel` state. \n   Stage 3 and 4 can happen multiple times during the whole lifespan of a block.\n   \n5. Once the block is no longer needed by anyone, some clean up process can issue a delete command (or force delete)\n   that turns the block into a `zombie`. Note that SMOS does not delete the actual data on the block. Becoming a \n   `zombie` only means that the block ceases to be visible to processes other than the SMOS server.\n   \n6. The SMOS server will reuse and dispatch the `zombie` blocks to writers when they issue create-new-block commands.\n\nThis four stage design enables the underlying buffer to be lock-free. For any operation, the server critical path\nonly contains manipulation of meta-data, enabling very low control overhead.\n\n**Special Notice:** Readers can still write to the blocks when they hold the handles in stage 3, but SMOS does not\nprovide data integrity guarantees for this kind of write operations. If this kind of writes are necessary, consider\nadding a buffer lock on the 'reader' side. (SMOS provides an implementation of read-write fair lock in `src/SMOS_utils.py`)\n\n### Special Optimizations for NumPy Arrays\nSMOS is an interprocess communication tool with special optimizations for reinforcement learning (RL) scenarios.\nWe recognize that the data pattern of RL contains (1) single write and multiple reads of large NumPy arrays\n, and (2) sharing of small complicated class objects. To address the first type of communication, we support\ndirect shared memory read of NumPy arrays in SMOS. NumPy arrays (or lists of NumPy arrays) can be passed between\nprocesses without serialization and memory copy. To address the second type of communication, we add intrinsic\npickle and unpickle operations to objects with user defined class types. We tackle the two kinds of data differently,\nwhich gives us better performance and broad data support range.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonymei%2Fsharedmemoryobjectstore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantonymei%2Fsharedmemoryobjectstore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonymei%2Fsharedmemoryobjectstore/lists"}