Rename map functions to map_generic

Open
  • Is something wrong?
#31 0 comments 0 reactions 1 assignee View on GitHub

@mxgrey is already working on this.

Since Nov 18, 2024.

Assessment

This issue has not been assessed yet.

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.

Dominant language
Rust
Stars
75
Forks
18
Avg merge
12d 12h
Merged PRs (30d)
3

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from open-rmf/crossflow

All issues in open-rmf/crossflow

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.