Provider-style API for Context

[jkarneges]

Proposal

Changelog

• 2025-03-01: Initial draft.

Problem statement

Currently, Context only carries a Waker, but there is interest in having it carry other kinds of data. There is also a general practice in the ecosystem of sharing data between executors and futures via thread-locals or globals that would arguably be better shared via Context, if it were possible.

Motivating examples or use cases

Use-cases for sharing more kinds of data via Context include LocalWaker, Context reactor hook ACP, and context_rs crate.

Solution sketch

To solve this, we can change Context to carry arbitrary extension data via an API similar to the one used by error_generic_member_access. At first it could reuse Request and other types directly from core::error, but it could be good to move those things to a common area if both the error & context usages are stabilized.

trait Provider {
    fn provide<'a>(&'a self, request: &mut Request<'a>) {}
    fn provide_mut<'a>(&'a mut self, request: &mut Request<'a>) {}
}

impl ContextBuilder {
    fn provider(self, provider: &'a mut (dyn Provider + 'static)) -> Self;
}

impl Context {
    fn request_value<T>(&self) -> Option<T>;
    fn request_ref<T>(&self) -> Option<&T>;
    fn request_mut<T>(&mut self) -> Option<&mut T>;
}

Basic usage:

struct MyExtensionData {
    executor_name: String,
}

struct MyProvider {
    ext: MyExtensionData,
}

impl Provider for MyProvider {
    fn provide<'a>(&'a self, request: &mut Request<'a>) {
        request.provide_ref::<MyExtensionData>(&self.ext);
    }
}

let mut provider = MyProvider {
    ext: MyExtensionData {
        executor_name: "foo".to_string(),
    },
};

let cx = ContextBuilder::from_waker(&waker).provider(&mut provider).build();

if let Some(ext) = cx.request_ref::<MyExtensionData>() {
    println!("{}", ext.executor_name);
}

Inheritance

Combinators that manage their own wakers will want to ensure the provider from an earlier context is carried over into any new contexts. For this, the ContextBuilder::from() method from context_ext can be used.

Overriding extensions

Not only do we want a way for Context to carry multiple extensions, which the provider-style API solves, we also want a way for extensions to be added/overridden later on. For example, an executor may want to expose "reactor" & "spawner" interfaces from the top level, but then deeper in the call stack a "nursery" may want to override just the spawner (while allowing the reactor to still be accessible), and yet some other code path may want to introduce a "budgeter" for fair/weighted processing of some subset of work. These effects are achieved by having the context forward the provider calls to the parent provider after using ContextBuilder::from().

Example overriding a "spawner":

struct TopLevelProvider {
    reactor: Rc<dyn Reactor>,
    spawner: Rc<dyn Spawner>,
}

impl Provider for TopLevelProvider {
    fn provide<'a>(&'a self, request: &mut Request<'a>) {
        request
            .provide_ref::<dyn Reactor>(&*self.reactor)
            .provide_ref::<dyn Spawner>(&*self.spawner);
    }
}

struct NestedProvider {
    spawner: Rc<dyn Spawner>,
}

impl Provider for NestedProvider {
    fn provide<'a>(&'a self, request: &mut Request<'a>) {
        request.provide_ref::<dyn Spawner>(&*self.spawner);
    }
}

let mut top_provider = TopLevelProvider {
    reactor,
    spawner: top_spawner,
};

let mut top_cx = ContextBuilder::from_waker(&waker).provider(&mut top_provider).build();

let mut nested_provider = NestedProvider {
    spawner: nested_spawner,
};

let mut nested_cx = ContextBuilder::from(&mut top_cx).provider(&mut nested_provider).build();

// receive the top provider's reactor through the nested context
let reactor = nested_cx.request_ref::<dyn Reactor>().unwrap();

// receive the nested spawner from the nested context
let spawner = nested_cx.request_ref::<dyn Spawner>().unwrap();

Alternatives

• Share data using thread local or globals.
• Stabilize context_ext instead.

This proposal addresses some issues with context_ext:

• Passing refs is sound, and works out of the box.
• It doesn't need to be blindly stabilized. context_ext was intended to be stabilized without knowing what the most desirable data structure/mechanism for managing multiple extensions might be, in order to enable the ecosystem figure it out. Instead, this provider-style API is intended to be the desirable mechanism from the get-go. It supports returning multiple types, and overriding is possible by forwarding calls.

Links and related work

• LocalWaker
• Context reactor hook ACP
• context_rs crate
• context_ext feature

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.