//! # Design
//! The design of protocols is based on an idea found in the [`gdbstub`](https://docs.rs/gdbstub/latest/gdbstub/target/ext/index.html) crate.
//! This idea is of so called inlinable dyn extension traits.
//! However, in the form given in `gdbstub` they can't be used for arbitrary interfaces.
//! The main trait still needs to know about all the possible protocols.
//! That is where this module comes in.
//!
//! This module implements a technique we name dynamic inlinable dyn extension traits (DIDETs). 
//! DIDETs adds one more layer to IDETs. Instead of a trait that knows all the possible protocols,
//! we have a single trait [`Implementer`] that allows looking up an extension trait
//! using a type ID. This may seem like it defeats the purpose of IDETs, that being to
//! make them inlinable. However, it turns out LLVM (the optimizer) is able to see
//! through this style of runtime reflection. As such, we still gain the benefits of
//! IDETs but with more flexability.
//! Protocols can now be defined in *any* crate and used between arbitrary crates.
//!
//! A protocol is a special trait that can participate as a DIDET. The only thing needed
//! for a protocol is an associated trait object. Because we need to use the
//! [`TypeId`][core::any::TypeId] of a protocol to perform reflection, we can't just use
//! the trait object itself as the protocol type. Instead an uninhabited type is used
//! as a marker for the trait.
//!
//! We then "implement" a protocol for a type by using [`Implementation`]. This provides
//! a mapping from `T` to the protocol's trait object.
//! By itself, [`Implementation`] is not enough for DIDET. A type also needs to implement
//! [`Implementer`] which allows looking up a particular [`Implementation`] trait object
//! from a [`ProtocolId`].
//!
//! The implementation of DIDETs defined by this module allows [`Implementer`] to be object safe.
//! This is done via the help of the [`AnyImpl`] type. This is not required for the core
//! idea of DIDETs.

mod id;

pub use any_implementation::AnyImpl;
pub use id::ProtocolId;

/// An interface for interfaces.
pub trait Protocol: 'static {
    /// The trait object for the interface.
    ///
    /// The trait this object is of, is the actual interface.
    ///
    /// Note, this types is not required to be a trait object, but it is expected.
    type Object<'a, 'ctx: 'a>;
}

/// Extension trait for getting the ID of a protocol.
pub trait ProtocolExt: Protocol {
    /// Get the protocol's ID.
    fn id() -> ProtocolId;
}

impl<T: Protocol> ProtocolExt for T {
    fn id() -> ProtocolId {
        ProtocolId::of::<T>()
    }
}

/// An implementer of zero, one or more protocols.
///
/// Types that implement this trait have a form of reflection over the traits they implement.
/// The only traits accessible using this are ones that are described by a protocol.
pub trait Implementer<'ctx> {
    /// Lookup the interface for a given protocol.
    ///
    /// The returned implementation is expected to just be `self` but as a
    /// `&mut dyn Implementation<'ctx, P>`. This is not required though.
    ///
    /// The returned [`AnyImpl`] could be for a different protocol; This is considered
    /// a bug in an implementation and can be resolved via a panic. This is how
    /// [`ImplementerExt::interface_for`] behaves.
    /// 
    /// If `self` doesn't implement the given protocol, then a `None` is returned.
    fn interface(&mut self, id: ProtocolId) -> Option<AnyImpl<'_, 'ctx>>;
}

/// An implementation of a protocol.
///
/// This is a formalization of `self as &mut dyn Trait`.
pub trait Implementation<'ctx, P: Protocol> {
    /// Convert to the trait object for the protocol.
    ///
    /// Its expected that the returned value is just `self` acting as a trait object.
    fn as_object(&mut self) -> P::Object<'_, 'ctx>;
}

/// Extension trait for getting the implementation of a protocol.
pub trait ImplementerExt<'ctx>: Implementer<'ctx> {
    /// Get an implementation given a protocol type.
    ///
    /// This wraps [`Implementer::interface`] and [`AnyImpl::downcast`].
    /// If [`Implementer::interface`] returns a [`AnyImpl`] for the wrong protocol then a panic is
    /// generated.
    fn interface_for<P: Protocol>(&mut self) -> Option<&mut dyn Implementation<'ctx, P>>;
}

