dittolive-ditto 4.11.3

//! Use [`ditto.disk_usage()`] to access the [`DiskUsage`] API to inspect Ditto's disk usage.
//!
//! # Monitor disk usage on a device
//!
//! In order to persist data on a device, Ditto can create a local database in a folder specified
//! with [`.with_root(...)`].
//!
//! To monitor this folder size, [`DiskUsage`] offers two methods:
//!   - [`.exec()`] to retrieve an immediate `DiskUsageTree` and
//!   - [`.observe(...)`] to call a callback every time changes occur in the Ditto folder.
//!
//! [`ditto.disk_usage()`]: crate::Ditto::disk_usage
//! [`.with_root(...)`]: crate::DittoBuilder::with_root
//! [`.exec()`]: DiskUsage::exec
//! [`.observe(...)`]: DiskUsage::observe

use_prelude!();
use core::ffi::c_void;
use std::sync::{Arc, Mutex, Weak};

use ffi_sdk::{BoxedDitto, FsComponent};
use serde::Deserialize;

#[repr(C)]
#[derive(Copy, Clone, Debug, PartialEq, Eq, Deserialize)]
/// Existing type in most file system.
pub enum FileSystemType {
    /// Item is a directory
    Directory = 0,

    /// Item is a standard file
    File,

    /// Item is a symlink
    SymLink,
}

#[derive(Deserialize, Debug, Clone, Eq, PartialEq)]
/// Entry in a file system
pub struct DiskUsageChild {
    /// Type of the entry.
    pub fs_type: FileSystemType,
    /// Relative path in the [`DittoRoot`].
    pub path: String,
    /// Size of the entry.
    pub size_in_bytes: usize,
    /// If the entry is a directory, it can contain children.
    pub children: Option<Vec<DiskUsageChild>>,
}

/// Handle returned by `DiskUsage::observe`.
/// Keep it in scope as long you want to receive updates on a given Ditto Subdirectory.
pub struct DiskUsageObserverCtx<F: ?Sized + DiskUsageCallback> {
    // Strong pointer to the inner callback
    // This will release the callback when dropped
    handle: Option<repr_c::Box<ffi_sdk::DiskUsageObserver>>,
    // callback
    on_update: F,
}

#[doc(hidden)]
#[deprecated(note = "This is now named `DiskUsageObserverCtx`")]
pub type DiskUsageObserver = DiskUsageObserverCtx<dyn DiskUsageCallback>;

trait_alias! {
    /// Callback bounds for the [`DiskUsage`] [`.observe(...)`] handler.
    ///
    /// [`.observe(...)`]: DiskUsage::observe
    pub trait DiskUsageCallback = 'static + Send + FnMut(DiskUsageChild)
}

/// Alias for the observer type returned by [`.observe(...)`].
///
/// [`.observe(...)`]: DiskUsage::observe
#[allow(type_alias_bounds)]
pub type DiskUsageObserverHandle<F: ?Sized + DiskUsageCallback = dyn DiskUsageCallback> =
    Mutex<DiskUsageObserverCtx<F>>;

const _ASSERT_IMPLS: &(dyn Send + Sync) = &::core::marker::PhantomData::<DiskUsageObserverHandle>;

impl<F: DiskUsageCallback> DiskUsageObserverCtx<F> {
    fn set_handle(&mut self, handle: repr_c::Box<ffi_sdk::DiskUsageObserver>) {
        self.handle = Some(handle);
    }

    /// `ctx` is, conceptually-speaking a `&'short_lived Weak< DiskUsageObserverCtx<F> >`.
    ///
    /// This scoped/callback API embodies that.
    #[track_caller]
    unsafe fn borrowing_from_ctx(
        ctx: *const c_void,
        yielding: impl FnOnce(&Weak<DiskUsageObserverHandle<F>>),
    ) {
        let weak_ctx = ::core::mem::ManuallyDrop::new(Weak::from_raw(
            ctx.cast::<DiskUsageObserverHandle<F>>(),
        ));
        yielding(&weak_ctx)
    }

    unsafe extern "C" fn on_event(ctx: *mut c_void, cbor: c_slice::Ref<'_, u8>) {
        Self::borrowing_from_ctx(ctx, |weak_ctx| {
            if let Some(strong_ctx) = weak_ctx.upgrade() {
                let tree = ::serde_cbor::from_slice(cbor.as_slice()).unwrap();
                (strong_ctx.lock().unwrap().on_update)(tree);
            }
        })
    }

    unsafe extern "C" fn retain(ctx: *mut c_void) {
        // No `Weak::increment_weak_count()`, so we do it ourselves.
        Self::borrowing_from_ctx(ctx, |weak_ctx| {
            _ = Weak::into_raw(weak_ctx.clone());
        });
    }

    unsafe extern "C" fn release(ctx: *mut c_void) {
        // No `Weak::decrement_weak_count()`, so we do it ourselves.
        drop(Weak::from_raw(ctx.cast::<DiskUsageObserverHandle<F>>()));
    }
}

/// Used to monitor the disk usage of Ditto or of its sub-components.
pub struct DiskUsage {
    ditto: Arc<BoxedDitto>,
    component: FsComponent,
}

impl DiskUsage {
    /// Create a new DiskUsage for the given component.
    pub(crate) fn new(ditto: Arc<BoxedDitto>, component: FsComponent) -> Self {
        Self { ditto, component }
    }

    /// Return the tree representation of the ditto disk usage of the component
    pub fn exec(&self) -> DiskUsageChild {
        let cval = ffi_sdk::ditto_disk_usage(&self.ditto, self.component);
        ::serde_cbor::from_slice(cval.as_slice()).unwrap()
    }

    /// Register a callback to monitor the disk usage of the component
    pub fn observe<F: DiskUsageCallback>(&self, callback: F) -> Arc<DiskUsageObserverHandle> {
        let observer: DiskUsageObserverHandle<F> = Mutex::new(DiskUsageObserverCtx::<F> {
            on_update: callback,
            handle: None,
        });
        let observer: Arc<DiskUsageObserverHandle<F>> = Arc::new(observer);

        // We will be using `Weak`s to get the "legacy" observer life-cycle pattern:
        // the caller must hold onto this to keep it alive, otherwise the strong references die,
        // so `DiskUsageObserver` dies, and drops the `Box<ffi_sdk::DiskUsageCbObserver>`, which
        // unregisters the callback.
        //
        // It would have been way less self-referential to have only the `on_event` part be behind
        // `Arc` indirection, and return a pair `(Arc<OnEvent>,
        // repr_c::Box<ffi_sdk::DiskUsageCbObserver>)` (properly prettified behind a layer
        // of `struct` abstraction), since it would have avoided the need for `Weak`s and the _a
        // posteriori_ `set_handle()`, but our hands are tied until the next breaking version.
        let weak_observer = Arc::downgrade(&observer);

        let handle = unsafe {
            ffi_sdk::ditto_register_disk_usage_callback(
                &self.ditto,
                self.component,
                weak_observer.as_ptr() as *mut _,
                Some(DiskUsageObserverCtx::<F>::retain),
                Some(DiskUsageObserverCtx::<F>::release),
                Some(<unsafe extern "C" fn(_, c_slice::Ref<'_, _>)>::into(
                    DiskUsageObserverCtx::<F>::on_event,
                )),
            )
        };
        // Would happen implicitly, but writing this down avoids mistakes (_e.g._, incorrectly
        // using `into_raw()` rather than `as_ptr()`).
        drop(weak_observer);

        observer.lock().unwrap().set_handle(handle.unwrap());
        observer
    }
}