Diffstat (limited to 'src/protocol.rs')
| -rw-r--r-- | src/protocol.rs | 89 |
1 files changed, 87 insertions, 2 deletions
diff --git a/src/protocol.rs b/src/protocol.rs index 124d270..acd22b8 100644 --- a/src/protocol.rs +++ b/src/protocol.rs @@ -1,13 +1,53 @@ +//! # 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; } @@ -17,15 +57,41 @@ impl<T: Protocol> ProtocolExt for 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>>; } @@ -35,7 +101,7 @@ impl<'ctx, T: Implementer<'ctx> + ?Sized> ImplementerExt<'ctx> for T { Some(interface) => match interface.downcast::<P>() { Ok(implementation) => Some(implementation), Err(interface) => panic!( - "unexpected type ID for protocol implementation: `{:?}`, expected: `{:?}`", + "unexpected protocol implementation: `{:?}`, expected: `{:?}`", interface.id(), P::id() ), @@ -45,6 +111,7 @@ impl<'ctx, T: Implementer<'ctx> + ?Sized> ImplementerExt<'ctx> for T { } } +/// Implement [`Implementer`] and [`Implementation`] for a set of protocols. #[doc(hidden)] #[macro_export] macro_rules! implementer { @@ -90,17 +157,30 @@ mod any_implementation { 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(), @@ -111,6 +191,10 @@ mod any_implementation { } } + /// 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`. @@ -118,13 +202,14 @@ mod any_implementation { // type. // // An important note is this method takes ownership. Which allows it to return - // the borrow with the `'walking` lifetime instead of a sub-borrow. + // 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 } |