cycle_ptr 0.1.1

//! Module for the member pointer type.
use crate::GcPtr;
use crate::errors::{Error, ErrorEnum};
use crate::generation::edge::Edge;
use crate::generation::{GenerationPtr, ObjectState};
use crate::object::{DynObjectPtr, ObjectIntf, ObjectPtr};
use crate::prelude::GcPtrEq;
use std::fmt;
use std::ops::Deref;
use std::pin::Pin;
use std::ptr;

#[cfg(feature = "multi_thread")]
use super::SingleOrMultiThreadPtr;
#[cfg(not(feature = "single_generation"))]
use crate::generation::Generation;
#[cfg(feature = "multi_thread")]
use crate::object::{MTObjectIntf, MTObjectPtr};
#[cfg(feature = "multi_thread")]
use crate::sync::{GcMtMemberPtr, GcMtPtr};

/// A member pointer is a pointer that propagates reachability.
/// It works by being aware of on which object it is installed,
/// and forwarding the reachability of that object, to the pointee.
/// (That's a very difficult way of saying: the pointer keeps the object alive,
/// so long as the object it is a member-variable of stays alive.)
///
/// The garbage collector is able to detect cycles in pointers,
/// because the member pointer is aware of where it is installed.
///
/// # How To Create
///
/// [GcMemberPtr] is constructed using the [Metadata][crate::Metadata].
/// This metadata is provided during construction of the object on which the member pointer will be present.
///
/// ```
/// use cycle_ptr::prelude::*;
/// use cycle_ptr::{GcMemberPtr, GcPtr, Metadata};
///
/// struct MyStruct {
///     member_ptr: GcMemberPtr<i32>,
/// }
///
/// let number = GcPtr::new(|_| 17);
/// let my_struct_ptr = GcPtr::new(|metadata| MyStruct {
///     member_ptr: metadata.new_pointer(number),
/// });
/// ```
///
/// # No Cloning
///
/// The member pointer is not [cloneable][Clone]. This is because it
/// tracks the origin object, and when cloning, you probably want to
/// install it somewhere else (this the copy would not be associated
/// with the same origin.
///
/// Instead, to create a copy, use the [GcMemberPtr::as_ptr] method
/// to create a [new strong pointer][GcPtr].
///
/// # Drop
///
/// When the origin of a member pointer becomes unreachable,
/// the member pointer is no longer dereferencable.
/// This is to prevent resurrection of the pointee object,
/// which may have already been dropped.
///
/// # Example
///
/// ```
/// use cycle_ptr::prelude::*;
/// use cycle_ptr::{GcMemberPtr, GcPtr, Metadata};
/// use std::sync::RwLock;
///
/// struct City {
///     name: String,
///     roads: RwLock<Vec<GcMemberPtr<Road>>>,
///
///     // We hold on to the metadata, so we can create MemberPointers later on.
///     metadata: Metadata,
/// }
///
/// struct Road {
///     from: GcMemberPtr<City>,
///     to: GcMemberPtr<City>,
///     distance: f32,
/// }
///
/// impl City {
///     fn new(name: String) -> GcPtr<City> {
///         GcPtr::new(|metadata| City {
///             roads: RwLock::new(Vec::default()),
///             name,
///             metadata,
///         })
///     }
/// }
///
/// impl Road {
///     fn new(from: &GcPtr<City>, to: &GcPtr<City>, distance: f32) -> GcPtr<Road> {
///         let road = GcPtr::new(|metadata| Road {
///             from: metadata.new_pointer(from.clone()),
///             to: metadata.new_pointer(to.clone()),
///             distance,
///         });
///         from.roads
///             .write()
///             .unwrap()
///             .push(from.metadata.new_pointer(road.clone()));
///         to.roads
///             .write()
///             .unwrap()
///             .push(to.metadata.new_pointer(road.clone()));
///         road
///     }
/// }
///
/// let amsterdam = City::new("Amsterdam".to_owned());
/// let berlin = City::new("Berlin".to_owned());
/// let road = Road::new(&amsterdam, &berlin, 636_f32);
/// ```
pub struct GcMemberPtr<T>
where
    T: 'static,
{
    /// The type-erased [Object][crate::object::ObjectIntf] of which this member-pointer is a member.
    pub(super) origin: Pin<DynObjectPtr>,

    /// The [Object][crate::object::Object] containing `T`, that this member-pointer points at.
    #[cfg(not(feature = "multi_thread"))]
    pub(super) ptr: Pin<ObjectPtr<T>>,
    /// The [Object][crate::object::Object]/[MTObject][crate::object::MTObject] containing `T`, that this member-pointer points at.
    #[cfg(feature = "multi_thread")]
    pub(super) ptr: SingleOrMultiThreadPtr<T>,

    /// The [Edge] that this member-pointer is tracked in.
    ///
    /// Member pointers may be stored behind a [Mutex][std::sync::Mutex] or other type of lock.
    /// An [Edge] publishes the member-pointer in a way the garbage collector can walk the object,
    /// without risking dead-lock or competing for locks.
    edge: Pin<Box<Edge>>,
}

