Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add the Provider api to core::any #91970

Merged
merged 7 commits into from
Jun 10, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
376 changes: 373 additions & 3 deletions library/core/src/any.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
//! This module implements the `Any` trait, which enables dynamic typing
//! of any `'static` type through runtime reflection.
//! This module contains the `Any` trait, which enables dynamic typing
//! of any `'static` type through runtime reflection. It also contains the
//! `Provider` trait and accompanying API, which enable trait objects to provide
//! data based on typed requests, an alternate form of runtime reflection.
//!
//! # `Any` and `TypeId`
//!
//! `Any` itself can be used to get a `TypeId`, and has more features when used
//! as a trait object. As `&dyn Any` (a borrowed trait object), it has the `is`
Expand Down Expand Up @@ -37,7 +41,7 @@
//! assert_eq!(boxed_id, TypeId::of::<Box<dyn Any>>());
//! ```
//!
//! # Examples
//! ## Examples
//!
//! Consider a situation where we want to log out a value passed to a function.
//! We know the value we're working on implements Debug, but we don't know its
Expand Down Expand Up @@ -81,6 +85,73 @@
//! do_work(&my_i8);
//! }
//! ```
//!
//! # `Provider` and `Demand`
//!
//! `Provider` and the associated APIs support generic, type-driven access to data, and a mechanism
//! for implementers to provide such data. The key parts of the interface are the `Provider`
//! trait for objects which can provide data, and the [`request_value`] and [`request_ref`]
//! functions for requesting data from an object which implements `Provider`. Generally, end users
//! should not call `request_*` directly, they are helper functions for intermediate implementers
//! to use to implement a user-facing interface. This is purely for the sake of ergonomics, there is
//! safety concern here; intermediate implementers can typically support methods rather than
//! free functions and use more specific names.
//!
//! Typically, a data provider is a trait object of a trait which extends `Provider`. A user will
//! request data from a trait object by specifying the type of the data.
//!
//! ## Data flow
//!
//! * A user requests an object of a specific type, which is delegated to `request_value` or
//! `request_ref`
//! * `request_*` creates a `Demand` object and passes it to `Provider::provide`
//! * The data provider's implementation of `Provider::provide` tries providing values of
//! different types using `Demand::provide_*`. If the type matches the type requested by
//! the user, the value will be stored in the `Demand` object.
//! * `request_*` unpacks the `Demand` object and returns any stored value to the user.
//!
//! ## Examples
//!
//! ```
//! # #![feature(provide_any)]
//! use std::any::{Provider, Demand, request_ref};
//!
//! // Definition of MyTrait, a data provider.
//! trait MyTrait: Provider {
//! // ...
//! }
//!
//! // Methods on `MyTrait` trait objects.
//! impl dyn MyTrait + '_ {
//! /// Get a reference to a field of the implementing struct.
//! pub fn get_context_by_ref<T: ?Sized + 'static>(&self) -> Option<&T> {
//! request_ref::<T, _>(self)
//! }
//! }
//!
//! // Downstream implementation of `MyTrait` and `Provider`.
//! # struct SomeConcreteType { some_string: String }
//! impl MyTrait for SomeConcreteType {
//! // ...
//! }
//!
//! impl Provider for SomeConcreteType {
//! fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
//! // Provide a string reference. We could provide multiple values with
//! // different types here.
//! demand.provide_ref::<String>(&self.some_string);
//! }
//! }
//!
//! // Downstream usage of `MyTrait`.
//! fn use_my_trait(obj: &dyn MyTrait) {
//! // Request a &String from obj.
//! let _ = obj.get_context_by_ref::<String>().unwrap();
//! }
//! ```
//!
//! In this example, if the concrete type of `obj` in `use_my_trait` is `SomeConcreteType`, then
//! the `get_context_ref` call will return a reference to `obj.some_string` with type `&String`.

#![stable(feature = "rust1", since = "1.0.0")]

Expand Down Expand Up @@ -700,3 +771,302 @@ pub const fn type_name<T: ?Sized>() -> &'static str {
pub const fn type_name_of_val<T: ?Sized>(_val: &T) -> &'static str {
type_name::<T>()
}

///////////////////////////////////////////////////////////////////////////////
// Provider trait
///////////////////////////////////////////////////////////////////////////////

/// Trait implemented by a type which can dynamically provide values based on type.
#[unstable(feature = "provide_any", issue = "96024")]
pub trait Provider {
/// Data providers should implement this method to provide *all* values they are able to
/// provide by using `demand`.
nrc marked this conversation as resolved.
Show resolved Hide resolved
///
/// Note that the `provide_*` methods on `Demand` have short-circuit semantics: if an earlier
/// method has successfully provided a value, then later methods will not get an opportunity to
/// provide.
///
/// # Examples
///
/// Provides a reference to a field with type `String` as a `&str`, and a value of
/// type `i32`.
///
/// ```rust
/// # #![feature(provide_any)]
/// use std::any::{Provider, Demand};
/// # struct SomeConcreteType { field: String, num_field: i32 }
///
/// impl Provider for SomeConcreteType {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// demand.provide_ref::<str>(&self.field)
/// .provide_value::<i32, _>(|| self.num_field);
/// }
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
fn provide<'a>(&'a self, demand: &mut Demand<'a>);
}

