{"id":13599861,"url":"https://github.com/kyren/gc-arena","last_synced_at":"2025-05-15T09:06:38.304Z","repository":{"id":34865389,"uuid":"185483706","full_name":"kyren/gc-arena","owner":"kyren","description":"Incremental garbage collection from safe Rust","archived":false,"fork":false,"pushed_at":"2025-03-27T04:17:49.000Z","size":489,"stargazers_count":679,"open_issues_count":13,"forks_count":46,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-14T15:00:40.376Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kyren.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-CC0","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,"zenodo":null}},"created_at":"2019-05-07T21:58:25.000Z","updated_at":"2025-04-14T02:27:34.000Z","dependencies_parsed_at":"2023-02-12T18:30:34.989Z","dependency_job_id":"ad812cae-69a8-46a1-b906-5cd7ddb2efa9","html_url":"https://github.com/kyren/gc-arena","commit_stats":{"total_commits":119,"total_committers":10,"mean_commits":11.9,"dds":0.6050420168067228,"last_synced_commit":"c8270f5591443e2d0524b45ae5439a6c34120632"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kyren%2Fgc-arena","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kyren%2Fgc-arena/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kyren%2Fgc-arena/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kyren%2Fgc-arena/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kyren","download_url":"https://codeload.github.com/kyren/gc-arena/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310515,"owners_count":22049469,"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-08-01T17:01:14.186Z","updated_at":"2025-05-15T09:06:38.268Z","avatar_url":"https://github.com/kyren.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"[![crates.io](https://img.shields.io/crates/v/gc-arena)](https://crates.io/crates/gc-arena)\n[![docs.rs](https://docs.rs/gc-arena/badge.svg)](https://docs.rs/gc-arena)\n[![Build Status](https://img.shields.io/circleci/project/github/kyren/gc-arena.svg)](https://circleci.com/gh/kyren/gc-arena)\n\n## gc-arena\n\nThis repo is home to the `gc-arena` crate, which provides Rust with garbage\ncollected arenas and a means of safely interacting with them.\n\nThe `gc-arena` crate, along with its helper crate `gc-arena-derive`, provides\nallocation with safe, incremental, exact, cycle-detecting garbage collection\nwithin a closed \"arena\". There are two techniques at play that make this system\nsound:\n\n* Garbage collected objects are traced using the `Collect` trait, which must\n  be implemented correctly to ensure that all reachable objects are found. This\n  trait is therefore `unsafe`, but it *can* safely be implemented by procedural\n  macro, and the `gc-arena-derive` provides such a safe procedural macro.\n\n* In order for garbage collection to take place, the garbage collector must\n  first have a list of \"root\" objects which are known to be reachable. In our\n  case, the user of `gc-arena` chooses a single root object for the arena, but\n  this is not sufficient for safe garbage collection. If garbage collection\n  were to take place when there are garbage collected pointers anywhere on the\n  Rust stack, such pointers would also need to be considered as \"root\" objects\n  to prevent memory unsafety. `gc-arena` solves this by strictly limiting where\n  garbage collected pointers can be stored, and when they can be alive. The\n  arena can only be accessed through a single `mutate` method which takes a\n  callback, and all garbage collected pointers inside this callback are branded\n  with an invariant lifetime which is unique to that single callback call. Thus,\n  when outside of this `mutate` method, the rust borrow checker ensures that\n  it is not possible for garbage collected pointers to be alive anywhere on\n  the stack, nor is it possible for them to have been smuggled outside of the\n  arena's root object. Since all pointers can be proven to be reachable from the\n  single root object, safe garbage collection can take place.\n  \nIn other words, the `gc-arena` crate does *not* retrofit Rust with a globally\naccessible garbage collector, rather it *only* allows for limited garbage\ncollection in isolated garbage collected arenas. All garbage collected pointers\nmust forever live inside only this arena, and pointers from different arenas are\nprevented from being stored in the wrong arena.\n\nSee [this blog post](https://kyju.org/blog/rust-safe-garbage-collection/) for a\nmore in-depth tour of the crate's design. It is quite dense, but it explains\neverything necessary to fully understand the machinery used in the included\n[linked list example](examples/linked_list.rs).\n\n## Use cases\n\nThis crate was developed primarily as a means of writing VMs for garbage\ncollected languages in safe Rust, but there are probably many more uses than\njust this.\n\n## Current status and TODOs\n\nBasically usable and safe! It is used by the Adobe Flash Player emulator\n[Ruffle](https://github.com/ruffle-rs/ruffle) for its ActionScript VM as well\nas some other projects (like my own stackless Lua runtime\n[piccolo](https://github.com/kyren/piccolo), for which the crate was originally\ndesigned)\n\nThe collection algorithm is an incremental mark-and-sweep algorithm very similar\nto the one in PUC-Rio Lua, and is optimized primarily for low pause time. During\nmutation, allocation \"debt\" is accumulated, and this \"debt\" determines the\namount of work that the next call to `Arena::collect` will do.\n\nThe pointers held in arenas (spelled `Gc\u003c'gc, T\u003e`) are zero-cost raw pointers.\nThey implement `Copy` and are pointer sized, and no bookkeeping at all is done\nduring mutation. \n\nSome notable current limitations:\n\n* Allocating DSTs is currently somewhat painful due to limitations in Rust. It\n  is possible to  have `Gc` pointers to DSTs, and there is a replacement for\n  unstable `Unsize` coercion, but there is no support for directly allocating\n  arbitrarily sized DSTs.\n\n* There is no support at all for multi-threaded allocation and collection.\n  The basic lifetime and safety techniques here would still work in an arena\n  supporting multi-threading, but this crate does not support this. It is\n  optimized for single threaded use and multiple, independent arenas.\n  \n* The `Collect` trait does not provide a mechanism to move objects once they are\n  allocated, so this limits the types of collectors that could be written. This\n  is achievable but no work has been done towards this.\n\n## Prior Art\n\nThe ideas here are mostly not mine. Much of the user-facing design is borrowed\nheavily from [rust-gc](\nhttps://manishearth.github.io/blog/2015/09/01/designing-a-gc-in-rust/),\nand the idea of using \"generativity\" comes from [You can't spell trust without\nRust](https://raw.githubusercontent.com/Gankro/thesis/master/thesis.pdf). The\ndesign of the actual garbage collection system itself borrows heavily from the\nincremental mark-and-sweep collector in Lua 5.4.\n\n## License\n\nEverything in this repository is licensed under either of:\n\n* MIT license [LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT\n* Creative Commons CC0 1.0 Universal Public Domain Dedication\n  [LICENSE-CC0](LICENSE-CC0) or\n  https://creativecommons.org/publicdomain/zero/1.0/\n\nat your option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkyren%2Fgc-arena","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkyren%2Fgc-arena","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkyren%2Fgc-arena/lists"}