impl<T> GcMemberPtr<T>
where
    T: 'static,
{
    /// Create a new object pointer.
    ///
    /// This is the single-threaded case.
    /// `sp_ptr` must have 1 reference count.
    unsafe fn new_ptr_st(origin: Pin<DynObjectPtr>, sp_ptr: Pin<ObjectPtr<T>>) -> Self {
        let edge = Box::pin(Edge::new(unsafe {
            Pin::new_unchecked(sp_ptr.get_control_block())
        }));

        let origin_generation = origin.get_generation_ptr();
        let sp_ptr_generation = sp_ptr.get_generation_ptr();

        #[cfg(feature = "single_generation")]
        {
            assert!(GenerationPtr::ptr_eq(
                &origin_generation,
                &sp_ptr_generation
            ));
            origin.get_control_block().register_edge(edge.as_ref());
            sp_ptr.get_control_block().refcount_dec_no_gc();
        }

        #[cfg(not(feature = "single_generation"))]
        if GenerationPtr::ptr_eq(&origin_generation, &sp_ptr_generation) {
            origin.get_control_block().register_edge(edge.as_ref());
            sp_ptr.get_control_block().refcount_dec_no_gc();
        } else if origin_generation.id < sp_ptr_generation.id {
            origin.get_control_block().register_edge(edge.as_ref());
        } else {
            let merged_generation = Generation::merge(sp_ptr_generation, origin_generation);
            assert!(GenerationPtr::ptr_eq(
                &merged_generation,
                &origin.get_generation_ptr()
            ));
            assert!(GenerationPtr::ptr_eq(
                &merged_generation,
                &sp_ptr.get_generation_ptr()
            ));
            origin.get_control_block().register_edge(edge.as_ref());
            sp_ptr.get_control_block().refcount_dec_no_gc();
        }

        GcMemberPtr {
            origin,
            #[cfg(not(feature = "multi_thread"))]
            ptr: sp_ptr,
            #[cfg(feature = "multi_thread")]
            ptr: sp_ptr.into(),
            edge,
        }
    }

    /// Create a new object pointer.
    ///
    /// This is the single-threaded case.
    /// `sp_ptr` must have 1 reference count.
    #[cfg(feature = "multi_thread")]
    unsafe fn new_ptr_mt(origin: Pin<DynObjectPtr>, sp_ptr: Pin<MTObjectPtr<T>>) -> Self {
        let edge = Box::pin(Edge::new_mt(unsafe {
            Pin::new_unchecked(sp_ptr.get_control_block())
        }));
        origin.get_control_block().register_edge(edge.as_ref());
        GcMemberPtr {
            origin,
            ptr: sp_ptr.into(),
            edge,
        }
    }

    /// Create a new member pointer, from a [GcPtr].
    pub(crate) fn new_ptr(origin: Pin<DynObjectPtr>, sp: GcPtr<T>) -> Self {
        // SAFETY: this is safe because we will handle the reference-drop ourselves.
        unsafe {
            let sp_ptr = GcPtr::release(sp);

            #[cfg(not(feature = "multi_thread"))]
            return Self::new_ptr_st(origin, sp_ptr);
            #[cfg(feature = "multi_thread")]
            return match sp_ptr {
                SingleOrMultiThreadPtr::SingleThread(sp_ptr) => Self::new_ptr_st(origin, sp_ptr),
                SingleOrMultiThreadPtr::MultiThread(sp_ptr) => Self::new_ptr_mt(origin, sp_ptr),
            };
        }
    }

    /// Retrieve a [strong pointer][GcPtr] from this pointer.
    ///
    /// # Panics
    ///
    /// If the origin of this member pointer has expired,
    /// then acquiring the pointer is no longer allowed and will cause a panic.
    ///
    /// (This means that if you attempt to dereference the pointer during [Drop::drop],
    /// the panic will happen.)
    #[inline]
    pub fn as_ptr(&self) -> GcPtr<T> {
        if self.origin.object_state() == ObjectState::Expired {
            panic!("cannot dereference member pointers on targets that are unreachable");
        }

        #[cfg(not(feature = "multi_thread"))]
        return {
            self.ptr.get_control_block().refcount_inc();
            // SAFETY: we incremented the reference counter just now.
            unsafe { GcPtr::new_from_raw(self.ptr.clone()) }
        };

        #[cfg(feature = "multi_thread")]
        return {
            match &self.ptr {
                SingleOrMultiThreadPtr::SingleThread(ptr) => {
                    ptr.get_control_block().refcount_inc();
                    // SAFETY: we incremented the reference counter just now.
                    unsafe { GcPtr::new_from_raw(ptr.clone()) }
                }
                SingleOrMultiThreadPtr::MultiThread(ptr) => {
                    ptr.get_control_block().refcount_inc();
                    // SAFETY: we incremented the reference counter just now.
                    unsafe { GcPtr::new_from_raw_mt(ptr.clone()) }
                }
            }
        };
    }

    /// Try to dereference the pointer.
    ///
    /// (Most of the time, you probably want to use the [Deref trait][GcMemberPtr::deref].)
    ///
    /// # Errors
    ///
    /// This function will fail if the origin of the member pointer has become unreachable.
    #[inline]
    pub fn try_deref(&self) -> Result<&T, Error> {
        if self.origin.object_state() == ObjectState::Expired {
            return Err(Error::new(ErrorEnum::OriginExpired(
                self.origin.created_backtrace().clone(),
            )));
        }

        #[cfg(not(feature = "multi_thread"))]
        return Ok(self.ptr.get_data());
        #[cfg(feature = "multi_thread")]
        return match &self.ptr {
            SingleOrMultiThreadPtr::SingleThread(ptr) => Ok(ptr.get_data()),
            SingleOrMultiThreadPtr::MultiThread(ptr) => Ok(ptr.get_data()),
        };
    }

    /// Retrieve a [strong pointer][GcPtr] from this pointer.
    ///
    /// # Errors
    ///
    /// This function will fail if the origin of the member pointer has become unreachable.
    #[inline]
    pub fn try_as_ptr(&self) -> Result<GcPtr<T>, Error> {
        if self.origin.object_state() == ObjectState::Expired {
            return Err(Error::new(ErrorEnum::OriginExpired(
                self.origin.created_backtrace().clone(),
            )));
        }

        #[cfg(not(feature = "multi_thread"))]
        return {
            self.ptr.get_control_block().refcount_inc();
            // SAFETY: we incremented the reference counter just now.
            Ok(unsafe { GcPtr::new_from_raw(self.ptr.clone()) })
        };

        #[cfg(feature = "multi_thread")]
        return {
            match &self.ptr {
                SingleOrMultiThreadPtr::SingleThread(ptr) => {
                    ptr.get_control_block().refcount_inc();
                    // SAFETY: we incremented the reference counter just now.
                    Ok(unsafe { GcPtr::new_from_raw(ptr.clone()) })
                }
                SingleOrMultiThreadPtr::MultiThread(ptr) => {
                    ptr.get_control_block().refcount_inc();
                    // SAFETY: we incremented the reference counter just now.
                    Ok(unsafe { GcPtr::new_from_raw_mt(ptr.clone()) })
                }
            }
        };
    }
}

