x-bow 0.2.0

use std::cell::{Ref, RefCell, RefMut};

use crate::{hash_visitor::HashVisitor, wakers::StoreWakers};

/// A Path object identifies a piece of the data store.
///
/// It can convert a borrow of the store's data to a borrow of the piece it identifies.
///
/// Often, you won't be working with the `Path` trait itself, but rather
/// the [PathExt][crate::PathExt] trait.
///
/// Path objects are mostly generated by `#[derive(x_bow::Trackable)]`.
/// To hand-implement, see example code in `src/impls/stdlib`.
pub trait Path {
    type Out: ?Sized;

    /// Borrow the data at the given path immutably.
    ///
    /// **Do not use this**. It is considered "internal" API. Use the equivalent
    /// [borrow_opt_mut][crate::PathExt::borrow_opt_mut] instead.
    ///
    /// If there is an existing mutable borrow anywhere in the store,
    /// this method will panic.
    #[doc(hidden)]
    fn path_borrow(&self) -> Option<Ref<'_, Self::Out>>;

    /// Borrow the data at the given path mutably.
    ///
    /// **Do not use this**. It is considered "internal" API. Use the equivalent
    /// [borrow_opt_mut_without_notifying][crate::PathExt::borrow_opt_mut_without_notifying] instead.
    ///
    /// If there is an existing mutable or immutable borrow anywhere in the store,
    /// this method will panic.
    #[doc(hidden)]
    fn path_borrow_mut(&self) -> Option<RefMut<'_, Self::Out>>;

    /// Call the given visitor function on the hash of this path node and every
    /// ancestor node in the path.
    #[doc(hidden)]
    fn visit_hashes(&self, visitor: &mut HashVisitor);

    /// Used internally for subscription and notification system.
    #[doc(hidden)]
    fn store_wakers(&self) -> &RefCell<StoreWakers>;
}