Add core::future::{pending,ready}
Adds two future constructors to `core`: `future::ready` and `future::pending`. These functions enable constructing futures of any type that either immediately resolve, or never resolve which is an incredible useful tool when writing documentation.
These functions have prior art in both the `futures` and `async-std` crates. This implementation has been adapted from the `futures` crate.
## Examples
In https://github.com/rust-lang/rust/pull/70817 we propose adding the `ready!` macro. In the example we use an `async fn` which does not return a future that implements `Unpin`, which leads to the use of `unsafe`. Instead had we had `future::ready` available, we could've written the same example without using `unsafe`:
```rust
use core::task::{Context, Poll};
use core::future::{self, Future};
use core::pin::Pin;
pub fn do_poll(cx: &mut Context<'_>) -> Poll<()> {
let mut fut = future::ready(42_u8);
let num = ready!(Pin::new(fut).poll(cx));
// ... use num
Poll::Ready(())
}
```
## Why future::ready?
Arguably `future::ready` and `async {}` can be considered equivalent. The main differences are that `future::ready` returns a future that implements `Unpin`, and the returned future is a concrete type. This is useful for traits that require a future as an associated type that can sometimes be a no-op ([example](https://docs.rs/http-service/0.4.0/http_service/trait.HttpService.html#associatedtype.ConnectionFuture)).
The final, minor argument is that `future::ready` and `future::pending` form a counterpart to the enum members of `Poll`: `Ready` and `Pending`. These functions form a conceptual bridge between `Poll` and `Future`, and can be used as a useful teaching device.
## References
- [`futures::future::ready`](https://docs.rs/futures/0.3.4/futures/future/fn.ready.html)
- [`futures::future::pending`](https://docs.rs/futures/0.3.4/futures/future/fn.pending.html)
- [`async_std::future::pending`](https://docs.rs/async-std/1.5.0/async_std/future/fn.pending.html)
- [`async_std::future::ready`](https://docs.rs/async-std/1.5.0/async_std/future/fn.ready.html)
Add const examples
I only added them to `std::f32` to get feedback on this approach before adding the other constants.
When looking at https://github.com/rust-lang/rust/pull/68952, I found the docs a little confusing. Unless you're intimately aware of what's going on here, I don't think it's super clear what is deprecated and what you're supposed to do instead. I think short examples really clarify what's meant here, so that's what I did.
Add `RefCell::take`
Add `RefCell::take` to match `Cell` and `Option`.
I also changed a couple of calls to `.replace` to `.take`.
Tracking issue is #71395.
This is my first contribution, please tell me if there's anything I could improve, thanks!
Rename Unique::empty() -> Unique::dangling()
A `FIXME` comment in `src/libcore/ptr/unique.rs` suggested refactoring `Unique::empty()` to `Unique::dangling()` which this PR does.
Add clarification on std::cfg macro docs v. #[cfg] attribute
The wording was discussed, to a limited degree in #71679. This tries to
address some confusion I as well as someone else had independently when
looking at this macro.
Fixes#71679
The wording was discussed, to a limited degree in #71679. This tries to
address some confusion I as well as someone else had independently when
looking at this macro.
Fixes#71679
Document unsafety in core::ptr
Contributes to #66219
I have yet to document all the `unsafe` blocks in the lib and would like to know if I'm headed in the right direction
r? @steveklabnik
Add documentation example to slice_from_raw_parts_mut()
Add SAFETY explanations to some unsafe blocks in libcore/ptr
* libcore/ptr/mod.rs
* libcore/ptr/unique.rs
* libcore/ptr/non_null.rs
safety-mod.rs: Add SAFETY to slice_from_raw_parts(),
slice_from_raw_parts_mut()
slice_from_raw_parts_mut: Add documentation example
safety-ptr-unique.rs: Add SAFETY to new() and cast()
safety-ptr-non_null.rs: Add SAFETY to new()
safety-ptr-non_null.rs: Add SAFETY to cast()
safety-ptr-non_null.rs: Add SAFETY to from() impls
safety-ptr-unique.rs: Add SAFETY to from() impls
safety-ptr-non_null.rs: Add SAFETY to new()
safety-ptr-unique.rs: Add SAFETY to new()
safety-ptr-mod.rs: Fix safety explanation
https://github.com/rust-lang/rust/pull/71507#discussion_r414488884
safety-prt-non_null.rs: Fix SAFETY comment syntax
safety-ptr-unique.rs: Fix syntax for empty()
safety-ptr-non_null.rs: Fix misuse of non-null for align_of()
safety-ptr-non_null.rs: Remove incorrect SAFETY comment
safety-ptr-unique.rs: Remove unsound SAFETY comment
safety-ptr-mod.rs: Add std comment on slice_from_raw_parts guarantee
safety-ptr-unique.rs: Remove incorrect safety comment
Creating a Unique from a NonNull has strict guarantees that the current
implementation does not guarantee
https://github.com/rust-lang/rust/pull/71507#discussion_r415035952
safety-ptr: Re-adding ignore-tidy directive
Rollup of 7 pull requests
Successful merges:
- #69041 (proc_macro: Stabilize `Span::resolved_at` and `Span::located_at`)
- #69813 (Implement BitOr and BitOrAssign for the NonZero integer types)
- #70712 (stabilize BTreeMap::remove_entry)
- #71168 (Deprecate `{Box,Rc,Arc}::into_raw_non_null`)
- #71544 (Replace filter_map().next() calls with find_map())
- #71545 (Fix comment in docstring example for Error::kind)
- #71548 (Add missing Send and Sync impls for linked list Cursor and CursorMut.)
Failed merges:
r? @ghost
Implement BitOr and BitOrAssign for the NonZero integer types
This provides overloaded operators for `NonZero$Int | NonZero$Int`, `NonZero$Int | $Int`, and `$Int | NonZero$Int`. It also provides `BitOrAssign` where `self` is `NonZero$Int`, for symmetry.
It's a pretty small conceptual addition, but is good becasue but avoids a case where the operation is obviously sound, but you'd otherwise need unsafe to do it.
In crates trying to minimize `unsafe` usage, this is unfortunate and makes working with `NonZero` types often not worth it, even if the operations you're doing are clearly sound.
I've marked these as stable as I've been told in the past that trait impls are automatically stable. I'm happy to change it to unstable if this wasn't correct information.
I'm not entirely confident what version I should have put down, so I followed https://www.whatrustisit.com. Hopefully it's correct for this.
Apologies in advance if this has come up before, but I couldn't find it.
Document unsafety in core::{panicking, alloc::layout, hint, iter::adapters::zip}
Helps with #66219.
r? @Mark-Simulacrum do you want to continue reading safety comments? :D
Stabilize UNICODE_VERSION (feature unicode_version)
Tracking issue: #49726
r? @sfackler
#71020 changed the definition of `UNICODE_VERSION` just yesterday from a struct to a tuple. Maybe you want to wait some more before stabilizing this constant, on the other hand this is a very small and simple addition.
CC @behnam @SimonSapin @Serentty
Document unsafety in core::{option, hash}
Helps with #66219.
I think that the part that will need reviewing the most is the `hash/sip.rs` file.
r? @LukasKalbertodt (or someone else from the libs team)
Changed raw pointer name from ptr to raw_pointer to avoid confusion with
the `use std::ptr` statement a few lines above. This way the crate name
and pointer name are well differenciated.
Fix doc links
This fixes a few doc links which were causing `cargo doc` to fail when using `--document-private-items --document-hidden-items` on libstd. Most of the fixes are just escaping '[' and ']' characters in doc comments, and one change actually fixes a doc link.
Only use read_unaligned in transmute_copy if necessary
I've noticed that this causes LLVM to generate poor code on targets that don't support unaligned memory accesses.