#[cfg(feature = "multi_thread")]
impl<T> GcMemberPtr<T>
where
    T: 'static + Send + Sync,
{
    /// Create a new member pointer, from a [GcMtPtr].
    pub(crate) fn new_mt_ptr(origin: Pin<DynObjectPtr>, sp: GcMtPtr<T>) -> Self {
        // SAFETY: this is safe because we will handle the reference-drop ourselves.
        unsafe { Self::new_ptr_mt(origin, GcMtPtr::release(sp)) }
    }
}

impl<T> GcPtrEq<GcPtr<T>> for GcMemberPtr<T>
where
    T: 'static,
{
    #[inline]
    fn ptr_eq(this: &Self, other: &GcPtr<T>) -> bool {
        GcPtr::ptr_eq(other, this)
    }
}

#[cfg(feature = "multi_thread")]
impl<T> GcPtrEq<GcMtPtr<T>> for GcMemberPtr<T>
where
    T: 'static + Send + Sync,
{
    #[inline]
    fn ptr_eq(this: &Self, other: &GcMtPtr<T>) -> bool {
        GcMtPtr::ptr_eq(other, this)
    }
}

impl<T> GcPtrEq<GcMemberPtr<T>> for GcMemberPtr<T>
where
    T: 'static,
{
    #[inline]
    fn ptr_eq(this: &Self, other: &GcMemberPtr<T>) -> bool {
        #[cfg(not(feature = "multi_thread"))]
        return ptr::eq(&*this.ptr, &*other.ptr);
        #[cfg(feature = "multi_thread")]
        return match (&this.ptr, &other.ptr) {
            (
                SingleOrMultiThreadPtr::SingleThread(this_ptr),
                SingleOrMultiThreadPtr::SingleThread(other_ptr),
            ) => ptr::eq(&**this_ptr, &**other_ptr),
            (SingleOrMultiThreadPtr::SingleThread(_), SingleOrMultiThreadPtr::MultiThread(_)) => {
                false
            }
            (SingleOrMultiThreadPtr::MultiThread(_), SingleOrMultiThreadPtr::SingleThread(_)) => {
                false
            }
            (
                SingleOrMultiThreadPtr::MultiThread(this_ptr),
                SingleOrMultiThreadPtr::MultiThread(other_ptr),
            ) => ptr::eq(&**this_ptr, &**other_ptr),
        };
    }
}

