API Naming Conventions

[steiltre]

I want to get a thread that I can point back to with all of the ideas surrounding API naming conventions. Ultimately, these names should be consistent above all else so a user can reason about some of a function's implications (i.e. collectives, asynchronous calls, local operations) just from the name.

The current idea is:

• async prefix on all asynchronous operations. This is probably the least controversial part of any naming scheme we might come up with.
• local prefix on all calls that execute safely at any time and are not collectives.
• All other functions are assumed to be collectives (e.g. barrier(), for_all()).

The biggest complaint I have with this scheme is that some local operation names are slightly cumbersome (e.g. local_owner(), local_rank(), local_cout() would all be necessary with this scheme). It also makes collectives the "default" in some sense by not giving them prefixes. This scheme is consistent and should be relatively straightforward for new users, clearing up confusing points like size() being a collective.

An alternative would be to prefix collectives with all and forego the local prefix on local operations. This seems like a worse choice as all_size() and all_barrier() would be necessary, for_all() would have to be changed or an exception to the rule, and emphasizing that some functions are local seems important.

I'm going to treat the first naming scheme as a convention for now. Feel free to add any further ideas here.