Tracking Issue for LocalWaker #118959

tvallotton · 2023-12-15T01:45:52Z

Feature gate: #![feature(local_waker)]

This is a tracking issue for support for local wakers on Context. This allows libraries to hold non thread safe data on their wakers, guaranteeing at compile time that the wakers will not be sent across threads. It includes a ContextBuilder type for building contexts.

Public API

impl Context {
    fn local_waker(&self) -> &LocalWaker;
    fn try_waker(&self) -> Option<Waker>;
}

impl ContextBuilder {
   fn from_local_waker(self) -> Self;
   fn from_waker(self) -> Self;
   fn waker(self, waker: Waker);
   fn local_waker(self, waker: LocalWaker);
   fn build(self) -> Context;
}

impl From<&mut Context> for ContextBuilder;

pub trait LocalWake {
    fn wake(self: Rc<Self>);
}

Steps / History

Implementation:
- Add LocalWaker and ContextBuilder types to core, and LocalWake trait to alloc. #118960
Have the @rust-lang/wg-async approve the API
Final comment period (FCP)¹
Stabilization PR

Unresolved Questions

Should runtimes be allowed to not define a waker?

Relevant links

https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

The text was updated successfully, but these errors were encountered:

…ulacrum Add LocalWaker and ContextBuilder types to core, and LocalWake trait to alloc. Implementation for rust-lang#118959.

Rollup merge of rust-lang#118960 - tvallotton:local_waker, r=Mark-Simulacrum Add LocalWaker and ContextBuilder types to core, and LocalWake trait to alloc. Implementation for rust-lang#118959.

tvallotton · 2024-02-12T14:02:05Z

@zzwxh

If I don't intend to support cross-thread wake-ups, it's best not to force me to provide a dummy Waker that pretends to support cross-thread wake-ups.

I agree, it would be best if users could panic on the call to cx.waker() rather than in the call to waker.wake().

ContextBuilder should allow the asynchronous runtime to explicitly specify which type of Waker it supports (or both), and the Future should have the ability to retrieve this information.

The feature used to work exactly like this, offering a ContextBuilder::from_local_waker method, and a Context::try_waker method. However, too many concerns were raised about compatibility, and I decided that this was not a hill I was willing to die on. Note that it is still possible to reintroduce these methods in the future without breaking changes.

Thomasdezeeuw · 2024-02-12T14:53:48Z

Context::try_waker does not introduce breaking changes, and I don't understand what concerns anyone has. We just need to deprecate Context::from_raw and Context::waker and use the new API instead.

I'm not sure you know what you're saying here. "Just" deprecating a crucial API for all Futures is bad idea. It will break all existing Futures and creates massive churn.

tvallotton · 2024-02-12T15:00:07Z

@zzwxh

Context::try_waker does not introduce breaking changes

Yes, this is what I said.

We just need to deprecate Context::from_raw and Context::waker and use the new API instead.

No, Context::waker and Context::from_waker are still useful and should not be deprecated, even if we decide to support optional wakers.

Thomasdezeeuw · 2024-02-12T15:09:54Z

@zzwxh it's not ok that you deleted your comment. It's hard to read back a discussion that way.

…ulacrum Add LocalWaker and ContextBuilder types to core, and LocalWake trait to alloc. Implementation for rust-lang#118959.

