Struct persian_rug::Proxy

pub struct Proxy<T> { /* private fields */ }

A handle to an item stored in some context.

A proxy is a link between objects, like Arc or Rc. It allows multiple objects to reference a single other object, without any one of them being declared the owner. Unlike reference counted smart pointers, you need to provide its Context to traverse the link represented by a Proxy.

When writing code that makes use of proxies, things are made more complicated by the need to ensure the right kind of access for the context is available (i.e. every function is likely to receive either a Mutator or an Accessor parameter, depending on whether mutable access is needed. However, things are made simpler in terms of establishing that access is safe, since there is only one object to which you need a mutable reference: the context object.

The following example traverses an arbitrary graph of Foos (checking for cycles by never revisiting any node). There are of course other ways of doing this (both in Rust, and using this crate), but holding and working with such graphs is generally considered challenging in Rust. As the example shows, it can be relatively convenient to do so using this crate:

use persian_rug::{contextual, persian_rug, Accessor, Context, Contextual, Proxy};
use std::collections::BTreeSet;

#[contextual(Rug)]
struct Foo {
   id: String,
   links: Vec<Proxy<Foo>>
}

impl Foo {
  pub fn print_graph<A: Accessor<Context=Rug>>(&self, access: A) {
    let mut b = BTreeSet::new();
    let mut work = Vec::new();
    work.push(self);
    while let Some(item) = work.pop() {
      println!("{}", item.id);
      b.insert(item.id.clone());
      for link in &item.links {
        let link = access.get(link);
        if !b.contains(&link.id) {
          work.push(link);
        }
      }
    }
  }
}

#[persian_rug]
struct Rug(#[table] Foo);

Had we used Proxy<Foo> as our start value here (and given up having a self parameter), we could’ve used the proxies themselves to check for uniqueness, avoiding the need to compare and clone String fields, and removing any chance of a name collision.

use persian_rug::{contextual, persian_rug, Accessor, Context, Contextual, Proxy};
use std::collections::BTreeSet;

#[contextual(Rug)]
struct Foo {
   id: String,
   links: Vec<Proxy<Foo>>
}

impl Foo {
  pub fn print_graph<A: Accessor<Context=Rug>>(start: Proxy<Foo>, access: A) {
    let mut b = BTreeSet::new();
    let mut work = Vec::new();
    work.push(start);
    while let Some(item_proxy) = work.pop() {
      let item = access.get(&item_proxy);
      println!("{}", item.id);
      b.insert(item_proxy);
      for link in &item.links {
        if !b.contains(link) {
          work.push(*link);
        }
      }
    }
  }
}

#[persian_rug]
struct Rug(#[table] Foo);

Note that a Proxy implements Copy as well as Eq. The implementation of Ord is guaranteed to be consistent on a given run of the program, but no other guarantees are made.

Trait Implementations

impl<T> Clone for Proxy<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Proxy<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Ord for Proxy<T>

fn cmp(&self, other: &Proxy<T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<T> PartialEq<Proxy<T>> for Proxy<T>

fn eq(&self, other: &Proxy<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialOrd<Proxy<T>> for Proxy<T>

fn partial_cmp(&self, other: &Proxy<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Copy for Proxy<T>

impl<T> Eq for Proxy<T>