Skip to content

Commit

Permalink
Rollup merge of rust-lang#70752 - yoshuawuyts:slice_fill, r=dtolnay
Browse files Browse the repository at this point in the history
Add slice::fill

Adds the `slice::fill` method to fill a slice with an item. This replaces manual for loops where items are copied one-by-one. This is a counterpart to C++20's [`std::fill`](https://en.cppreference.com/w/cpp/algorithm/fill) function.

## Usage

```rust
let mut buf = vec![0; 10];
buf.fill(1);
assert_eq!(buf, vec![1; 10]);
```

## Performance

When compiling in release mode, for `[u8]` and `[u16]` this method will optimize to a `memset(3)` call ([godbolt](https://godbolt.org/z/85El_c)). The initial implementation relies on LLVM's optimizer to make it as fast as possible for any given input. But as @jonas-schievink [pointed out](https://twitter.com/sheevink/status/1245756597453885442) this can later be optimized through specialization to guarantee it has a specific performance profile.

## Why now?

Conversations about adding `slice::fill` are not new. In fact, rust-lang/rfcs#2067 was opened 3 years ago about this exact topic. However discussion stranded while discussing implementation details, and it's not seen much forward motion since.

In ["The Hunt for the Fastest Zero"](https://travisdowns.github.io/blog/2020/01/20/zero.html) Travis Downs provides disects C++'s `std::fill` performance profile on gcc, comparing it among others to `memset(3)`. Even though `memset(3)` outperforms `std::fill` in their tests, the author notes the following:

>  That the optimization fails, perhaps unexpectedly, in some cases is unfortunate but it’s nice that you can fix it yourself. [...] Do we throw out modern C++ idioms, at least where performance matters, for example by replacing std::fill with memset? I don’t think so.

Much of the article focuses on how how to fix the performance of `std::fill` by providing specializations for specific input. In Rust we don't have any dedicated methods to fill slices with values, so it either needs to be optimized at the MIR layer, or more likely rely on LLVM's optimizer.

By adding a dedicated method for filling slices with values it opens up the ability for us to in the future guarantee that e.g. `Vec<u8>` will always optimize to `memset` even in debug mode. Or perhaps provide stronger guarantees about memory when zeroing values when a certain flag is passed. But regardless of that, it improves general ergonomics of working with slices by providing a dedicated method with documentation and examples.

## References
- [slice-fill prototype on docs.rs](https://docs.rs/slice-fill/1.0.1/slice_fill/)
- [The Hunt For The Fastest Zero](https://travisdowns.github.io/blog/2020/01/20/zero.html)
- [Safe memset for slices](rust-lang/rfcs#2067)
- [C++20 std::fill](https://en.cppreference.com/w/cpp/algorithm/fill)
- [ASM output on Godbolt](https://godbolt.org/z/5-XU66)
  • Loading branch information
Dylan-DPC committed Apr 5, 2020
2 parents 630414d + edabceb commit 6ea2701
Showing 1 changed file with 24 additions and 0 deletions.
24 changes: 24 additions & 0 deletions src/libcore/slice/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
// * The `raw` and `bytes` submodules.
// * Boilerplate trait implementations.

use crate::borrow::Borrow;
use crate::cmp;
use crate::cmp::Ordering::{self, Equal, Greater, Less};
use crate::fmt;
Expand Down Expand Up @@ -2145,6 +2146,29 @@ impl<T> [T] {
}
}

/// Fills `self` with elements by cloning `value`.
///
/// # Examples
///
/// ```
/// #![feature(slice_fill)]
///
/// let mut buf = vec![0; 10];
/// buf.fill(1);
/// assert_eq!(buf, vec![1; 10]);
/// ```
#[unstable(feature = "slice_fill", issue = "70758")]
pub fn fill<V>(&mut self, value: V)
where
V: Borrow<T>,
T: Clone,
{
let value = value.borrow();
for el in self {
el.clone_from(value)
}
}

/// Copies the elements from `src` into `self`.
///
/// The length of `src` must be the same as `self`.
Expand Down

0 comments on commit 6ea2701

Please sign in to comment.