Add `Context::ext` This change enables `Context` to carry arbitrary extension data via a single `&mut dyn Any` field. ```rust #![feature(context_ext)] impl Context { fn ext(&mut self) -> &mut dyn Any; } impl ContextBuilder { fn ext(self, data: &'a mut dyn Any) -> Self; fn from(cx: &'a mut Context<'_>) -> Self; fn waker(self, waker: &'a Waker) -> Self; } ``` Basic usage: ```rust struct MyExtensionData { executor_name: String, } let mut ext = MyExtensionData { executor_name: "foo".to_string(), }; let mut cx = ContextBuilder::from_waker(&waker).ext(&mut ext).build(); if let Some(ext) = cx.ext().downcast_mut::<MyExtensionData>() { println!("{}", ext.executor_name); } ``` Currently, `Context` only carries a `Waker`, but there is interest in having it carry other kinds of data. Examples include [LocalWaker](rust-lang#118959), [a reactor interface](rust-lang/libs-team#347), and [multiple arbitrary values by type](https://docs.rs/context-rs/latest/context_rs/). 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. The `ext` field would provide a low friction (to stabilization) solution to enable experimentation. It would enable experimenting with what kinds of data we want to carry as well as with what data structures we may want to use to carry such data. Dedicated fields for specific kinds of data could still be added directly on `Context` when we have sufficient experience or understanding about the problem they are solving, such as with `LocalWaker`. The `ext` field would be for data for which we don't have such experience or understanding, and that could be graduated to dedicated fields once proven. Both the provider and consumer of the extension data must be aware of the concrete type behind the `Any`. This means it is not possible for the field to carry an abstract interface. However, the field can carry a concrete type which in turn carries an interface. There are different ways one can imagine an interface-carrying concrete type to work, hence the benefit of being able to experiment with such data structures. ## Passing interfaces Interfaces can be placed in a concrete type, such as a struct, and then that type can be casted to `Any`. However, one gotcha is `Any` cannot contain non-static references. This means one cannot simply do: ```rust struct Extensions<'a> { interface1: &'a mut dyn Trait1, interface2: &'a mut dyn Trait2, } let mut ext = Extensions { interface1: &mut impl1, interface2: &mut impl2, }; let ext: &mut dyn Any = &mut ext; ``` To work around this without boxing, unsafe code can be used to create a safe projection using accessors. For example: ```rust pub struct Extensions { interface1: *mut dyn Trait1, interface2: *mut dyn Trait2, } impl Extensions { pub fn new<'a>( interface1: &'a mut (dyn Trait1 + 'static), interface2: &'a mut (dyn Trait2 + 'static), scratch: &'a mut MaybeUninit<Self>, ) -> &'a mut Self { scratch.write(Self { interface1, interface2, }) } pub fn interface1(&mut self) -> &mut dyn Trait1 { unsafe { self.interface1.as_mut().unwrap() } } pub fn interface2(&mut self) -> &mut dyn Trait2 { unsafe { self.interface2.as_mut().unwrap() } } } let mut scratch = MaybeUninit::uninit(); let ext: &mut Extensions = Extensions::new(&mut impl1, &mut impl2, &mut scratch); // ext can now be casted to `&mut dyn Any` and back, and used safely let ext: &mut dyn Any = ext; ``` ## Context inheritance Sometimes when futures poll other futures they want to provide their own `Waker` which requires creating their own `Context`. Unfortunately, polling sub-futures with a fresh `Context` means any properties on the original `Context` won't get propagated along to the sub-futures. To help with this, some additional methods are added to `ContextBuilder`. Here's how to derive a new `Context` from another, overriding only the `Waker`: ```rust let mut cx = ContextBuilder::from(parent_cx).waker(&new_waker).build(); ```

Rollup merge of rust-lang#123203 - jkarneges:context-ext, r=Amanieu Add `Context::ext` This change enables `Context` to carry arbitrary extension data via a single `&mut dyn Any` field. ```rust #![feature(context_ext)] impl Context { fn ext(&mut self) -> &mut dyn Any; } impl ContextBuilder { fn ext(self, data: &'a mut dyn Any) -> Self; fn from(cx: &'a mut Context<'_>) -> Self; fn waker(self, waker: &'a Waker) -> Self; } ``` Basic usage: ```rust struct MyExtensionData { executor_name: String, } let mut ext = MyExtensionData { executor_name: "foo".to_string(), }; let mut cx = ContextBuilder::from_waker(&waker).ext(&mut ext).build(); if let Some(ext) = cx.ext().downcast_mut::<MyExtensionData>() { println!("{}", ext.executor_name); } ``` Currently, `Context` only carries a `Waker`, but there is interest in having it carry other kinds of data. Examples include [LocalWaker](rust-lang#118959), [a reactor interface](rust-lang/libs-team#347), and [multiple arbitrary values by type](https://docs.rs/context-rs/latest/context_rs/). 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. The `ext` field would provide a low friction (to stabilization) solution to enable experimentation. It would enable experimenting with what kinds of data we want to carry as well as with what data structures we may want to use to carry such data. Dedicated fields for specific kinds of data could still be added directly on `Context` when we have sufficient experience or understanding about the problem they are solving, such as with `LocalWaker`. The `ext` field would be for data for which we don't have such experience or understanding, and that could be graduated to dedicated fields once proven. Both the provider and consumer of the extension data must be aware of the concrete type behind the `Any`. This means it is not possible for the field to carry an abstract interface. However, the field can carry a concrete type which in turn carries an interface. There are different ways one can imagine an interface-carrying concrete type to work, hence the benefit of being able to experiment with such data structures. ## Passing interfaces Interfaces can be placed in a concrete type, such as a struct, and then that type can be casted to `Any`. However, one gotcha is `Any` cannot contain non-static references. This means one cannot simply do: ```rust struct Extensions<'a> { interface1: &'a mut dyn Trait1, interface2: &'a mut dyn Trait2, } let mut ext = Extensions { interface1: &mut impl1, interface2: &mut impl2, }; let ext: &mut dyn Any = &mut ext; ``` To work around this without boxing, unsafe code can be used to create a safe projection using accessors. For example: ```rust pub struct Extensions { interface1: *mut dyn Trait1, interface2: *mut dyn Trait2, } impl Extensions { pub fn new<'a>( interface1: &'a mut (dyn Trait1 + 'static), interface2: &'a mut (dyn Trait2 + 'static), scratch: &'a mut MaybeUninit<Self>, ) -> &'a mut Self { scratch.write(Self { interface1, interface2, }) } pub fn interface1(&mut self) -> &mut dyn Trait1 { unsafe { self.interface1.as_mut().unwrap() } } pub fn interface2(&mut self) -> &mut dyn Trait2 { unsafe { self.interface2.as_mut().unwrap() } } } let mut scratch = MaybeUninit::uninit(); let ext: &mut Extensions = Extensions::new(&mut impl1, &mut impl2, &mut scratch); // ext can now be casted to `&mut dyn Any` and back, and used safely let ext: &mut dyn Any = ext; ``` ## Context inheritance Sometimes when futures poll other futures they want to provide their own `Waker` which requires creating their own `Context`. Unfortunately, polling sub-futures with a fresh `Context` means any properties on the original `Context` won't get propagated along to the sub-futures. To help with this, some additional methods are added to `ContextBuilder`. Here's how to derive a new `Context` from another, overriding only the `Waker`: ```rust let mut cx = ContextBuilder::from(parent_cx).waker(&new_waker).build(); ```

Add `Context::ext` This change enables `Context` to carry arbitrary extension data via a single `&mut dyn Any` field. ```rust #![feature(context_ext)] impl Context { fn ext(&mut self) -> &mut dyn Any; } impl ContextBuilder { fn ext(self, data: &'a mut dyn Any) -> Self; fn from(cx: &'a mut Context<'_>) -> Self; fn waker(self, waker: &'a Waker) -> Self; } ``` Basic usage: ```rust struct MyExtensionData { executor_name: String, } let mut ext = MyExtensionData { executor_name: "foo".to_string(), }; let mut cx = ContextBuilder::from_waker(&waker).ext(&mut ext).build(); if let Some(ext) = cx.ext().downcast_mut::<MyExtensionData>() { println!("{}", ext.executor_name); } ``` Currently, `Context` only carries a `Waker`, but there is interest in having it carry other kinds of data. Examples include [LocalWaker](rust-lang/rust#118959), [a reactor interface](rust-lang/libs-team#347), and [multiple arbitrary values by type](https://docs.rs/context-rs/latest/context_rs/). 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. The `ext` field would provide a low friction (to stabilization) solution to enable experimentation. It would enable experimenting with what kinds of data we want to carry as well as with what data structures we may want to use to carry such data. Dedicated fields for specific kinds of data could still be added directly on `Context` when we have sufficient experience or understanding about the problem they are solving, such as with `LocalWaker`. The `ext` field would be for data for which we don't have such experience or understanding, and that could be graduated to dedicated fields once proven. Both the provider and consumer of the extension data must be aware of the concrete type behind the `Any`. This means it is not possible for the field to carry an abstract interface. However, the field can carry a concrete type which in turn carries an interface. There are different ways one can imagine an interface-carrying concrete type to work, hence the benefit of being able to experiment with such data structures. ## Passing interfaces Interfaces can be placed in a concrete type, such as a struct, and then that type can be casted to `Any`. However, one gotcha is `Any` cannot contain non-static references. This means one cannot simply do: ```rust struct Extensions<'a> { interface1: &'a mut dyn Trait1, interface2: &'a mut dyn Trait2, } let mut ext = Extensions { interface1: &mut impl1, interface2: &mut impl2, }; let ext: &mut dyn Any = &mut ext; ``` To work around this without boxing, unsafe code can be used to create a safe projection using accessors. For example: ```rust pub struct Extensions { interface1: *mut dyn Trait1, interface2: *mut dyn Trait2, } impl Extensions { pub fn new<'a>( interface1: &'a mut (dyn Trait1 + 'static), interface2: &'a mut (dyn Trait2 + 'static), scratch: &'a mut MaybeUninit<Self>, ) -> &'a mut Self { scratch.write(Self { interface1, interface2, }) } pub fn interface1(&mut self) -> &mut dyn Trait1 { unsafe { self.interface1.as_mut().unwrap() } } pub fn interface2(&mut self) -> &mut dyn Trait2 { unsafe { self.interface2.as_mut().unwrap() } } } let mut scratch = MaybeUninit::uninit(); let ext: &mut Extensions = Extensions::new(&mut impl1, &mut impl2, &mut scratch); // ext can now be casted to `&mut dyn Any` and back, and used safely let ext: &mut dyn Any = ext; ``` ## Context inheritance Sometimes when futures poll other futures they want to provide their own `Waker` which requires creating their own `Context`. Unfortunately, polling sub-futures with a fresh `Context` means any properties on the original `Context` won't get propagated along to the sub-futures. To help with this, some additional methods are added to `ContextBuilder`. Here's how to derive a new `Context` from another, overriding only the `Waker`: ```rust let mut cx = ContextBuilder::from(parent_cx).waker(&new_waker).build(); ```

raftario · 2024-09-09T21:24:11Z

It would be nice to start work towards stabilisation for this feature as it currently exists (an opt-in performance optimisation) and move the discussion about optional wakers to its own issue.

tvallotton added C-tracking-issue Category: A tracking issue for an RFC or an unstable feature. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. labels Dec 15, 2023

tvallotton mentioned this issue Dec 15, 2023

Add LocalWaker and ContextBuilder types to core, and LocalWake trait to alloc. #118960

Merged

Thomasdezeeuw mentioned this issue Dec 15, 2023

Add LocalWaker support rust-lang/libs-team#191

Open

bors pushed a commit to rust-lang-ci/rust that referenced this issue Feb 18, 2024

Rollup merge of rust-lang#118960 - tvallotton:local_waker, r=Mark-Sim…

0816d49

…ulacrum Add LocalWaker and ContextBuilder types to core, and LocalWake trait to alloc. Implementation for rust-lang#118959.

jkarneges mentioned this issue Mar 29, 2024

Add Context::ext #123203

Merged

traviscross added the WG-async Working group: Async & await label Apr 8, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tracking Issue for LocalWaker #118959

Tracking Issue for LocalWaker #118959

tvallotton commented Dec 15, 2023 •

edited

Loading

tvallotton commented Feb 12, 2024 •

edited

Loading

Thomasdezeeuw commented Feb 12, 2024

tvallotton commented Feb 12, 2024

Thomasdezeeuw commented Feb 12, 2024

raftario commented Sep 9, 2024

Tracking Issue for LocalWaker #118959

Tracking Issue for LocalWaker #118959

Comments

tvallotton commented Dec 15, 2023 • edited Loading

Public API

Steps / History

Unresolved Questions

Relevant links

Footnotes

tvallotton commented Feb 12, 2024 • edited Loading

Thomasdezeeuw commented Feb 12, 2024

tvallotton commented Feb 12, 2024

Thomasdezeeuw commented Feb 12, 2024

raftario commented Sep 9, 2024

tvallotton commented Dec 15, 2023 •

edited

Loading

tvallotton commented Feb 12, 2024 •

edited

Loading