Minor cleanups and clarifications #303
Conversation
Add reserved prefixes for regular expressions and explain that such prefixes are required to be present. Expand on explanation of refresh cache behavior and required keys. Add new compressed byte object data type. Signed-off-by: Ralph Castain <rhc@pmix.org>
Chap_API_Server.tex
Outdated
| \item \emph{compress} - a compressed format based on the zlib compression package | ||
| \end{itemize} | ||
|
|
||
| Note that the regular expression itself is not required to be a printable string nor to obey typical string constraints (e.g., include a \code{NULL} terminator byte). |
There was a problem hiding this comment.
We need to update the "Advice to PMIx server hosts" in both the PMIx_generate_regex and PMIx_generate_ppn functions (16.2.1 and 16.2.2). That advice is where we introduce the colon delimiter with either the pmix:\0 prefix or the blob:\0 prefix. Note that we added the :\0 (with the NUL character) so that if the user tired to print it they wouldn't accidentally be printing an unterminated string. I think that it would be good to preserve that.
From this addition it seems like native: == pmix: and compress: == blob:. Why do we need the name change?
I think this text should be moved to PMIx_generate_regex (with a reference to it in PMIx_generate_ppn) as normal text since it is putting a requirement on those two functions. Then trim up the Advice blocks since some of that is normative text now.
In this particular section, it would be good to keep a sentence or two about the regex nature of the returned "string" specifically indicating that the return value is not necessarily printable (maybe keep your last sentence here).
There was a problem hiding this comment.
Sigh - just shows you shouldn't try to write documents when half asleep and multi-tasking on a telecon 😄 I just knew I had written the prefix stuff up somewhere, but couldn't find it!
I'll do as suggested and push the change a little later - after I have completely woken up this time!
There was a problem hiding this comment.
@jjhursey Okay, see what you think now!
Per the provided comments Signed-off-by: Ralph Castain <rhc@pmix.org>
Looks good to me. Signed-off-by: Ralph Castain <rhc@pmix.org> Co-authored-by: Josh Hursey <4259120+jjhursey@users.noreply.github.com>
Signed-off-by: Ralph Castain <rhc@pmix.org> Co-authored-by: Josh Hursey <4259120+jjhursey@users.noreply.github.com>
Add reserved prefixes for regular expressions and explain that such
prefixes are required to be present. Expand on explanation of refresh
cache behavior and required keys. Add new compressed byte object data
type.
Signed-off-by: Ralph Castain rhc@pmix.org