Ch. 4->3: Clarify three roles of the interface

[jjhursey]

• Effort to clarify the three roles of consumers of the PMIx interface (clients / servers / tools)
• Goal is to use the new Chapter 3 as a splitting point to direct those focused on a specific role to those sections of the standard that are most meaningful to them.
• Part of the implementation agnostic/client separation working group effort
• Ref Issue Further separate out the PMIx client interface from the CL/host interactions #175

[jjhursey]

I think this is ready for the Working Group to start reviewing.

[jjhursey]

Here is a link to the generated PDF that I will try to keep updated with any further changes:

• https://ibm.box.com/s/tt0v2l5w4bmx893b6b6r9e72y206mp9g

[jjhursey]

Per Client Separation Working Group Meeting on June 9, 2020:

• Move the server init/finalize routines to the "Server-specific interfaces" chapter
• Move the 'new' preamble text to Chapter 1. This defines the three roles in the interface.
  • Note once PR Ch. 1: Issue 175: Separate out the PMIx client interface from the CL/host interactions  #192 is merged (next month) then I'll replace this section within the new Chapter 1 text.
• Move the general information interfaces to a new chapter out of the init/finalize chapter
• Make the init/finalize chapter a "Client-Specific Interfaces" chapter
  • For now it includes the tool init/finalize routines. But once we get the Tools chapter then we will move those interfaces to the new chapter.
• Idea is that we will have chapters dedicated to interfaces specific to each of the three roles. Then the rest of the chapters are generally consumable (more or less) by any role. it also provides a specific chapter for folks to jump to if they are only concerned with one of the three roles.

[jjhursey]

Per WG teleconf June 15, 2020

• Section 1.3.3 (new section) - General note that 'consumer' is misleading in the title, at least in the current form.
  • Change the title to (here are some options - vote with emoji)
    • 👍 "Types of PMIx API Consumers"
    • 😄 "Categories of PMIx Roles"
    • 🎉 "PMIx Roles"
    • 🚀 "PMIx API Role Groupings"
    • 👎 -- back to the drawing board - suggest in comments or in the next meeting
  • Change the first sentence to
    • "The role of a PMIx process in the PMIx universe is grouped into three categories based on how it operates in the PMIx environment namely as a client, server, or tool"
• New Chapter 3 ("General Information Interfaces) is a bit small
  • Keep it for now to see if other things fit into this category (maybe renaming the chapter)
  • Maybe PMIx_Query should move in here?
• New Chapter 4 ("Client-Specific Interfaces") is also small since there are not many interfaces exclusive to clients that cannot also be used by tools and servers.
  • That's ok for now, but seems a bit odd.
• All other chapters are generally "part of the client role" of the interface - meaning that tools and servers can also use them. Should we put a note in each chapter designating the role in which it is intended to be used?

The current version of the document for reference is attached to this comment.
pmix-standard.pdf

[jjhursey]

I updated the title and first sentence of Section 1.3.3 - attached in the current rendering.
pmix-standard.pdf

[jjhursey]

Per teleconf today - Slight adjustment to first sentence wording.
pmix-standard.pdf

[jjhursey]

We might bring in part of this PR into the PMIx v4.0 standard. We can discuss in the next monthly ASC meeting.

[jjhursey]

This PR has grown stale. It tried to do 2 things:

• Split up the initialization/finalization of client / tool / server into separate chapters. This was completed in v4.
• Define the 3 consumers of the interface. I pulled this out into PR Clarify three roles of consumers of the PMIx interface #327