impl<'ctx, T: Implementer<'ctx> + ?Sized> ImplementerExt<'ctx> for T {
    fn interface_for<P: Protocol>(&mut self) -> Option<&mut dyn Implementation<'ctx, P>> {
        match self.interface(P::id()) {
            Some(interface) => match interface.downcast::<P>() {
                Ok(implementation) => Some(implementation),
                Err(interface) => panic!(
                    "unexpected protocol implementation: `{:?}`, expected: `{:?}`",
                    interface.id(),
                    P::id()
                ),
            },
            None => None,
        }
    }
}

/// Implement [`Implementer`] and [`Implementation`] for a set of protocols.
#[doc(hidden)]
#[macro_export]
macro_rules! implementer {
    {
        impl[$ctx:lifetime $($generic:tt)*] $name:ty = [$($protocol:ty),* $(,)?];
    } => {
        impl<$ctx $($generic)*> $crate::protocol::Implementer<$ctx> for $name {
            #[inline]
            fn interface(&mut self, id: $crate::protocol::ProtocolId) -> ::core::option::Option<$crate::protocol::AnyImpl<'_, $ctx>> {
                match id {
                    $(id if id == $crate::protocol::ProtocolId::of::<$protocol>() => Some($crate::protocol::AnyImpl::new::<$protocol>(self)),)*
                    _ => None
                }
            }
        }

        $crate::implementer! {
            $ctx $name [$($protocol),*] [$($generic)*]
        }
    };
    {
        $ctx:lifetime $name:ty [$protocol:ty] [$($generic:tt)*]
    } => {
        impl<$ctx $($generic)*> $crate::protocol::Implementation<$ctx, $protocol> for $name {
            fn as_object(&mut self) -> <$protocol as $crate::protocol::Protocol>::Object<'_, $ctx> {
                self
            }
        }
    };
    {
        $ctx:lifetime $name:ty [$($protocol:ty),*] $generic:tt
    } => {
        $($crate::implementer! {
            $ctx $name [$protocol] $generic
        })*
    };
}
#[doc(inline)]
pub use implementer;

mod any_implementation {
    use core::{marker::PhantomData, mem::MaybeUninit};

    use super::{Implementation, Protocol, ProtocolExt, ProtocolId};

    /// Helper trait to make sure AnyImpl has the correct properties.
    trait ErasedImplementation<'ctx> {}

    /// Size of a trait object.
    /// This should always be 2 pointers in size.
    const DYN_PTR_SIZE: usize = core::mem::size_of::<&mut dyn ErasedImplementation<'static>>();

    /// A [`Implementation`] for any `P`.
    ///
    /// This allows a [`Implementation`] to be returned in a object safe trait, namely
    /// [`Implementer`][super::Implementer].
    pub struct AnyImpl<'a, 'ctx> {
        /// ID of the protocol the ptr is for.
        id: ProtocolId,

        /// A trait object pointer stored in raw form.
        fat_ptr: MaybeUninit<[u8; DYN_PTR_SIZE]>,

        /// A marker for what `fat_ptr` is storing.
        _marker: PhantomData<&'a mut dyn ErasedImplementation<'ctx>>,
    }

    impl<'a, 'ctx> AnyImpl<'a, 'ctx> {
        /// Wrap a [`Implementation`] trait object to erase it's `P` type.
        pub fn new<P: Protocol>(implementation: &'a mut dyn Implementation<'ctx, P>) -> Self {
            Self {
                id: P::id(),
                // SAFETY: A maybe uninit array of bytes can hold any pointer.
                // Additionally, transmute makes sure the size is correct.
                fat_ptr: unsafe { core::mem::transmute(implementation) },
                _marker: PhantomData,
            }
        }

        /// Downcast to a [`Implementation`] trait object with a given `P` type.
        ///
        /// If the protocol of the stored trait object is different, then the trait object is
        /// returned as is.
        pub fn downcast<P: Protocol>(self) -> Result<&'a mut dyn Implementation<'ctx, P>, Self> {
            if self.id == P::id() {
                // SAFETY: Only `new` can make a value of this type, and it stores the ID of `P`.
                // If the IDs are equal then we can act like any and downcast back to the real
                // type.
                //
                // An important note is this method takes ownership. Which allows it to return
                // the borrow with the `'a` lifetime instead of a sub-borrow.
                Ok(unsafe { core::mem::transmute(self.fat_ptr) })
            } else {
                Err(self)
            }
        }

        /// ID of the protocol this [`Implementation`] is for.
        pub fn id(&self) -> ProtocolId {
            self.id
        }
    }
}