Struct drying_paint::WatchContext

pub struct WatchContext { /* fields omitted */ }

Most of the functions in this crate require that they are executing in a context. The context keeps track of some "global" state which enables the functionality in this crate.

The following will panic if done outside of a WatchContext:

• Calling WatchContext::update_current() (you can use WatchContext::update() to concisely update a context from outside itself).
• Mutating a Watched value.
• Calling WatchedEvent::dispatch()
• Calling WatchedMeta::trigger() (the two above are actually just specific variations on this)
• Creating a Watcher

When a watched value changes, the code watching those values will be queued onto the WatchContext. WatchContext::update_current() will execute all pending operations. Note: Because Watcher makes use of a RefCell internally to execute the watching code, you should not keep references gotten from Watcher::data() or Watcher::data_mut() around during WatchContext::update_current() or WatchContext::update().

Methods

impl WatchContext

pub fn new() -> Self

Create a new WatchContext

pub fn with<R, F: FnOnce() -> R>(&mut self, func: F) -> R

Set this WatchContext as the current one for the duration of the passed function. Note that it is supported (although discouraged) to nest WatchContexts within each other.

pub fn update_current()

Execute all operations which are currently pending because a value they were watching changed. Note: Because Watcher makes use of a RefCell internally to execute the watching code, you should not keep references gotten from Watcher::data() or Watcher::data_mut() around during WatchContext::update_current() or WatchContext::update().

Panics

This function will panic if called outside of WatchContext::with, or if any function queued for update panics or if the limit set by set_frame_limit is exceeded.

pub fn update(&mut self)

The same as doing context.with(|| WatchContext::update_current())

pub fn set_frame_limit(&mut self, value: Option<usize>)

Set the number of cycles this watch context will execute before panicking. This is useful for catching bugs involving recursive watches. None indicates no limit. The default behaviour is to provide a high value for debug builds and no limit for release builds.

Examples

#[derive(Default)]
struct KeepBalanced {
    left: Watched<i32>,
    right: Watched<i32>,
}
impl WatcherInit for KeepBalanced {
    fn init(watcher: &mut WatcherMeta<Self>) {
        watcher.watch(|root| {
            *root.left = *root.right;
        });
        watcher.watch(|root| {
            *root.right = *root.left;
        });
    }
}
fn main() {
    let mut ctx = WatchContext::new();
    ctx.set_frame_limit(Some(100));
    ctx.with(|| {
        let mut obj = Watcher::<KeepBalanced>::new();
        *obj.data_mut().left = 4;
        // because we used set_frame_limit, this will panic after
        // 100 iterations.
        WatchContext::update_current();
    });
}