#[cfg(feature = "multi_thread")]
impl<T> GcPtrEq<GcMtMemberPtr<T>> for GcMemberPtr<T>
where
    T: 'static + Send + Sync,
{
    #[inline]
    fn ptr_eq(this: &Self, other: &GcMtMemberPtr<T>) -> bool {
        match &this.ptr {
            SingleOrMultiThreadPtr::MultiThread(this_ptr) => ptr::eq(&**this_ptr, &*other.ptr),
            _ => false,
        }
    }
}

#[cfg(feature = "weak_pointer")]
impl<T> GcPtrEq<crate::Weak<T>> for GcMemberPtr<T>
where
    T: 'static,
{
    #[inline]
    fn ptr_eq(this: &Self, other: &crate::Weak<T>) -> bool {
        #[cfg(not(feature = "multi_thread"))]
        return other
            .ptr
            .as_ref()
            .map(|other_ptr| ptr::eq(&*this.ptr, &**other_ptr))
            .unwrap_or(false);
        #[cfg(feature = "multi_thread")]
        return other
            .ptr
            .as_ref()
            .map(|other_ptr| match (&this.ptr, other_ptr) {
                (
                    SingleOrMultiThreadPtr::SingleThread(this_ptr),
                    SingleOrMultiThreadPtr::SingleThread(other_ptr),
                ) => ptr::eq(&**this_ptr, &**other_ptr),
                (
                    SingleOrMultiThreadPtr::SingleThread(_),
                    SingleOrMultiThreadPtr::MultiThread(_),
                ) => false,
                (
                    SingleOrMultiThreadPtr::MultiThread(_),
                    SingleOrMultiThreadPtr::SingleThread(_),
                ) => false,
                (
                    SingleOrMultiThreadPtr::MultiThread(this_ptr),
                    SingleOrMultiThreadPtr::MultiThread(other_ptr),
                ) => ptr::eq(&**this_ptr, &**other_ptr),
            })
            .unwrap_or(false);
    }
}

