Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Sharing values

In the previous chapter, we saw that giving a non-copyable value moves it – after a give, the original is gone. We also saw that shared struct types like Int are copyable and can be given multiple times. But what about ordinary structs? What if you want to use a value in multiple places without giving up ownership?

That’s what sharing is for.

Sharing a value

Sharing a value expression, such as new Data().share or d→.share, converts unique (given) ownership to independent shared ownership, shared[]. The shorter permission spelling shared means the same thing. Once shared, a value can be freely copied:

sharing_a_value [src]
crate::assert_ok!(
    r#"
        struct Data { }

        struct Main {
            fn test(given self) → shared Data {
                let d = new Data();
                let s = d→.share;
                s→;
                s→;
            }
        }
    "#
);

Compare this with the giving a value twice example from the previous chapter, which failed. The difference is .share – it transforms the Data value so that subsequent gives copy rather than move.

Sharing a place directly is a different operation. d and d.share both yield shared[d] Data, keeping a dependency on d. To share its value independently, write d→.share: first give the value, then share it. The Sharing places chapter explains place dependencies.

The share value rule

The type checker handles sharing a value with this rule:

type_expr::share value [src]
(type_expr(env, live_after, &**expr) => (env, ty))
(prove_is_struct(env, ty) => ())
----------------------------------- ("share value")
(type_expr(env, live_after, Expr::ShareValue(expr)) => (env, Ty::apply_perm(Perm::Shared, ty)))

The rule has two premises:

  • type_expr(env, ..., &*expr) => (env, ty) – Type-check the inner expression, producing a type ty.

  • prove_is_struct(&env, &ty) => () – Verify that the type is allowed to be shared. Not all types can be shared – classes cannot.

If both premises succeed, the result type is shared ty – the original type wrapped with the shared[] permission. Dependencies already present in the inner type still matter; for example, sharing a mutable lease does not remove the lease’s origin.

Shareability and declaration categories

Whether a type can be shared depends on its class predicate. The three declaration forms select these predicates:

ClassPredicate [src]
#[term]
#[derive(Copy, Default)]
pub enum ClassPredicate {
    /// Uniquely tracked affine data. Only classes may have a destructor.
    #[default]
    #[grammar(class)]
    Class,

    /// Data that can be shared independently. It has no destructor.
    #[grammar(struct)]
    Struct,

    /// Always-shared value data. Individual fields cannot be mutated.
    #[grammar(shared struct)]
    Shared,
}
DeclarationPredicateShareable?
class Foo { }ClassNo
struct Foo { }StructYes
shared struct Foo { }SharedAlready shared

The prove_is_struct judgment delegates to the general predicate-proving machinery:

prove_is_struct::is [src]
(prove_predicate(env, Predicate::struct_(a)) => ())
---------------------------- ("is")
(prove_is_struct(env, a) => ())

For a struct like Data, the Struct declaration category permits value sharing. Neither structs nor shared structs may have a destructor; the checker rejects a nonempty drop body on either form.

Shared values are copyable

Once a value is shared, the move_place judgment from the giving chapter treats it differently. Recall that move_place has two rules – “give” (move) and “copy”. The “copy” rule requires prove_is_shared:

move_place::copy [src]
(if live_after.is_live(place))!
(prove_is_shared(env, ty) => ())
----------------------------------- ("copy")
(move_place(env, _live_after, _place, ty) => env)

A shared Data type satisfies prove_is_shared because any shared permission can be duplicated. So when you write s→ on a shared value, the “copy” rule fires and the value is copied rather than moved.

This is why the example above works – both s→ expressions copy the shared value.

Shared structs and generic arguments

In the previous chapter, we saw that Int values can be given multiple times. That’s because Int is a shared struct type – it has the Shared class predicate, which means it is always shared and copyable without needing an explicit .share:

shared_classes_always_shared [src]
crate::assert_ok!(
    r#"
        shared struct Point {
            x: Int;
            y: Int;
        }

        struct Main {
            fn test(given self) → Point {
                let p = new Point(22, 44);
                p→;
                p→;
            }
        }
    "#
);

Shared structs with no generic arguments, such as Int, are always copyable. A generic shared struct additionally requires all its arguments to be shared; an owned, unique type argument can prevent copying. Their fields cannot be individually mutated. Ordinary structs have mutable fields and require value sharing to become copyable. Classes retain affine ownership.

Classes cannot be shared as values

A class may have a destructor and cannot be independently shared as a value. Attempting that conversion is an error:

given_classes_cannot_be_shared [src]
crate::assert_err!(
    r#"
        class Resource { }

        struct Main {
            fn test(given self) → shared Resource {
                let r = new Resource();
                r→.share;
            }
        }
    "#,
    expect_test::expect![[r#"
        the rule "struct" at (predicates.rs) failed because
          pattern `true` did not match value `false`"#]]
);

The prove_is_struct premise fails because Resource has the Class predicate, which does not satisfy Resource is struct.

Sharing is idempotent

Sharing an already-shared value is fine – it’s a no-op:

sharing_is_idempotent [src]
crate::assert_ok!(
    r#"
        struct Data { }

        struct Main {
            fn test(given self) → shared Data {
                let d = new Data();
                d→.share.share;
            }
        }
    "#
);

The inner .share produces shared Data. The outer .share checks prove_is_struct on shared Data, which succeeds because a shared permission is always shareable. The result is still shared Data – applying shared to an already-shared type normalizes to the same type.

Struct, unique, shared, and owned

These predicates describe different properties:

  • T is struct means values of T can be shared as values.
  • T is unique means access must remain exclusive: this includes unique owners and mutable leases. It does not imply ownership.
  • T is shared means values of T are shared and can be duplicated. This includes values obtained by sharing a place; it does not require ownership.
  • T is owned means fully owned, with no origin dependencies.

For fully owned shared values, write both constraints: where T is shared, T is owned. For unique ownership, write where T is unique, T is owned; there is no separate given predicate.

The permission shared[] describes independent sharing; shared[d] describes sharing from the place d. Any shared permission can be duplicated. Thus shared Data is both shared and owned, while shared[d] Data is shared without being owned. An ordinary owned Data can be shareable without already being shared. A declaration category describes the data type; a permission describes access to a particular value.

Giving from alternative origins: ownership requires owned origins

given[p1, ..., pn] satisfies owned when every possible originating place has an owned type. An owned shared value qualifies just as a unique owner does; a borrowed alternative cannot be ignored merely because another origin is owned.

For an ordinary non-shared Wrapper, with borrowed origins referring to uniquely owned source1 and source2:

Origin typesgiven[d1, d2] is owned?
Any pair of given Wrapper and shared WrapperYes
Any pair containing shared[source] Wrapper or ![source] WrapperNo

Consequently, given/shared alternatives can be owned even though they are neither uniformly shared nor uniformly unique. Ownership, duplication, and the mut predicate describe different capabilities.

The complete place type matters

Origins may be fields, nested fields, or fields storing references inside unique containers. The ownership of the container alone does not prove that its stored reference is owned. The table assumes genuinely borrowed references: the model can treat a reference to an owned shared value as owned, because that shared ownership is retained. Reference syntax alone does not decide this predicate.

Candidate lemma and evidence

For a well-formed environment and nonempty list of valid places, the mv owned rule proves given[p1, ..., pn] is owned from ownership of each place’s type. Conversely, such a derivation through that rule requires every premise. This is a candidate lemma, not a proof of preservation during execution.

Tests use complete Dada programs calling a method requiring P is owned. All concrete given/shared/shared/mut pairs are checked for direct origins; selected contrasting pairs in both orders cover fields, nested fields, and stored-field permissions. Every negative program compiles when only its owned requirement is removed. The class is ordinary and non-generic, avoiding independently shared value types such as Int as the result. Generic assumptions and runtime cleanup are outside this evidence.

Property source and tests

Unique ownership requires both exclusivity and ownership

P is unique includes mutable leases as well as unique owners, while P is owned includes shared owners as well as unique owners. Requiring both admits independent unique ownership and excludes either shared ownership or mutable leasing alone. There is no separate given predicate.

The accepted program forwards both assumptions through a generic method, checks an ownership-only disjunction, and executes the returned result. Rejected programs remove one assumption or pass a concrete shared owner or mutable lease. These are examples supporting the conjunction, not a proof that all permission combinations have been characterized.

Property source and tests

Independent sharing

shared and shared[] are equivalent. Neither introduces a place dependency.

Independent sharing is owned and duplicable

shared and shared[] denote the same permission: a shared value with no origin dependency. Such a permission satisfies both shared and owned, and does not satisfy the exclusive/unique predicate. These complete programs test the empty-origin spelling through surface lowering and generic calls. Bare places and explicit .share retain their origin; giving then sharing creates independent shared ownership.

Property source and tests