Administrative MTypes

[Mark Taylor]

On Tue, 3 Jun 2008, Mike Fitzpatrick wrote:

> Hi Guys,
>
>        The 'hub.event.stopping' was derived from the PLASTIC message
> of a similar name but I really think it could be just 'hub.event.shutdown'
> to be more explicit.  This would avoid confusion with the
> app.{starting,stopping} but I also agree that at least those two are
> application specific things that belong in the second doc.

agreed - I'll use shutdown rather than stopping for the hub event
and leave the app stopping/starting messages out of the SAMP doc.

>        That said, I'd still like to have an 'app' class of messages
> since not every administrative message will be coming from the hub.
> My sense is that app.echo and app.isAlive really mean the same thing
> and could be just 'app.ping' or somesuch (after all, if an app isn't
> alive it would never respond, but then neither would any other message).

echo and isAlive do do pretty similar things, the difference is that
echo has a parameter and matching return value.  My current draft reads:

    samp.app.isAlive:
       Arguments:
          none
       Return Values:
          none
       Description:
          Diagnostic used to indicate whether an application is currently
          responding. No “status”-like return values is defined, since in general
          any response will indicate aliveness, and the normal samp.status
          key in the response may be used to indicate any abnormal state.

    samp.app.echo:
       Arguments:
          text (string) — arbitrary text to echo
       Return Values:
          text (string) — the same value as the text parameter
       Description:
          Slightly more interesting diagnostic message to determine whether
          client is responding. The input string is simply copied to the
          output.

Thus echo allows you to tell whether the recipient is actually 
understanding the message rather than just consuming it.
Is this a worthwhile distinction?   Not sure.  I'm happy to replace
these two by a single ping MType (which does or does not have an
echoed argument?) if people think that's better.

>        Lastly, did we settle the question of whether users can extend
> the hub/app toplevel classes or are we saying e.g. that any app.* message
> is reserved for the spec?  Can anyone imagine a use-case where they
> implement a hub and want to define their own hub.* mtype for some
> particular reason?

In one of your slides you raised the question of whether to use
the samp. namespace for the admin messages.  I suggest yes - thus we
have

    samp.hub.event.shutdown
      ...
    samp.app.ping
      ...

etc.  Then people are allowed to come up with custom hub.* or app.* 
messages - if they look sufficiently useful they can be moved into
the samp. namespace in later versions of the document.  This matches
the way that the samp. namespace is used for other extensible 
vocabularies in the document.

Mark

-- 
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-928-8776 http://www.star.bris.ac.uk/~mbt/