# A smart pointer library, with a garbage collector.
This library has a smart pointer (similar to `Rc`/`Arc`), but permits these pointers to have cycles.
It does this by having two groups of pointers:
- `GcPtr`, which is similar to `Rc`/`Arc` (and cannot handle cycles).
- `GcMemberPtr`, which describes the link between two objects, and supports cycles.
## Thread-safe and thread-local
The `GcPtr` and `GcMemberPtr` pointers are available in thread-local form (similar to `Rc`).
These are generally faster (because there's no locking/concurrency overhead), but are restricted to always staying in the same thread.
And, if the `multi_thread` feature is activated, the `sync::GcMtPtr` and `sync::GcMtMemberPtr` are available in thread-safe form.
## Constraint on Types
The pointers can only point at items of `'static` lifetime, because the garbage collector can be delayed.
In addition, because the thread-safe pointer (`sync::GcMtPtr` or `sync::GcMtMemberPtr`) can have the garbage collection run in a separate thread, requires that their types are always `Send+Sync`.
## Weak Pointers
Optional support for weak pointers is available, behind the `weak_pointers` feature.
## Features
- `multi_thread` enables the multi-thread pointers.
- `weak_pointer` enables the weak pointers.
- `single_generation` makes the thread-local code use a single generation (this tends to speed up constructors, and slow down GC cycles, so you probably want to install a `GcTask` callback).
- `single_generation_mt` makes the thread-safe code use a single generation (this tends to speed up constructors, and slow down GC cycles, so you probably want to install a `GcTask` callback).
For the `single_generation`/`single_generation_mt` features, it's best not to enable them in libraries, only in binaries.
Because it's much easier to run tests with many generations (since each test will use its own self-contained generations).
## Bugs
This is fairly new code, and the tests are a bit underwhelming.
So there might be some bugs.
Design should be fine though.
## Further Reading
See also [documentation on docs.rs](https://docs.rs/cycle_ptr/latest/cycle_ptr/) and [cycle\_ptr on crates.io](https://crates.io/crates/cycle_ptr).