https://github.com/ericlbuehler/trc

A faster Arc.
https://github.com/ericlbuehler/trc

reference-counting rust smart-pointers

Last synced: 2 days ago
JSON representation

A faster Arc.

• Host: GitHub
• URL: https://github.com/ericlbuehler/trc
• Owner: EricLBuehler
• License: mit
• Created: 2023-06-11T23:36:55.000Z (over 1 year ago)
• Default Branch: master
• Last Pushed: 2024-02-08T13:25:04.000Z (8 months ago)
• Last Synced: 2024-09-14T09:35:07.188Z (21 days ago)
• Topics: reference-counting, rust, smart-pointers
• Language: Rust
• Homepage: https://crates.io/crates/trc
• Size: 497 KB
• Stars: 44
• Watchers: 5
• Forks: 6
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Trc

[![MIT License](https://img.shields.io/badge/License-MIT-informational)](LICENSE)

![Build status](https://github.com/EricLBuehler/trc/actions/workflows/build.yml/badge.svg)

![Docs status](https://github.com/EricLBuehler/trc/actions/workflows/docs.yml/badge.svg)

![Tests status](https://github.com/EricLBuehler/trc/actions/workflows/tests.yml/badge.svg)

`Trc` is a performant heap-allocated smart pointer for Rust that implements thread reference counting.

`Trc` stands for: Thread Reference Counted.

`Trc` provides a shared ownership of the data similar to `Arc` and `Rc`.

It implements thread reference counting, which is based on the observation that most objects are only used by one thread.

This means that two reference counts can be created: one for thread-local use, and one atomic one for sharing between threads.

Thread reference counting sets the atomic reference count to the number of threads using the data.

A cycle between `Trc` pointers cannot be deallocated as the reference counts will never reach zero. The solution is a `Weak`.

A `Weak` is a non-owning reference to the data held by a `Trc`.

They break reference cycles by adding a layer of indirection and act as an observer. They cannot access the data directly, and

must be converted back into a `Trc`. `Weak` does not keep the value alive (which can be dropped), and only keeps the backing allocation alive.

To soundly implement thread safety `Trc` is `!Send` and `!Sync`. To solve this, `Trc` introduces a `SharedTrc`, which is `Send` and `Sync`.

`SharedTrc` is the only way to safely send a `Trc`'s data across threads without using a `Weak`.

See `SharedTrc` for it's API, which is similar to that of `Weak`.

Because `Trc` is not part of the standard library, the `CoerceUnsized` and `Receiver` traits cannot currently be implemented by default. However, `Trc` provides `dyn_unstable` trait which enables the above traits for `Trc` and `SharedTrc` and must be used with nightly Rust (`cargo +nightly ...`).

## Examples

See examples [here](EXAMPLES.md).

## Benchmarks 

Click [here](BENCHMARKS.md) for more benchmarks. Multiple different operating systems, CPUs, and architectures are tested. 

![Trc vs Arc performance](./figures/performance.png)

## Use

To use `Trc`, simply run `cargo add trc`, or add `trc = "1.2.3"`. Optionally, you can always use the latest version by adding `trc = {git = "https://github.com/EricLBuehler/trc.git"}`.