Rename map functions to map_generic
@mxgrey is already working on this.
Since Nov 18, 2024.
- Dominant language
- Rust
- Stars
- 72
- Forks
- 16
- PR merge metrics
- No merged PRs in 30d
Description
Any map that gets added to a workflow must be either a blocking map or an async map. This choice determines whether or not the world execution will be blocked while waiting for the mapping to finish (with some subtle advantages and disadvantages for each). This choice is expressed through map_block and map_async functions, which both funnel into a map function that is able to process either but requires the incoming map to be wrapped in an appropriate newtype.
Unfortunately the word map is often used throughout the std Rust library and many others to refer to what is effectively map_block. Because of this, users are likely to naturally mistakenly call our map function when they meant to use map_block. In many cases the compiler should be able to guide users to correct this mistake, but as workflows get very complex and the user leans heavily on type inference, it's possible for them to receive a very misleading error from the compiler which masks the real problem and makes them think there's an error somewhere else in their code.
To fix this, I think we should rename all uses of map to map_generic to make its role more clear. Having a longer name and containing the word generic should discourage users from reaching for this function unless they really know what they're doing.
We could also consider renaming map_block to map, but this would make it less explicit to the user that map_block will be blocking the entire world update loop until it's finished, which might influence them to inappropriately use it for long-running functions, not realizing the extent of its blockiness.
We can start on this now by deprecating map and introducing map_generic, but we cannot remove map entirely until it's time for the next major release.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.