{"id":28962719,"url":"https://github.com/engali94/movable-ref","last_synced_at":"2025-08-11T17:33:37.906Z","repository":{"id":300624164,"uuid":"1006660097","full_name":"engali94/movable-ref","owner":"engali94","description":"A Rust library for offset based pointers that enable movable self-referential data structures.","archived":false,"fork":false,"pushed_at":"2025-06-22T20:12:49.000Z","size":37,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-22T20:15:41.644Z","etag":null,"topics":["pin","pointer","rust","self-refrence","smart"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/engali94.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T18:34:45.000Z","updated_at":"2025-06-22T20:14:37.000Z","dependencies_parsed_at":"2025-06-22T19:48:53.193Z","dependency_job_id":null,"html_url":"https://github.com/engali94/movable-ref","commit_stats":null,"previous_names":["engali94/tether","engali94/movable-ref"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/engali94/movable-ref","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engali94%2Fmovable-ref","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engali94%2Fmovable-ref/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engali94%2Fmovable-ref/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engali94%2Fmovable-ref/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/engali94","download_url":"https://codeload.github.com/engali94/movable-ref/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/engali94%2Fmovable-ref/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261595784,"owners_count":23182249,"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":["pin","pointer","rust","self-refrence","smart"],"created_at":"2025-06-24T03:11:51.832Z","updated_at":"2025-08-11T17:33:37.887Z","avatar_url":"https://github.com/engali94.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# movable-ref\n\n[![Crates.io](https://img.shields.io/crates/v/movable-ref.svg)](https://crates.io/crates/movable-ref)\n[![Documentation](https://docs.rs/movable-ref/badge.svg)](https://docs.rs/movable-ref)\n[![CI](https://github.com/engali94/movable-ref/workflows/CI/badge.svg)](https://github.com/engali94/movable-ref/actions)\n[![Ubuntu](https://img.shields.io/github/actions/workflow/status/engali94/movable-ref/ci.yml?branch=main\u0026label=Ubuntu\u0026logo=ubuntu)](https://github.com/engali94/movable-ref/actions)\n[![macOS](https://img.shields.io/github/actions/workflow/status/engali94/movable-ref/ci.yml?branch=main\u0026label=macOS\u0026logo=apple)](https://github.com/engali94/movable-ref/actions)\n[![Windows](https://img.shields.io/github/actions/workflow/status/engali94/movable-ref/ci.yml?branch=main\u0026label=Windows\u0026logo=windows)](https://github.com/engali94/movable-ref/actions)\n[![MSRV](https://img.shields.io/badge/MSRV-1.70+-blue.svg)](https://github.com/engali94/movable-ref/actions)\n\nA Rust library for **offset based pointers** that enable movable self-referential data structures.\n\n\n## The Problem\n\nStandard Rust cannot create self-referential structures that can be moved in memory:\n\n```rust\n// This is impossible in safe Rust\nstruct SelfRef\u003c'a\u003e {\n    data: String,\n    ptr: \u0026'a str,  // Cannot reference self.data\n}\n```\n\nExisting solutions have many limitations:\n- `Pin\u003cBox\u003cT\u003e\u003e`: Requires heap allocation, prevents movement.\n- `Rc\u003cRefCell\u003cT\u003e\u003e`: Runtime overhead, not `Send`/`Sync`\n- `ouroboros`: Complex macros, limited flexibility.\n\n## The Solution\n\nOffset pointers store **offsets** instead of absolute addresses, enabling self-referential structures that remain valid when moved:\n\n```rust\nuse movable_ref::SelfRef;\n\nstruct Node {\n    value: String,\n    self_ref: SelfRef\u003cString, i16\u003e,  // 2-byte offset instead of 8-byte pointer\n}\n\nimpl Node {\n    fn new(value: String) -\u003e Self {\n        let mut node = Self {\n            value,\n            self_ref: SelfRef::null(),\n        };\n        node.self_ref.set(\u0026mut node.value).unwrap();\n        node\n    }\n    \n    fn get_value(\u0026self) -\u003e \u0026str {\n        unsafe { self.self_ref.as_ref_unchecked() }\n    }\n}\n\n// This works! The structure can be moved anywhere\nlet node = Node::new(\"Hello\".to_string());\nlet boxed = Box::new(node);         // ✓ Moves to heap\nlet mut vec = Vec::new();\nvec.push(*boxed);                   // ✓ Moves again\nprintln!(\"{}\", vec[0].get_value()); // ✓ Still works!\n```\n\n## Why tether?\n\nOffset pointers solve a fundamental limitation in Rust: creating efficient, movable self-referential data structures. While other solutions exist, tether provides:\n\n1. **Embedded Systems Friendly**: Can run in very memory constrained devices. \n2. **Movement freedom**: Structures work on stack, heap, or anywhere unlike `Pin`\n3. **True zero-cost abstraction**: Zero to Minimal runtime overhead\n4. **Memory efficiency**: 1-8 bytes vs 8+ bytes for alternatives  \n5. **Simplicity**: Straightforward API without complex macros\n\nPerfect for performance-critical applications, embedded systems, and anywhere you need self-referential structures that can move.\n\n## Installation\n\nAdd to your `Cargo.toml`:\n\n```toml\n[dependencies]\nmovable-ref = \"0.1.0\"\n```\n\n## Basic Usage\n\n```rust\nuse movable_ref::SelfRef;\n\n// 1. Create structure with null pointer\nlet mut data = MyStruct {\n    value: \"Hello\".to_string(),\n    ptr: SelfRef::null(),\n};\n\n// 2. Set the relative pointer\ndata.ptr.set(\u0026mut data.value).unwrap();\n\n// 3. Dereference the pointer\nlet reference: \u0026str = unsafe { data.ptr.as_ref_unchecked() };\n```\n\n## Features\n\n- **`no_std`**: Works in embedded environments (disable default `std` feature)\n- **`nightly`**: Trait object support with nightly Rust\n\n```toml\n[dependencies]\nmovable-ref = { version = \"0.1.0\", default-features = false }\n```\n## Performance Benchmarks\n\nRun `cargo bench` to see these results on your machine:\n\n### 🚀 **Access Speed** (lower = faster)\n```\nDirect Access:   329ps  (baseline)\nSelfRef:         331ps  ⭐ FASTEST\nPin\u003cBox\u003cT\u003e\u003e:     365ps  (+10% slower)\nRc\u003cRefCell\u003cT\u003e\u003e:  429ps  (+30% slower)\n```\n\n### 💾 **Memory Efficiency**\n```\nSelfRef\u003cT, i8\u003e:   1 byte  (±127 byte range)\nSelfRef\u003cT, i16\u003e:  2 bytes (±32KB range)  \nSelfRef\u003cT, i32\u003e:  4 bytes (±2GB range)\n*const T:         8 bytes (full address space)\nRc\u003cRefCell\u003cT\u003e\u003e:   8 bytes + heap allocation\n```\n\n### ⚡ **Creation Speed**\n```\nDirect:           19ns   (baseline)\nSelfRef:          38ns   (+100% but still fastest)\nRc\u003cRefCell\u003cT\u003e\u003e:   40ns   \nPin\u003cBox\u003cT\u003e\u003e:      46ns   \n```\n\n### 🔄 **Move Semantics**\n```\nDirect move:      49ns   \nRc\u003cRefCell\u003cT\u003e\u003e:   50ns   (clone, not true move)\nSelfRef move:     58ns   ⭐ __TRUE MOVE SEMANTICS__\nPin\u003cBox\u003cT\u003e\u003e:      N/A    (cannot move!)\n```\n\n**Key Takeaways:**\n- ✅ **Zero-cost abstraction**: SelfRef access is as fast as direct access\n- ✅ **Memory efficient**: 1-8 bytes vs 8+ bytes for alternatives\n- ✅ **True movability**: Unlike Pin\u003cBox\u003cT\u003e\u003e, SelfRef can actually move\n- ✅ **No runtime overhead**: No borrow checking like Rc\u003cRefCell\u003cT\u003e\u003e\n\n\n## Comparison with Alternatives\n\n| Solution | Move Cost | Memory | Runtime Cost | Complexity |\n|----------|-----------|---------|--------------|------------|\n| `SelfRef` | **Zero** | **1-8 bytes** | **Zero** | Low |\n| `Pin\u003cBox\u003cT\u003e\u003e` | Impossible | 8+ bytes | Allocation | Medium |\n| `Rc\u003cRefCell\u003cT\u003e\u003e` | Cheap | 16+ bytes | Reference counting | High |\n| `ouroboros` | Zero | Varies | Zero | High |\n\n## Safety\n\n- ⚠️ Uses `unsafe` for pointer dereferencing\n- ✅ Safe when structure layout doesn't change after pointer setup\n- ✅ Safe for moving entire structures\n- ✅ Extensively tested with Miri\n\n## Examples\n\nRun the examples to see tether in action:\n\n```bash\n# Basic usage\ncargo run --example basic_usage\n\n# Performance benchmarks\ncargo run --example performance\n```\n\n## License\n\nLicensed under [MIT license](LICENSE-MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fengali94%2Fmovable-ref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fengali94%2Fmovable-ref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fengali94%2Fmovable-ref/lists"}