bevyengine / bevyengine/bevy

ParallelSlice chunk index

Open
#24,363 0 comments 0 reactions 0 assignees View on GitHub
A-Tasks C-Docs S-Needs-Design
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.