/// Request a value from the `Provider`.
///
/// # Examples
///
/// Get a string value from a provider.
///
/// ```rust
/// # #![feature(provide_any)]
/// use std::any::{Provider, request_value};
///
/// fn get_string<P: Provider>(provider: &P) -> String {
/// request_value::<String, _>(provider).unwrap()
nrc marked this conversation as resolved.
Show resolved Hide resolved
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn request_value<'a, T, P>(provider: &'a P) -> Option<T>
where
T: 'static,
P: Provider + ?Sized,
{
request_by_type_tag::<'a, tags::Value<T>, P>(provider)
}

/// Request a reference from the `Provider`.
///
/// # Examples
///
/// Get a string reference from a provider.
///
/// ```rust
/// # #![feature(provide_any)]
/// use std::any::{Provider, request_ref};
///
/// fn get_str<P: Provider>(provider: &P) -> &str {
/// request_ref::<str, _>(provider).unwrap()
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn request_ref<'a, T, P>(provider: &'a P) -> Option<&'a T>
where
T: 'static + ?Sized,
P: Provider + ?Sized,
{
request_by_type_tag::<'a, tags::Ref<tags::MaybeSizedValue<T>>, P>(provider)
}

/// Request a specific value by tag from the `Provider`.
fn request_by_type_tag<'a, I, P>(provider: &'a P) -> Option<I::Reified>
where
I: tags::Type<'a>,
P: Provider + ?Sized,
{
let mut tagged = TaggedOption::<'a, I>(None);
provider.provide(tagged.as_demand());
tagged.0
}

///////////////////////////////////////////////////////////////////////////////
// Demand and its methods
///////////////////////////////////////////////////////////////////////////////

/// A helper object for providing data by type.
///
/// A data provider provides values by calling this type's provide methods.
#[unstable(feature = "provide_any", issue = "96024")]
#[repr(transparent)]
pub struct Demand<'a>(dyn Erased<'a> + 'a);
yaahc marked this conversation as resolved.
Show resolved Hide resolved

impl<'a> Demand<'a> {
/// Create a new `&mut Demand` from a `&mut dyn Erased` trait object.
fn new<'b>(erased: &'b mut (dyn Erased<'a> + 'a)) -> &'b mut Demand<'a> {
// SAFETY: transmuting `&mut (dyn Erased<'a> + 'a)` to `&mut Demand<'a>` is safe since
// `Demand` is repr(transparent).
unsafe { &mut *(erased as *mut dyn Erased<'a> as *mut Demand<'a>) }
}

/// Provide a value or other type with only static lifetimes.
///
/// # Examples
///
/// Provides a `String` by cloning.
///
/// ```rust
/// # #![feature(provide_any)]
/// use std::any::{Provider, Demand};
/// # struct SomeConcreteType { field: String }
///
/// impl Provider for SomeConcreteType {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// demand.provide_value::<String, _>(|| self.field.clone());
/// }
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn provide_value<T, F>(&mut self, fulfil: F) -> &mut Self
where
T: 'static,
F: FnOnce() -> T,
{
self.provide_with::<tags::Value<T>, F>(fulfil)
}

/// Provide a reference, note that the referee type must be bounded by `'static`,
/// but may be unsized.
///
/// # Examples
///
/// Provides a reference to a field as a `&str`.
///
/// ```rust
/// # #![feature(provide_any)]
/// use std::any::{Provider, Demand};
/// # struct SomeConcreteType { field: String }
///
/// impl Provider for SomeConcreteType {
/// fn provide<'a>(&'a self, demand: &mut Demand<'a>) {
/// demand.provide_ref::<str>(&self.field);
/// }
/// }
/// ```
#[unstable(feature = "provide_any", issue = "96024")]
pub fn provide_ref<T: ?Sized + 'static>(&mut self, value: &'a T) -> &mut Self {
self.provide::<tags::Ref<tags::MaybeSizedValue<T>>>(value)
}

/// Provide a value with the given `Type` tag.
fn provide<I>(&mut self, value: I::Reified) -> &mut Self
where
I: tags::Type<'a>,
{
if let Some(res @ TaggedOption(None)) = self.0.downcast_mut::<I>() {
res.0 = Some(value);
}
self
}

/// Provide a value with the given `Type` tag, using a closure to prevent unnecessary work.
fn provide_with<I, F>(&mut self, fulfil: F) -> &mut Self
where
I: tags::Type<'a>,
F: FnOnce() -> I::Reified,
{
if let Some(res @ TaggedOption(None)) = self.0.downcast_mut::<I>() {
res.0 = Some(fulfil());
}
self
}
}

