// SPDX-License-Identifier: BSD-2-Clause

/*

 * mem.rs - Memory handling helper structs and traits for the libcoap Rust Wrapper.

 * This file is part of the libcoap-rs crate, see the README and LICENSE files for

 * more information and terms of use.

 * Copyright © 2021-2023 The NAMIB Project Developers, all rights reserved.

 * See the README as well as the LICENSE file for more information.

 */

//! Code related to memory handling, especially for passing objects through FFI

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

use std::ffi::c_void;

use std::fmt::{Debug, Formatter};

use std::ops::{Deref, DerefMut};

use std::rc::{Rc, Weak};

/// Trait implemented by libcoap wrapper structs that contain an inner value that may be dropped

/// exclusively, i.e., that can be dropped with the additional check that there are no further

/// references to the inner value.

pub(crate) trait DropInnerExclusively {

    /// Consume this instance, ensuring that the inner (and potentially shared) part of the struct

    /// referenced by this instance is also dropped.

    ///

    /// # Panics

    ///

    /// Panics if the inner part of this struct cannot be exclusively dropped, i.e., it is still

    /// used by another instance.

    fn drop_exclusively(self);

}

/// A strong reference counted cell, created from an app data/user data pointer inside of a C

/// library struct.

///

/// This type is a wrapper around Rc<RefCell<D>> with some additional functions for creating from

/// or converting to raw pointers.

pub(crate) struct CoapFfiRcCell<D>(Rc<RefCell<D>>);

impl<D> CoapFfiRcCell<D> {

    /// Creates a new instance of CoapFfiRcCell, containing the provided value.

    /// Converts from a raw user data/application data pointer inside of a libcoap C library struct

    /// into the appropriate reference type.

    ///

    /// This is done by first restoring the `Rc<RefCell<D>>` using [Rc::from_raw()], then

    /// cloning and creating the [CoapFfiRcCell] from it (maintaining the original reference using

    /// [Rc::into_raw()]).

    ///

    /// Note that for the lifetime of this [CoapFfiRcCell], the reference counter of the

    /// underlying [Rc] is increased by one.

    ///

    /// # Safety

    /// For an explanation of the purpose of this struct and where it was originally intended to be

    /// used, see the struct-level documentation.

    ///

    /// To safely use this function, the following invariants must be kept:

    /// - ptr is a valid pointer to an Rc<RefCell<D>>

    /// Converts from a raw user data/application data pointer inside of a libcoap C library struct

    /// into the appropriate reference type.

    ///

    /// This is done by first restoring the `Weak<RefCell<D>>` using [Weak::from_raw()],

    /// upgrading it to a `Rc<RefCell<D>>` then cloning and creating the [CoapFfiRcCell] from the

    /// upgraded reference (restoring the raw pointer again afterwards using [Rc::downgrade()] and

    /// [Weak::into_raw()]).

    ///

    /// Note that for the lifetime of this [CoapFfiRcCell], the reference counter of the underlying

    /// [Rc] is increased by one.

    ///

    /// # Panics

    /// Panics if the provided Weak reference is orphaned.

    ///

    /// # Safety

    /// For an explanation of the purpose of this struct and where it was originally intended to be

    /// used, see the struct-level documentation.

    ///

    /// To safely use this function, the following invariants must be kept:

    /// - ptr is a valid pointer to a `Weak<RefCell<D>>`

    /// Converts from a raw user data/application data pointer inside of a libcoap C library struct

    /// into the underlying `Weak<RefCell<D>>`.

    ///

    /// This is done by restoring the `Weak<RefCell<D>>` using [Weak::from_raw()],

    ///

    /// Note that unlike [CoapFfiRcCell::clone_raw_weak()], this does not clone the weak reference

    /// inside of the pointer and instead restores the `Weak` directly from the pointer.

    /// This means that dropping the `Weak` returned from this function invalidates the pointer

    /// provided to this function.

    ///

    /// # Panics

    /// Panics if the provided Weak reference is orphaned.

    ///

    /// # Safety

    /// For an explanation of the purpose of this struct and where it was originally intended to be

    /// used, see the struct-level documentation.

    ///

    /// To safely use this function, the following invariants must be kept:

    /// - ptr is a valid pointer to a `Weak<RefCell<D>>`

    /// - as soon as the returned `Weak<RefCell<D>>` is dropped, the provided pointer is treated as

    ///   invalid.

    /// Converts from a raw user data/application data pointer inside of a libcoap C library struct

    /// into the underlying `Rc<RefCell<D>>`.

    ///

    /// This is done by restoring the `Rc<RefCell<D>>` using [Rc::from_raw()],

    ///

    /// Note that unlike [CoapFfiRcCell::clone_raw_rc()], this does not clone the weak reference

    /// inside of the pointer and instead restores the `Rc` directly from the pointer.

    /// This means that dropping the `Rc` returned from this function invalidates the pointer

    /// provided to this function and that the provided pointer must point to a valid

    /// `Rc<RefCell<D>>`.

    ///

    /// # Panics

    /// Panics if the provided Weak reference is orphaned.