#[cfg(all(feature = "multi_thread", feature = "weak_pointer"))]
impl<T> GcPtrEq<crate::sync::Weak<T>> for GcMemberPtr<T>
where
    T: 'static + Send + Sync,
{
    #[inline]
    fn ptr_eq(this: &Self, other: &crate::sync::Weak<T>) -> bool {
        other
            .ptr
            .as_ref()
            .map(|other_ptr| match &this.ptr {
                SingleOrMultiThreadPtr::MultiThread(this_ptr) => ptr::eq(&**this_ptr, &**other_ptr),
                _ => false,
            })
            .unwrap_or(false)
    }
}

impl<T> Drop for GcMemberPtr<T>
where
    T: 'static,
{
    #[cfg(not(feature = "multi_thread"))]
    #[allow(
        clippy::missing_inline_in_public_items,
        reason = "The drop of a member function does a lot of complicated things. There's probably very little benefit to inlining this, and not inlining it hopefully allows for easier debugging."
    )]
    fn drop(&mut self) {
        let origin_generation = self.origin.get_generation_ptr();
        let ptr_generation = self.ptr.get_generation_ptr();

        self.origin
            .get_control_block()
            .deregister_edge(self.edge.as_ref().get_ref());

        #[cfg(feature = "single_generation")]
        {
            assert!(GenerationPtr::ptr_eq(&origin_generation, &ptr_generation));
            self.ptr.get_control_block().gc_if_zero_refs();
        }

        #[cfg(not(feature = "single_generation"))]
        if GenerationPtr::ptr_eq(&origin_generation, &ptr_generation) {
            self.ptr.get_control_block().gc_if_zero_refs();
        } else {
            assert!(origin_generation.id < ptr_generation.id);
            self.ptr.get_control_block().refcount_dec();
        }
    }

    #[cfg(feature = "multi_thread")]
    #[allow(
        clippy::missing_inline_in_public_items,
        reason = "The drop of a member function does a lot of complicated things. There's probably very little benefit to inlining this, and not inlining it hopefully allows for easier debugging."
    )]
    fn drop(&mut self) {
        match &self.ptr {
            SingleOrMultiThreadPtr::SingleThread(ptr) => {
                let origin_generation = self.origin.get_generation_ptr();
                let ptr_generation = ptr.get_generation_ptr();

                self.origin
                    .get_control_block()
                    .deregister_edge(self.edge.as_ref().get_ref());

                #[cfg(feature = "single_generation")]
                {
                    assert!(GenerationPtr::ptr_eq(&origin_generation, &ptr_generation));
                    ptr.get_control_block().gc_if_zero_refs();
                }

                #[cfg(not(feature = "single_generation"))]
                if GenerationPtr::ptr_eq(&origin_generation, &ptr_generation) {
                    ptr.get_control_block().gc_if_zero_refs();
                } else {
                    assert!(origin_generation.id < ptr_generation.id);
                    ptr.get_control_block().refcount_dec();
                }
            }
            SingleOrMultiThreadPtr::MultiThread(ptr) => {
                self.origin
                    .get_control_block()
                    .deregister_edge(self.edge.as_ref().get_ref());
                ptr.get_control_block().refcount_dec();
            }
        };
    }
}

