{"id":19705854,"url":"https://github.com/llnl/umap","last_synced_at":"2025-05-06T20:44:56.226Z","repository":{"id":22276243,"uuid":"95720536","full_name":"LLNL/umap","owner":"LLNL","description":"User-space Page Management","archived":false,"fork":false,"pushed_at":"2024-08-09T16:00:42.000Z","size":72748,"stargazers_count":107,"open_issues_count":6,"forks_count":25,"subscribers_count":14,"default_branch":"develop","last_synced_at":"2025-04-12T05:03:46.853Z","etag":null,"topics":["cpp"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LLNL.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"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}},"created_at":"2017-06-28T23:41:24.000Z","updated_at":"2025-03-30T00:43:50.000Z","dependencies_parsed_at":"2024-08-09T01:12:32.322Z","dependency_job_id":"9669f595-74f1-4340-b2d0-977451f4da72","html_url":"https://github.com/LLNL/umap","commit_stats":{"total_commits":344,"total_committers":17,"mean_commits":"20.235294117647058","dds":"0.44476744186046513","last_synced_commit":"cfdcd3d4a05ca3db1cc6faa547ae1e588a32ea1c"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2Fumap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2Fumap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2Fumap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LLNL%2Fumap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LLNL","download_url":"https://codeload.github.com/LLNL/umap/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252769127,"owners_count":21801373,"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":["cpp"],"created_at":"2024-11-11T21:30:56.847Z","updated_at":"2025-05-06T20:44:56.184Z","avatar_url":"https://github.com/LLNL.png","language":"C++","readme":"# UMAP v2.1.0\n\n[![Travis Build Status](https://travis-ci.com/LLNL/umap.svg?branch=develop)](https://travis-ci.com/LLNL/umap)\n[![Documentation Status](https://readthedocs.org/projects/llnl-umap/badge/?version=develop)](https://llnl-umap.readthedocs.io/en/develop/?badge=develop)\n\nUmap is a library that provides an mmap()-like interface to a simple, user-\nspace page fault handler based on the userfaultfd Linux feature (starting with\n4.3 linux kernel). The use case is to have an application specific buffer of\npages cached from a large file, i.e. out-of-core execution using memory map.\n\nThe src directory in the top level contains the source code for the library.\n\nThe tests directory contains various tests written to test the library\nincluding a hello world program for userfaultfd based upon code from the\n[userfaultfd-hello-world project](http://noahdesu.github.io/2016/10/10/userfaultfd-hello-world.html).\n\n`LLNL-CODE-733797`\n\n## Quick Start\n\n*Building umap* is trivial. In the root directory of the repo\n\n```bash\nmkdir build\ncd build\ncmake -DCMAKE_INSTALL_PREFIX=\u003cwhere you want the sofware\u003e ..\nmake install\n```\n\nThe default for cmake is to build a Debug version of the software.  If you\nwould like to build an optimized (-O3) version, simply run \n```bash\ncmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=\u003cinstall-dir\u003e ..\n```\n\n### Docker Container\nThere is a `Dockerfile` included in the repository to make it easier to build a container image with a basic Umap development environment.\n\nA few caveats:\nThe [runtime requirements](#runtime-requirements) of the Docker container are the same as the non-containerized Umap. Additionally, it's important to note that Umap checks the kernel headers present in the build-time environment to decide whether or not WP mode should be enabled. The included `Dockerfile` will always build Umap with WP support enabled because the Ubuntu 22.04 kernel headers included in the the container indicate that WP is supported, even if the host kernel doesn't actually support that feature. Umap will return an error at runtime if it's built with WP enabled but run on a kernel without WP support.\n\nDocker, as a security measure, uses a `seccomp` profile to restrict the syscalls allowed to be made by an application running inside a container to a minimal subset. Umap relies on being able to make host kernel syscalls that are otherwise blocked by Docker's default `seccomp` profile. Specifically, Umap relies on the `userfaultfd` syscall. See [here](https://docs.docker.com/engine/security/seccomp/#significant-syscalls-blocked-by-the-default-profile]) for more information about which syscalls are blocked by Docker's default `seccomp` profile.\n\n#### Example: Building and running the Umap Docker container\n```bash\ndocker build -t umap .\ndocker run --security-opt seccomp=unconfined -it umap bash\n```\n\n#### Example: Running the Umap container with a `seccomp` whitelist\nIt's also possible to run the container with a `seccomp` whitelist rather than disabling confinement entirely.\nFirst, create a `userfaultfd.json` file:\n```json\n{\"names\": [\"userfaultfd\"], \"action\": \"SCMP_ACT_ALLOW\"}\n```\n\nWhen running the container:\n```bash\ndocker run --security-opt seccomp=userfaultfd.json -it umap bash\n```\n\n## Build Requirements\nBuilding Umap requires a C++ compiler, CMake \u003e= 3.5.1, as well as the Linux kernel headers.\n\nAdditionally, Umap will automatically enable read/write mode *at library compile time* if it detects that the installed kernel supports it by looking at the defined symbols in the kernel headers. Some Linux distributions, such as Ubuntu 20.04.2, provide a 5.8 kernel that supports read/write mode but don't ship with headers that define these symbols.\n\nRead-only mode: Linux kernel \u003e= 4.3\n\nRead/write mode: Linux kernel \u003e= 5.7 (\u003e= 5.10 preferred)\n\nNote: Some early mainline releases of Linux that included support for read/write mode (between 5.7 and 5.9) contain a known bug that causes an application to hang indefinitely when performing a write. It's recommended to update to a 5.10 kernel if this bug is encountered.\n\n## Runtime Requirements\nAt runtime, Umap requires a kernel that supports the same features as it was built against. For example, running a version of Umap compiled against kernel 5.10 on a system with kernel 4.18 will result in runtime errors caused by write functionality not being present in the 4.18 kernel.\n\nOn Linux \u003e= 5.4, the `sysctl` variable `vm.unprivileged_userfaultfd` needs to be set to `1` in order to use Umap in both read-only and read/write modes as a non-root user. The value of this variable may be determined by running `sysctl vm.unprivileged_userfaultfd` or `cat /proc/sys/vm/unprivileged_userfaultfd`.\n\n## Applications\n\nApplications can be found at https://github.com/LLNL/umap-apps. \n\n## Documentation\n\nBoth user and code documentation is available\n[here](http://llnl-umap.readthedocs.io/).\n\nIf you have build problems, we have comprehensive\n[build sytem documentation](https://llnl-umap.readthedocs.io/en/develop/advanced_configuration.html) too!\n\n## Publications\n\n```Peng, I.B., Gokhale, M., Youssef, K., Iwabuchi, K. and Pearce, R., 2021. Enabling Scalable and Extensible Memory-mapped Datastores in Userspace. IEEE Transactions on Parallel and Distributed Systems. doi: 10.1109/TPDS.2021.3086302.```\n\n```Peng, I.B., McFadden, M., Green, E., Iwabuchi, K., Wu, K., Li, D., Pearce, R. and Gokhale, M., 2019, November. UMap: Enabling application-driven optimizations for page management. In 2019 IEEE/ACM Workshop on Memory Centric High Performance Computing (MCHPC) (pp. 71-78). IEEE.```\n\n## License\n\n- The license is [LGPL](/LICENSE).\n- [thirdparty_licenses.md](/thirdparty_licenses.md)\n\n## Contact\n\n- Ivy Peng  (ivybopeng@gmail.com)\n- Maya Gokhale (gokhale2@llnl.gov)\n- Eric Green (green77@llnl.gov)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllnl%2Fumap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fllnl%2Fumap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllnl%2Fumap/lists"}