    ///

    /// # Safety

    /// For an explanation of the purpose of this struct and where it was originally intended to be

    /// used, see the struct-level documentation.

    ///

    /// To safely use this function, the following invariants must be kept:

    /// - ptr is a valid pointer to a `Rc<RefCell<D>>`

    /// - as soon as the returned `Rc<RefCell<D>>` is dropped, the provided pointer is treated as

    ///   invalid.

    // Kept for consistency

    #[allow(unused)]

    /// Creates a raw reference, suitable for storage inside of a libcoap C library user/application

    /// data pointer.

    ///

    /// This function internally calls [Rc::clone()] and then [Rc::into_raw()] to create a pointer

    /// referring to a clone of the `Rc<RefCell<D>>` contained in this type.

    ///

    /// Note that this increases the reference count of the Rc by one.

    // Kept for consistency

    #[allow(unused)]

    /// Creates a raw reference, suitable for storage inside of a libcoap C library user/application

    /// data pointer.

    ///

    /// This function internally calls [Rc::downgrade()] and then [Weak::into_raw()] to create a

    /// pointer referring to a weak reference of the `Rc<RefCell<D>>` contained in this type.

    ///

    /// Note that this does not increase the reference count of the [Rc] by one. If you want to

    /// ensure that the underlying D is never cleaned up for as long as this pointer exists, you

    /// need to maintain this object for as least as long as the reference.

    /// Creates an immutable reference to the contained data type.

    ///

    /// # Panics

    /// Panics if borrowing here would violate Rusts aliasing rules.

    /// Creates a mutable reference to the contained data type.

    ///

    /// # Panics

    /// Panics if borrowing mutably here would violate Rusts aliasing rules.

}

impl<D: PartialEq> PartialEq for CoapFfiRcCell<D> {

}

impl<D: Eq + PartialEq> Eq for CoapFfiRcCell<D> {}

impl<D> Clone for CoapFfiRcCell<D> {

}

impl<D: Debug> Debug for CoapFfiRcCell<D> {

}

impl<T: Debug> DropInnerExclusively for CoapFfiRcCell<T> {

}

/// A reference counted cell suitable for passing through the FFI barrier, with the additional

/// possibility of passing an existing reference through this barrier.

///

/// This struct is similar to [CoapFfiRcCell], but provides additional functionality for

/// maintaining a reference through the FFI barrier using the [lend()] function.

#[derive(Debug)]

pub(crate) struct CoapLendableFfiRcCell<T: Debug>(Rc<RefCell<T>>, Rc<RefCell<Option<*mut T>>>);

impl<T: Debug> CoapLendableFfiRcCell<T> {

    /// Creates a new [`CoapLendableFfiRcCell`] from the given value.

    /// Mutably borrows from the value in this cell.

    ///

    /// This function will first check if a reference was lent through the FFI barrier using a call

    /// to [lend()].

    /// If so, it will take that reference (and return it to the cell when the returned

    /// [CoapLendableFfiRef] goes out of scope).

    /// If not, it will borrow the value normally by calling [Rc::borrow()] on the contained value.

    ///

    /// # Panics

    /// Panics if the value was already mutably borrowed.

            // SAFETY: The aliasing rules are ensured here by making sure that only one person may

            // retrieve the pointer value stored in the container at any time (as the value in the

            // Option is always retrieved using _take()_.

            // The validity of the pointer is ensured because the only way a value can be stored

            // here is by calling CoapLendableFfiRcCell::lend_ref_mut(), which converts a