impl<T> Deref for GcMemberPtr<T>
where
    T: 'static,
{
    type Target = T;

    /// Dereference the member pointer.
    ///
    /// # Panics
    ///
    /// If the origin of this member pointer has expired,
    /// then acquiring the pointer is no longer allowed and will cause a panic.
    #[inline]
    fn deref(&self) -> &Self::Target {
        if self.origin.object_state() == ObjectState::Expired {
            panic!("cannot dereference member pointers on targets that are unreachable");
        }

        #[cfg(not(feature = "multi_thread"))]
        return self.ptr.get_data();
        #[cfg(feature = "multi_thread")]
        return match &self.ptr {
            SingleOrMultiThreadPtr::SingleThread(ptr) => ptr.get_data(),
            SingleOrMultiThreadPtr::MultiThread(ptr) => ptr.get_data(),
        };
    }
}

impl<T> fmt::Debug for GcMemberPtr<T>
where
    T: 'static + Send + Sync + fmt::Debug,
{
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
        fmt::Debug::fmt(&**self, f)
    }
}

#[cfg(test)]
mod tests {
    use super::GcMemberPtr;
    use crate::prelude::GcMemberPtrNew;
    use crate::{GcPtr, Metadata};
    use std::sync::{Arc, Mutex, RwLock};

    #[derive(Debug)]
    struct Bla {
        n: Arc<Mutex<i32>>,
    }

    #[derive(Debug)]
    struct BlaParent {
        _bla: GcMemberPtr<Bla>,
    }

    impl Bla {
        fn new(n: Arc<Mutex<i32>>) -> GcPtr<Bla> {
            *n.lock().unwrap() += 1;
            GcPtr::new(|_| Bla { n })
        }
    }

    impl Drop for Bla {
        fn drop(&mut self) {
            *self.n.lock().unwrap() -= 1;
        }
    }

    impl BlaParent {
        fn new(bla: GcPtr<Bla>) -> GcPtr<BlaParent> {
            GcPtr::new(|metadata| BlaParent {
                _bla: metadata.new_pointer(bla),
            })
        }
    }

    struct Cycle {
        n: Arc<Mutex<i32>>,
        cptr: RwLock<Option<GcMemberPtr<Cycle>>>,
        metadata: Metadata,
    }

    impl Cycle {
        fn new(n: Arc<Mutex<i32>>) -> GcPtr<Cycle> {
            *n.lock().unwrap() += 1;
            GcPtr::new(|metadata| Cycle {
                n,
                cptr: RwLock::new(None),
                metadata,
            })
        }

        fn assign(&self, ptr: GcPtr<Cycle>) {
            *self.cptr.write().unwrap() = Some(self.metadata.new_pointer(ptr));
        }
    }

    impl Drop for Cycle {
        fn drop(&mut self) {
            *self.n.lock().unwrap() -= 1;
        }
    }

    #[test]
    fn create_pointer() {
        let n = Arc::new(Mutex::new(0));
        let bla = Bla::new(n.clone());
        let bla_parent = BlaParent::new(bla.clone());
        assert_eq!(*n.lock().unwrap(), 1);

        drop(bla);
        assert_eq!(
            *n.lock().unwrap(),
            1,
            "`bla` is to remain live, because `bla_parent` has a member-pointer pointing at it"
        );

        drop(bla_parent);
        assert_eq!(*n.lock().unwrap(), 0);
    }

    #[test]
    fn create_cycle() {
        let n = Arc::new(Mutex::new(0));
        let p = Cycle::new(n.clone());
        let q = Cycle::new(n.clone());
        assert_eq!(*n.lock().unwrap(), 2);

        p.assign(q.clone());
        q.assign(p.clone());
        assert_eq!(*n.lock().unwrap(), 2);

        drop(p);
        assert_eq!(
            *n.lock().unwrap(),
            2,
            "`cycle p` is to remain live, because `cycle q` has a member-pointer pointing at it"
        );

        // Recreate `q`.
        let p = q.cptr.read().unwrap().as_ref().unwrap().as_ptr();
        drop(q);
        assert_eq!(
            *n.lock().unwrap(),
            2,
            "`cycle q` is to remain live, because `cycle p` has a member-pointer pointing at it"
        );

        drop(p);
        assert_eq!(*n.lock().unwrap(), 0);
    }
}