Adding `archery` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add archery

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

archery = "1.2.2"

The archery library will be automatically available globally. Read the archery library documentation.

Back to the crate overview.

Readme

`archery`

archery is a rust library that offers a way to abstraction over Rc and Arc smart pointers. This allows you to create data structures where the pointer type is parameterizable, so you can avoid the overhead of Arc when you don’t need to share data across threads.

In languages that supports higher-kinded polymorphism this would be simple to achieve without any library, but rust does not support that yet. To mimic higher-kinded polymorphism archery implements the approach suggested by Joshua Liebow-Feeser in “Rust has higher kinded types already… sort of”. While other approaches exist, they seem to always offer poor ergonomics for the user.

Setup

To use archery add the following to your Cargo.toml:

[dependencies]
archery = "<version>"

Using `archery`

archery defines a SharedPointer that receives the kind of pointer as a type parameter. This gives you a convenient and ergonomic way to abstract the pointer type away.

Example

Declare a data structure with the pointer kind as a type parameter bounded by SharedPointerKind:

use archery::*;

struct KeyValuePair<K, V, P: SharedPointerKind> {
    pub key: SharedPointer<K, P>,
    pub value: SharedPointer<V, P>,
}

impl<K, V, P: SharedPointerKind> KeyValuePair<K, V, P> {
    fn new(key: K, value: V) -> KeyValuePair<K, V, P> {
        KeyValuePair {
            key: SharedPointer::new(key),
            value: SharedPointer::new(value),
        }
    }
}

To use it just plug-in the kind of pointer you want:

let pair: KeyValuePair<_, _, RcK> =
    KeyValuePair::new("António Variações", 1944);

assert_eq!(*pair.value, 1944);

`triomphe::Arc`

You can also use triomphe::Arc as the backing implementation of a SharedPointer. This is generally faster than std::sync::Arc. Read triomphe’s crate documentation to learn more about it.

To use it you need to enable the triomphe feature in archery. Use ArcTK as the pointer kind in SharedPointer.

Serialization

We support serialization through serde. To use it enable the serde feature. To do so change the archery dependency in your Cargo.toml to

[dependencies]
archery = { version = "<version>", features = ["serde"] }

Limitations

Currently it is not possible to have unsized types inside a SharedPointer. As a workaround you can put the unsized type inside a Box.

Alternative approaches

An alternative to the approach taken by archery is to use traits with associated types to encode type-level functions. This has been suggested multiple times, but offers ugly ergonomics (see here and here).

Adding archery library as a dependency

Adding `archery` library as a dependency