{"id":21273487,"url":"https://github.com/graphaware/offheap","last_synced_at":"2025-07-11T06:33:16.450Z","repository":{"id":57724720,"uuid":"122929881","full_name":"graphaware/offheap","owner":"graphaware","description":null,"archived":false,"fork":false,"pushed_at":"2018-02-26T18:11:09.000Z","size":17434,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-06T01:06:40.402Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/graphaware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-26T07:23:02.000Z","updated_at":"2020-02-01T10:39:52.000Z","dependencies_parsed_at":"2022-09-11T01:32:27.431Z","dependency_job_id":null,"html_url":"https://github.com/graphaware/offheap","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/graphaware/offheap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphaware%2Foffheap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphaware%2Foffheap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphaware%2Foffheap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphaware%2Foffheap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphaware","download_url":"https://codeload.github.com/graphaware/offheap/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphaware%2Foffheap/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264748126,"owners_count":23657971,"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":[],"created_at":"2024-11-21T09:15:01.037Z","updated_at":"2025-07-11T06:33:16.184Z","avatar_url":"https://github.com/graphaware.png","language":"Java","readme":"# JVM off-heap maps and cache library\n\nThe components in the OffHeap library allow processes running in different JVMs on the same machine to share data using off-heap memory structures.\n\n---\n\n## SharedMapCacheManager\n\nA Spring-compatible CacheManager:\n\n```\n@Configuration\n@EnableCaching\npublic class CacheConfig {\n\n    public static final String[] CACHE_NAMES = {\"users\", \"profiles\"};\n\n    @Bean\n    public CacheManager cacheManager() {\n        return new SharedMapCacheManager(CACHE_NAMES);\n    }\n\n}\n```\n\n---\n\n## SharedOffHeapMap\n\nA shared off heap memory map that acts as the underlying store for a `SharedMapCacheManager`. \n\nThis map allows multiple processes (e.g in different JVMs) running on a single machine to access a common map via shared memory. The map is persisted to disk via a memory-mapped file.\n\nThe map stores all its entries off-heap, which eliminates GC pressure and allows the map's size to be larger than the amount of available physical memory. Note that for best performance, the map should not be larger than twice the amount of main memory.\n\nTo use a `SharedOffHeapMap`, clients must agree on the file name the map uses, and the max number of entries it should hold:\n\n\n```\n// creates a named file in the temp directory, which will persist until the server is rebooted\nMap\u003cKey, Value\u003e sharedMap = new SharedOffHeapMap(new File(System.getProperty(\"java.io.tmpdir\"), \"test.dat\"), 10_000);\n``` \n\n*Warning: this map will not grow*. You need to know approximately the number of entries you want to hold in it before creating it. It is therefore ideal for using as a shared cache implementation for processes running on the same machine. \n\nIf you need an off-heap map that can grow arbitrarily, see the next section\n\n---\n\n## OffHeapMap\n\nA map that stores all its entries off-heap. The entries in this map cannot be shared with other processes, but unlike the `SharedOffHeapMap` this map will grow as required.\n\nAn `OffHeapMap` is created with a number of partitions. For optimum performance, the number of partitions should be around 10% of the maximum number of entries the map is expected to hold:\n\n```\n// create a map with 10k partitions, which is efficient for storing approximately 100k Key-Value pairs.\nMap\u003cKey, Value\u003e offHeapMap = new OffHeapMap(10_000);\n```\n\n---\n\n## Constraints\n\nIn both maps keys must be Strings, and null keys are not supported. Values can be any type, and again null values are not permitted. \n\n---\n\n## Key and Value types\n\nBoth maps implement `Map\u003cKey, Value\u003e`, where Key and Value are wrappers for your actual keys and values. The Key and Value classes perform serialisation and de-serialising of the keys and values in the map, so you don't need to. \n\n_To add an entry to the map_:\n \n```\nString key = \"friends\";\nList\u003cString\u003e value = Arrays.asList(\"phoebe\", \"rachel\", \"monica\", \"joey\", \"chandler\", \"ross\");\nmap.put(Key.of(key), Value.of(value))\n```\n\nHowever, if your key and value objects are already byte[] arrays, you do not need to create Key and Value wrappers.\n\n_To retrieve an entry from the map_:\n\n```\nList\u003cString\u003e friends = map.get(Key.of(\"friends\")).get();\n```\n\n---\n## Licensing\nOffHeap is licensed under the Apache 2.0 License. You should have received a copy of the license with this code. \n\n---\n\n## Acknowledgements\nInspiration, ideas and some code for this library have come from a number of open-source projects, including:\n\n- https://github.com/cfelde/BinaryOffheapHashMap\n- https://github.com/OpenHFT/Chronicle-Map \n\nThe SharedOffHeapMap currently uses a Chronicle map under the hood. \n\n---\n\n## Using the offheap library in your own projects\n\nReleases are published on Maven Central. The latest release version is 1.0.0\n\n```\n# maven example\n\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ecom.graphaware.offheap\u003c/groupId\u003e\n        \u003cartifactId\u003eoffheap\u003c/artifactId\u003e\n        \u003cversion\u003e1.0.0\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphaware%2Foffheap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphaware%2Foffheap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphaware%2Foffheap/lists"}