{"id":13822455,"url":"https://github.com/Voultapher/self_cell","last_synced_at":"2025-05-16T17:30:54.238Z","repository":{"id":41248872,"uuid":"319437361","full_name":"Voultapher/self_cell","owner":"Voultapher","description":"Safe-to-use proc-macro-free self-referential structs in stable Rust.","archived":false,"fork":false,"pushed_at":"2025-04-11T11:19:52.000Z","size":232,"stargazers_count":261,"open_issues_count":1,"forks_count":17,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-14T15:08:59.980Z","etag":null,"topics":["ast","erasure","lifetime","referential-structs","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/Voultapher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2020-12-07T20:33:35.000Z","updated_at":"2025-05-14T02:06:53.000Z","dependencies_parsed_at":"2023-01-23T22:46:02.479Z","dependency_job_id":"1af65ddc-8ec0-4581-89df-1a865f6d9c5f","html_url":"https://github.com/Voultapher/self_cell","commit_stats":{"total_commits":106,"total_committers":4,"mean_commits":26.5,"dds":"0.10377358490566035","last_synced_commit":"ca7ca07229525aeff8dbe3922c64d576b16d5339"},"previous_names":["voultapher/once_self_cell"],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voultapher%2Fself_cell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voultapher%2Fself_cell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voultapher%2Fself_cell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voultapher%2Fself_cell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Voultapher","download_url":"https://codeload.github.com/Voultapher/self_cell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254576399,"owners_count":22094363,"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":["ast","erasure","lifetime","referential-structs","rust"],"created_at":"2024-08-04T08:02:00.911Z","updated_at":"2025-05-16T17:30:54.232Z","avatar_url":"https://github.com/Voultapher.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"[\u003cimg alt=\"github\" src=\"https://img.shields.io/badge/github-self__cell-8da0cb?style=for-the-badge\u0026logo=github\" height=\"20\"\u003e](https://github.com/Voultapher/self_cell)\n[\u003cimg alt=\"crates.io\" src=\"https://img.shields.io/badge/dynamic/json?color=fc8d62\u0026label=crates.io\u0026query=%24.crate.max_version\u0026url=https%3A%2F%2Fcrates.io%2Fapi%2Fv1%2Fcrates%2Fself_cell\u0026style=for-the-badge\u0026logo=rust\" height=\"20\"\u003e](https://crates.io/crates/self_cell)\n[\u003cimg alt=\"docs.rs\" src=\"https://img.shields.io/badge/docs.rs-self__cell-66c2a5?style=for-the-badge\u0026logoColor=white\u0026logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K\" height=\"20\"\u003e](https://docs.rs/self_cell)\n\n# `self_cell!`\n\nUse the macro-rules macro: `self_cell!` to create safe-to-use self-referential\nstructs in stable Rust, without leaking the struct internal lifetime.\n\nIn a nutshell, the API looks *roughly* like this:\n\n```rust\n// User code:\n\nself_cell!(\n    struct NewStructName {\n        owner: Owner,\n\n        #[covariant]\n        dependent: Dependent,\n    }\n    \n    impl {Debug}\n);\n\n// Generated by macro:\n\nstruct NewStructName(...);\n\nimpl NewStructName {\n    fn new(\n        owner: Owner,\n        dependent_builder: impl for\u003c'a\u003e FnOnce(\u0026'a Owner) -\u003e Dependent\u003c'a\u003e\n    ) -\u003e NewStructName { ... }\n    fn borrow_owner\u003c'a\u003e(\u0026'a self) -\u003e \u0026'a Owner { ... }\n    fn borrow_dependent\u003c'a\u003e(\u0026'a self) -\u003e \u0026'a Dependent\u003c'a\u003e { ... }\n    [...]\n    // See the macro level documentation for a list of all generated functions\n    // and other possible options, e.g. async builder support,\n    // https://docs.rs/self_cell/latest/self_cell/macro.self_cell.html#generated-api.\n}\n\nimpl Debug for NewStructName { ... }\n```\n\nSelf-referential structs are currently not supported with safe vanilla Rust. The\nonly reasonable safe alternative is to expect the user to juggle 2 separate data\nstructures which is a mess. The library solution ouroboros is expensive to\ncompile due to its use of procedural macros.\n\nThis alternative is `no_std`, uses no proc-macros, some self contained unsafe\nand works on stable Rust, and is miri tested. With a total of less than 300\nlines of implementation code, which consists mostly of type and trait\nimplementations, this crate aims to be a good minimal solution to the problem of\nself-referential structs.\n\nIt has undergone [community code review](https://users.rust-lang.org/t/experimental-safe-to-use-proc-macro-free-self-referential-structs-in-stable-rust/52775)\nfrom experienced Rust users.\n\n### Fast compile times\n\n```\n$ rm -rf target \u0026\u0026 cargo +nightly build -Z timings\n\nCompiling self_cell v0.9.0\nCompleted self_cell v0.9.0 in 0.2s\n```\n\nBecause it does **not** use proc-macros, and has 0 dependencies compile-times\nare fast.\n\nMeasurements done on a slow laptop.\n\n### A motivating use case\n\n```rust\nuse self_cell::self_cell;\n\n#[derive(Debug, Eq, PartialEq)]\nstruct Ast\u003c'a\u003e(pub Vec\u003c\u0026'a str\u003e);\n\nself_cell!(\n    struct AstCell {\n        owner: String,\n\n        #[covariant]\n        dependent: Ast,\n    }\n\n    impl {Debug, Eq, PartialEq}\n);\n\nfn build_ast_cell(code: \u0026str) -\u003e AstCell {\n    // Create owning String on stack.\n    let pre_processed_code = code.trim().to_string();\n\n    // Move String into AstCell, then build Ast inplace.\n    AstCell::new(\n        pre_processed_code,\n        |code| Ast(code.split(' ').filter(|word| word.len() \u003e 1).collect())\n    )\n}\n\nfn main() {\n    let ast_cell = build_ast_cell(\"fox = cat + dog\");\n\n    println!(\"ast_cell -\u003e {:?}\", \u0026ast_cell);\n    println!(\"ast_cell.borrow_owner() -\u003e {:?}\", ast_cell.borrow_owner());\n    println!(\"ast_cell.borrow_dependent().0[1] -\u003e {:?}\", ast_cell.borrow_dependent().0[1]);\n}\n```\n\n```\n$ cargo run\n\nast_cell -\u003e AstCell { owner: \"fox = cat + dog\", dependent: Ast([\"fox\", \"cat\", \"dog\"]) }\nast_cell.borrow_owner() -\u003e \"fox = cat + dog\"\nast_cell.borrow_dependent().0[1] -\u003e \"cat\"\n```\n\nThere is no way in safe Rust to have an API like `build_ast_cell`, as soon as\n`Ast` depends on stack variables like `pre_processed_code` you can't return the\nvalue out of the function anymore. You could move the pre-processing into the\ncaller but that gets ugly quickly because you can't encapsulate things anymore.\nNote this is a somewhat niche use case, self-referential structs should only be\nused when there is no good alternative.\n\nUnder the hood, it heap allocates a struct which it initializes first by moving\nthe owner value to it and then using the reference to this now Pin/Immovable\nowner to construct the dependent inplace next to it. This makes it safe to move\nthe generated SelfCell but you have to pay for the heap allocation.\n\nSee the documentation for a more in-depth API overview and advanced examples:\nhttps://docs.rs/self_cell\n\n### Installing\n\n[See cargo docs](https://doc.rust-lang.org/cargo/guide/).\n\n## Running the tests\n\n```\ncargo test\n\ncargo miri test\n```\n\n### Related projects\n\n- [ouroboros](https://github.com/joshua-maros/ouroboros)\n- [rental](https://github.com/jpernst/rental) | soundness issues (tests fail with recent miri versions) and [deprecated](https://github.com/jpernst/rental#warning-this-crate-is-no-longer-maintained-or-supported)\n- [Schroedinger](https://github.com/dureuill/sc) | [soundness issues](https://github.com/dureuill/sc/issues/1)\n- [owning_ref](https://github.com/Kimundi/owning-ref-rs) | [soundness issues](https://rustsec.org/advisories/RUSTSEC-2022-0040.html) and [seems unmaintained](https://github.com/Kimundi/owning-ref-rs/issues/81)\n- [ghost-cell](https://github.com/matthieu-m/ghost-cell)\n- [qcell](https://github.com/uazu/qcell/)\n- [selfref](https://docs.rs/selfref)\n\n## Min required rustc version\n\nBy default the minimum required rustc version is 1.51.\n\nThere is an optional feature you can enable called \"old_rust\" that enables\nsupport down to rustc version 1.36. However this requires polyfilling std\nlibrary functionality for older rustc with technically UB versions. Testing does\nnot show older rustc versions (ab)using this. Use at your own risk.\n\nUsing the `async_builder` option requires Rust 1.85 or newer.\n\nThe minimum versions are best-effort and may change with any new major release.\n\n## Contributing\n\nPlease respect the [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) when contributing.\n\n## Versioning\n\nWe use [SemVer](http://semver.org/) for versioning. For the versions available,\nsee the [tags on this repository](https://github.com/Voultapher/self_cell/tags).\n\n## Authors\n\n* **Lukas Bergdoll** - *Initial work* - [Voultapher](https://github.com/Voultapher)\n\nSee also the list of [contributors](https://github.com/Voultapher/self_cell/contributors)\nwho participated in this project.\n\n## License\n\nThis project is licensed under the Apache License, Version 2.0 -\nsee the [LICENSE.md](LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVoultapher%2Fself_cell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVoultapher%2Fself_cell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVoultapher%2Fself_cell/lists"}