Struct Pass 

pub struct Pass(/* private fields */);

A key for reading/writing to RwData

This key is necessary in order to prevent breakage of the number one rule of Rust: any number of shared references, or one exclusive reference.

When you call RwData::read, any call to RwData::write may end up breaking this rule, and vice-versa, which is why this struct is necessary.

One downside of this approach is that it is even more restrictive than Rust’s rule of thumb, since that one is enforced on individual instances, while this one is enforced on all RwDatas. This (as far as i know) cannot be circumvented, as a more advanced compile time checker (that distinguishes RwData<T>s of different Ts, for example) does not seem feasible without the use of unfinished features, which I am not willing to use.

Implementations

impl Pass

pub fn write_many<'p, Tup: WriteableTuple<'p, impl Any>>( &'p mut self, tup: Tup, ) -> Tup::Return

Writes to many RwData-like structs at once

This function accepts tuples (or a single element) of references to types that implement the [WriteableData] trait, which is one of the following:

• RwData: Duat’s regular smart pointer.
• BulkDataWriter: A pointer to lazyly updated data.
• Handle: A handle for a Widget
• RwArea: A handle for a Widget’s Area

Here’s an example, which writes to two RwDatas at the same time as a Handle:

use duat::{data::RwData, prelude::*};
setup_duat!(setup);

fn setup() {
    let (num1, num2) = (RwData::new(0), RwData::new(0));
    hook::add::<BufferOpened>(move |pa, handle: &Handle| {
        let (num1, num2, buf) = pa.write_many((&num1, &num2, handle));
        // Rest of the function writes to all of them at the same time.
    });
}

This allows for much more flexibility when writing to global state, which should hopefully lead to more streamlined functions

Panics

This function will panic if any of the elements of the tuple point to the same data as any other element, for example, with the earlier code snippet:

use duat::{data::RwData, prelude::*};
setup_duat!(setup);

fn setup() {
    let num1 = RwData::new(0);
    // num2 is now a clone of num1
    let num2 = num1.clone();
    hook::add::<BufferOpened>(move |pa, handle: &Handle| {
        let (num1, num2, buf) = pa.write_many((&num1, &num2, handle));
        // Rest of the function writes to all of them at the same time.
    });
}

Since num1 and num2 point to the same data, you’d be getting two &mut i32 for the same variable, which violates rust’s “mutability xor aliasing” rule. This is why this will panic. If you want a non-panicking version of this function, check out Pass::try_write_many, which returns a Result instead.

pub fn try_write_many<'p, Tup: WriteableTuple<'p, impl Any>>( &'p mut self, tup: Tup, ) -> Result<Tup::Return, Text>

Tries writing to many RwData-like structs at once

This function accepts tuples (or a single element) of references to types that implement the [WriteableData] trait, which is one of the following:

• RwData: Duat’s regular smart pointer.
• BulkDataWriter: A pointer to lazyly updated data.
• Handle: A handle for a Widget
• RwArea: A handle for a Widget’s Area

This function works exactly like Pass::write_many, however, instead of panicking, this function returns a Result, returning an Err if any of the tuple’s elements point to the same data as any of the other elements.