Context usage of MPI_Win_allocate for using MPI_Win_free and not MPI_Free_mem

[zerothi]

ompi/ompi/mpi/man/man3/MPI_Win_allocate.3in

Line 93 in a541ab9

For supported info keys see \fBMPI_Win_create\fI.

While the standard mentions how MPI_Win_allocate and MPI_Free_mem should be used together, it isn't mentioned here in the documentation.

This is a reminder to myself to create a PR for this.

I.e. something like this should be amended:

Notes
--------
....

The `baseptr` allocated in MPI_Win_allocate will be freed upon calling MPI_Win_free.

also, under See also I would add a link to MPI_Win_free.

This same edit should go in for MPI_Win_allocate_shared.

Also add this to MPI_Win_free to clarify what it does in the MPI_Win_allocate* cases.

Feel free to add suggestions before I make a pr against this.

[zerothi]

In this regard, would it make sense to amend documentation for MPI_Win_fence with descriptions of MPI_MODE_NOPUT and friends?

[jsquyres]

Yes, that would be great.

In the "FYI" category...

Know that we are in the middle of a man page and documentation revamp. In the best of worlds, it will be ready in time for v5.0.0 (but there's a possibility that it may be after the initial v5.0.0 release). This documentation / man page revamp will not be applied to versions prior to v5.0.0.

The short version is that it looks very promising that we'll be converting our man pages from native nroff to Restructured Text, which will hopefully make the upkeep of their content easier.

We're unfortunately not far enough along yet to ask you to post a PR against the new RST. ☹️ However, if you post a PR against the existing nroff in the near-ish future, we'll almost certainly get those changes "for free" in the upcoming RST-ization (i.e., we'll be converting from nroff to RST). Additionally, your nroff PR will likely also apply fairly easily to the v4.1.x and v4.0.x branches.

[zerothi]

Should I branch off v4.1.0x, or v4.0.x or master then?

Could you give an estimate on the time frame? ;)

[jsquyres]

No, you can make a PR against master and PR it to v4.0.x and v4.1.x. If that's done "soon-ish", we'll pick it up in the man page revamp automatically.

The docs/man page revamp is currently proceeding on side branches right now. I don't have an ETA, other than "hopefully by 5.0.0". You can see on PR where at least a bunch of the work is (but none of the man pages yet): #8329

[zerothi]

Done, closing this issue since it is now tracked in a PR.