Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Readme sync #10

Merged
merged 4 commits into from
Jul 23, 2019
Merged

Readme sync #10

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6539767
add note about Send and Sync
lopopolo Jul 23, 2019
b8beb68
Update docs links to point to artichoke docs
lopopolo Jul 23, 2019
e2090ea
Add CircleCI badge and link to docs
lopopolo Jul 23, 2019
8f222ca
Make docs link a badge
lopopolo Jul 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,21 @@
Single-threaded, cycle-aware, reference-counting pointers. 'Rc' stands for
'Reference Counted'.

[![CircleCI](https://circleci.com/gh/artichoke/cactusref.svg?style=svg)](https://circleci.com/gh/artichoke/cactusref)
[![Documentation](https://img.shields.io/badge/docs-cactusref-blue.svg)](https://artichoke.github.io/cactusref/cactusref/)

The type
[`Rc<T>`](https://lopopolo.github.io/ferrocarril/cactusref/struct.Rc.html)
[`Rc<T>`](https://artichoke.github.io/cactusref/cactusref/struct.Rc.html)
provides shared ownership of a value of type `T`, allocated in the heap.
Invoking
[`clone`](https://lopopolo.github.io/ferrocarril/cactusref/struct.Rc.html#impl-Clone)
on [`Rc`](https://lopopolo.github.io/ferrocarril/cactusref/struct.Rc.html)
[`clone`](https://artichoke.github.io/cactusref/cactusref/struct.Rc.html#impl-Clone)
on [`Rc`](https://artichoke.github.io/cactusref/cactusref/struct.Rc.html)
produces a new pointer to the same value in the heap. When the last externally
reachable
[`Rc`](https://lopopolo.github.io/ferrocarril/cactusref/struct.Rc.html) pointer
to a given value is destroyed, the pointed-to value is also destroyed.
reachable [`Rc`](https://artichoke.github.io/cactusref/cactusref/struct.Rc.html)
pointer to a given value is destroyed, the pointed-to value is also destroyed.

`Rc` can **detect and deallocate cycles** of `Rc`s through the use of
[`Adoptable`](https://lopopolo.github.io/ferrocarril/cactusref/trait.Adoptable.html).
[`Adoptable`](https://artichoke.github.io/cactusref/cactusref/trait.Adoptable.html).
Cycle detection is a zero-cost abstraction.

🌌 `CactusRef` depends on _several_ unstable Rust features and can only be built
Expand All @@ -39,10 +41,16 @@ implements most of the API from `std`.
If you do not depend on these APIs, `cactusref` is a drop-in replacement for
[`std::rc`](https://doc.rust-lang.org/std/rc/index.html).

Like [`std::rc`](https://doc.rust-lang.org/std/rc/index.html),
[`Rc`](https://artichoke.github.io/cactusref/cactusref/struct.Rc.html) and
[`Weak`](https://artichoke.github.io/cactusref/cactusref/struct.Weak.html) are
`!`[`Send`](https://doc.rust-lang.org/nightly/core/marker/trait.Send.html) and
`!`[`Sync`](https://doc.rust-lang.org/nightly/core/marker/trait.Sync.html).

## Cycle Detection

`Rc` implements
[`Adoptable`](https://lopopolo.github.io/ferrocarril/cactusref/trait.Adoptable.html)
[`Adoptable`](https://artichoke.github.io/cactusref/cactusref/trait.Adoptable.html)
to log bookkeeping entries for strong ownership links to other `Rc`s that may
form a cycle. The ownership links tracked by these bookkeeping entries form an
object graph of reachable `Rc`s. On `drop`, `Rc` uses these entries to conduct a
Expand Down