            // reference into an always valid pointer.

        } else {

        }

    /// Immutably borrows from the value in this cell.

    ///

    /// This function will first check if a reference was lent through the FFI barrier using a call

    /// to [lend()].

    /// If so, it will take that reference (and return it to the cell when the returned

    /// [CoapLendableFfiRef] goes out of scope).

    /// If not, it will borrow the value normally by calling [Rc::borrow()] on the contained value.

    ///

    /// # Panics

    /// Panics if the value was already mutably borrowed.

            // SAFETY: The aliasing rules are ensured here by making sure that only one person may

            // retrieve the pointer value stored in the container at any time (as the value in the

            // Option is always retrieved using _take()_.

            // The validity of the pointer is ensured because the only way a value can be stored

            // here is by calling CoapLendableFfiRcCell::lend_ref_mut(), which converts a

            // reference into an always valid pointer.

            // TODO we may want to allow multiple immutable borrows at some point(?)

        } else {

        }

    /// Create a raw pointer to this cell, suitable for storage in a libcoap application data

    /// pointer.

    ///

    /// Internally, this function creates a clone of this cell, wraps this cell in a `Box` and then

    /// converts this value into a pointer using [Box::into_raw].

    ///

    /// It is in the callers responsibility to free the memory associated with this `Box`, e.g., by

    /// calling [from_raw_box()] and then dropping the value.

    // Kept for consistency

    #[allow(unused)]

    /// Create a raw pointer to this cell, suitable for storage in a libcoap application data

    /// pointer.

    ///

    /// Internally, this function creates a weak clone of this cell, wraps this cell in a `Box` and

    /// then converts this value into a pointer using [Box::into_raw].

    ///

    /// It is in the callers responsibility to free the memory associated with this `Box`, e.g., by

    /// calling [CoapLendableFfiWeakCell::from_raw_box()] and then dropping the value.

    /// Creates a new instance of this struct by cloning from a raw pointer pointing to a

    /// `Box<CoapLendableFfiRcCell<T>`.

    ///

    /// # Safety

    /// The provided pointer must point to a valid instance of `Box<CoapLendableFfiRcCell<T>`.

    // Kept for consistency

    #[allow(unused)]

    /// Creates a new instance of this struct by cloning from a raw pointer pointing to a

    /// `Box<CoapLendableFfiWeakCell<T>`.

    ///

    /// # Panics

    /// Panics if the provided weak cell is orphaned.

    ///

    /// # Safety

    /// The provided pointer must point to a valid instance of `Box<CoapLendableFfiWeakCell<T>`.

    /// Restores a `Box<CoapLendableFfiRcCell<T>>` from a raw pointer.

    ///

    /// Note that unlike [clone_raw_rc_box()], this function does not create a clone but directly

    /// restores the underlying provided box.

    /// As soon as the returned value is dropped, the provided pointer is therefore invalid.

    ///

    /// # Safety

    /// The provided pointer must point to a valid instance of `Box<CoapLendableFfiRcCell<T>`.

    // Kept for consistency

    #[allow(unused)]

    /// Stores a mutable reference to an instance of T for later retrieval by code running on the

    /// other side of the FFI barrier.

    ///

    /// This function can be used to pass a previously borrowed value to other users of this cell

    /// through the FFI barrier _without_ intermittently releasing the borrow.

    ///

    /// The reference will be lent for as long as the returned [CoapLendableFfiRefLender<'a, T>] is

    /// not dropped.

        );

    /// Creates a weak version of this reference counted cell by downgrading its components.

}

impl<T: Debug> Clone for CoapLendableFfiRcCell<T> {

}

/// The weak variant of a [CoapLendableFfiRcCell].

#[derive(Debug)]

pub(crate) struct CoapLendableFfiWeakCell<T: Debug>(Weak<RefCell<T>>, Weak<RefCell<Option<*mut T>>>);

impl<T: Debug> Clone for CoapLendableFfiWeakCell<T> {

}

impl<T: Debug> CoapLendableFfiWeakCell<T> {

    /// Attempts to upgrade this weak cell into a full [CoapLendableFfiRcCell<T>], returning None

    /// if the underlying value was already dropped.

    /// Restores a `Box<CoapLendableFfiWeakCell<T>>` from a raw pointer.

    ///

    /// Note that unlike [CoapLendableFfiRcCell<T>::clone_raw_weak_box()], this function does not

    /// create a clone but directly restores the underlying provided box.

    /// As soon as the returned value is dropped, the provided pointer is therefore invalid.

    ///

    /// # Safety

    /// The provided pointer must point to a valid instance of `Box<CoapLendableFfiWeakCell<T>`.

}

/// A token that is held by the lender of a mutable reference.

///

/// As long as this token is held, the mutable reference provided to [CoapLendableFfiRcCell] can be

/// borrowed by other functions owning clones of the same [CoapLendableFfiRcCell].

///

/// When this value is dropped, it will check whether the lent reference is currently used

/// elsewhere and panic/abort if this is the case, as this would violate the Rust aliasing rules.

pub(crate) struct CoapLendableFfiRefLender<'a, T> {

    lent_ref: &'a mut T,

    lent_ptr_ctr: Weak<RefCell<Option<*mut T>>>,

}

impl<'a, T> CoapLendableFfiRefLender<'a, T> {

    /// Create a new lender token from the given reference.

}

impl<T> Drop for CoapLendableFfiRefLender<'_, T> {

            )

}

/// A non-mutable reference created by borrowing mutably from a [CoapFfiRcCell] using

/// [CoapFfiRcCell::borrow_mut()].

pub(crate) enum CoapLendableFfiRef<'a, T> {

    Owned(Ref<'a, T>),

    Borrowed(&'a mut T, Rc<RefCell<Option<*mut T>>>),

}

impl<T> Deref for CoapLendableFfiRef<'_, T> {

    type Target = T;

        }

}

impl<T> Drop for CoapLendableFfiRef<'_, T> {

            );

            );

}

/// A mutable reference created by borrowing mutably from a [CoapFfiRcCell] using

/// [CoapFfiRcCell::borrow_mut()].

pub(crate) enum CoapLendableFfiRefMut<'a, T> {

    Owned(RefMut<'a, T>),

    Borrowed(&'a mut T, Rc<RefCell<Option<*mut T>>>),

}

impl<T> Deref for CoapLendableFfiRefMut<'_, T> {

    type Target = T;

        }

}

impl<T> DerefMut for CoapLendableFfiRefMut<'_, T> {

        }

}

impl<T> Drop for CoapLendableFfiRefMut<'_, T> {

            );

            );

}