#[unstable(feature = "provide_any", issue = "96024")]
impl<'a> fmt::Debug for Demand<'a> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Demand").finish_non_exhaustive()
}
}

///////////////////////////////////////////////////////////////////////////////
// Type tags
///////////////////////////////////////////////////////////////////////////////

mod tags {
//! Type tags are used to identify a type using a separate value. This module includes type tags
//! for some very common types.
//!
//! Currently type tags are not exposed to the user. But in the future, if you want to use the
//! Provider API with more complex types (typically those including lifetime parameters), you
//! will need to write your own tags.

use crate::marker::PhantomData;

/// This trait is implemented by specific tag types in order to allow
/// describing a type which can be requested for a given lifetime `'a`.
///
/// A few example implementations for type-driven tags can be found in this
/// module, although crates may also implement their own tags for more
/// complex types with internal lifetimes.
pub trait Type<'a>: Sized + 'static {
/// The type of values which may be tagged by this tag for the given
/// lifetime.
type Reified: 'a;
}

/// Similar to the [`Type`] trait, but represents a type which may be unsized (i.e., has a
/// `?Sized` bound). E.g., `str`.
pub trait MaybeSizedType<'a>: Sized + 'static {
type Reified: 'a + ?Sized;
}

impl<'a, T: Type<'a>> MaybeSizedType<'a> for T {
type Reified = T::Reified;
}

/// Type-based tag for types bounded by `'static`, i.e., with no borrowed elements.
#[derive(Debug)]
pub struct Value<T: 'static>(PhantomData<T>);

impl<'a, T: 'static> Type<'a> for Value<T> {
type Reified = T;
}

/// Type-based tag similar to [`Value`] but which may be unsized (i.e., has a `'Sized` bound).
#[derive(Debug)]
pub struct MaybeSizedValue<T: ?Sized + 'static>(PhantomData<T>);

impl<'a, T: ?Sized + 'static> MaybeSizedType<'a> for MaybeSizedValue<T> {
type Reified = T;
}

/// Type-based tag for reference types (`&'a T`, where T is represented by
/// `<I as MaybeSizedType<'a>>::Reified`.
#[derive(Debug)]
pub struct Ref<I>(PhantomData<I>);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm puzzled by the need for MaybeSizedType/MaybeSizedValue here.

Why can't Ref take something optionally-sized all the time?

pub struct Ref<I: ?Sized>(PhantomData<I>);

Maybe an update to the doc comment could help? The comment referencing T, which doesn't actually exist as a type parameter for it, makes it hard for me to follow. I think it's a tag for reference-to-I::Reified, if I'm reading the rest of the module correctly?

And every use of Ref (other that trait impls) seems to be tags::Ref<tags::MaybeSizedValue<T>>. I can't see any place that would want tags::Ref<tags::Value<T>> instead?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll try and add some docs to clarify. Essentially, it is not the I which is sized/unsized, but the type which I represents (I::Reified)


impl<'a, I: MaybeSizedType<'a>> Type<'a> for Ref<I> {
type Reified = &'a I::Reified;
}
}

/// An `Option` with a type tag `I`.
///
/// Since this struct implements `Erased`, the type can be erased to make a dynamically typed
/// option. The type can be checked dynamically using `Erased::tag_id` and since this is statically
/// checked for the concrete type, there is some degree of type safety.
#[repr(transparent)]
struct TaggedOption<'a, I: tags::Type<'a>>(Option<I::Reified>);

impl<'a, I: tags::Type<'a>> TaggedOption<'a, I> {
fn as_demand(&mut self) -> &mut Demand<'a> {
Demand::new(self as &mut (dyn Erased<'a> + 'a))
}
}

/// Represents a type-erased but identifiable object.
///
/// This trait is exclusively implemented by the `TaggedOption` type.
unsafe trait Erased<'a>: 'a {
/// The `TypeId` of the erased type.
fn tag_id(&self) -> TypeId;
}

unsafe impl<'a, I: tags::Type<'a>> Erased<'a> for TaggedOption<'a, I> {
fn tag_id(&self) -> TypeId {
TypeId::of::<I>()
}
}

#[unstable(feature = "provide_any", issue = "96024")]
impl<'a> dyn Erased<'a> + 'a {
/// Returns some reference to the dynamic value if it is tagged with `I`,
/// or `None` otherwise.
#[inline]
fn downcast_mut<I>(&mut self) -> Option<&mut TaggedOption<'a, I>>
where
I: tags::Type<'a>,
{
if self.tag_id() == TypeId::of::<I>() {
// SAFETY: Just checked whether we're pointing to an I.
Some(unsafe { &mut *(self as *mut Self).cast::<TaggedOption<'a, I>>() })
} else {
None
}
}
}
Loading