ParallelSlice chunk index
- Dominant language
- Rust
- Stars
- 48.2k
- Forks
- 4.8k
- Avg merge
- 3d 22h
- Merged PRs (30d)
- 161
Description
The docs for [ParallelSlice](https://docs.rs/bevy/latest/bevy/tasks/trait.ParallelSlice.html) give the following explanation of the parameters passed to the closure:
> The iteration function takes the index of the chunk in the original slice as the first argument, and the chunk as the second argument.
This was quite misleading for me, as I wanted to calculate the original index based on this index and the index within the chunk. The docs suggest that it is actually the start index of the chunk within the original slice, while it is actually the index of the chunk iterator itself.
As the example code itself does not use the index parameter, this gives no clarity either.
Now, it's possible to just adjust the docs so it correctly reflects the parameter, but in my case it would be handy to have the start_index of the chunk itself. As par_splat_map calculates the chunk size automagically, I had to calculate the chunk size myself based on that calculation. If that calculation ever changes, my code breaks if I don't use par_chunk_map.
The size of the chunk itself is not reliable either, as the last chunk can be smaller.
So I think there are a couple of options:
- (non-breaking) Adjust the docs so it correctly reflects what the index parameter means. Possibly improve the example code to use the index parameter as well.
For my application this would mean calculating the chunk size myself and be unable to reliably use par_splat_map, so I'd have to use par_chunk_map
- (breaking) Add a chunk_start_index parameter to the closure parameters, calculated as chunk_index * chunk_size
- (breaking) Add a chunk_size parameter to the closure parameters, so the chunk_start_index can be calculated inside of the closure
If consensus is reached, I'm happy to open a PR with the necessary changes 👍
Contributor guide
Research direction
Start by reading the ParallelSlice documentation and comparing the documented closure index with the behavior of par_splat_map and par_chunk_map. Resolve whether the intended outcome is a documentation and example correction or an API change exposing chunk information. Done means the chosen behavior is agreed on and the documentation accurately explains the parameter and its limitations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100