Re: Draft algorithms specification

Francois, thank you for the detailed feedback.  Responses inline, and I
will craft a PR with some edits shortly.

On Tue, Jan 6, 2015 at 6:34 AM, Francois Daoust <fd@w3.org> wrote:

> Hi Mark,
>
> On 2014-12-31 00:04, mark a. foltz wrote:
>
>> Anssi, Dominik, et al,
>>
>> I have created a first draft of the algorithms [1] to specify the
>> behavior of the Presentation API as defined by the current draft of the
>> specification [2].
>>
>> I believe the behavior is consistent with the current state of
>> discussion on the mailing list; however, I have annotated the PR with
>> several open issues that may deserve further discussion.  If the editors
>> and WG members agree with the direction and content of this PR I am
>> happy to iterate on it further.
>>
>
> That's a very good step forward!
>
> Here are a few comments:
>
>
> 7.1 Screen Availability Listener Added
> -----
> I may be reading "searching" the wrong way. I understand it means that the
> search is performed only once, whereas I would rather expect the user agent
> to "monitor" available screens periodically. Or is that intended?
>

Yes "monitor" or "discover" would be a bettter term.  The spec should
require a continuous process to find the current set available screens
while there are registered listeners.


>
> If so, following the current algorithm, a dumb implementation would only
> search for available screens when event handlers are added to
> NavigatorPresentation.onavailablechange. On such a dumb implementation, a
> page that would like to detect whether a second screen becomes available
> after the page has loaded would have to remove then add event handlers
> periodically to trigger a new search. That seems a bad idea. I would rather
> remove the possibility to have dumb implementations in the first place.
>


>
> Said differently, I would replace the current steps with:
>
> [[
> Let availableScreens be the list of available screens that are compatible
> with the Presentation API and that are currently known to the user agent.
>
> 1. If the user agent is not already monitoring the availability of screens
> that are compatible with the Presentation API, then:
>     1. Queue a task to monitor the availability of screens that are
> compatible with the Presentation API.
> 2. If the availableScreens list is not empty, then:
>     1. Queue a task to fire an event named availablechange at E (and only
> E) with the event's available property set to true.
> ]]
>

That looks fine.


>
> ... And I would replace "7.3 No Screens Available" section by a new one
> called "Monitor the availability of screens", along the lines of:
>
> [[
> When requested to monitor the availability of screens that are compatible
> with the Presentation API, the user agent must repeat the following steps
> periodically (say, once every few seconds) while there are event handlers
> added to NavigatorPresentation.onavailablechange:
>
> 1. Queue a task to search for screens compatible with the Presentation API
> 2. Wait for the completion of that task
> 3. Let newScreens be the list of available screens found during the search
> 4. If availableScreens is empty and newScreens is not empty, then:
>    1. Queue a task to fire an event named availablechange at all the event
> handlers added to NavigatorPresentation.onavailablechange with the
> event's available property set to true.
> 5. If availableScreens is non empty and newScreens is empty, then:
>    1. Queue a task to fire an event named availablechange at all the event
> handlers added to NavigatorPresentation.onavailablechange with the
> event's available property set to false.
> 6. Set newScreens to availableScreens.
> ]]
>

Sounds good, although I would slightly alter the text to not require
periodical searches since that may vary depending on the implementation of
discovery.  The important detail is to run the algorithm above when the set
of available screens may have changed for any reason, via periodic scan or
passive discovery.


>
> ... along with the current note that the mechanism used to search for
> compatible screens is up to the user agent and that user agents may run the
> monitoring even when there are no event handlers added to
> NavigatorPresentation.onavailablechange.
>
>
> 7.4 Start Session
> -----
> If the Web app did not use "onavailablechange", the user agent may not
> have searched for available screens yet. I would clarify that possibility
> by replacing step 3 with something along the lines of:
>
> [[
> 3. If the user agent is not monitoring screens that are compatible with
> the Presentation API, then:
>     1. Queue a task to search for screens that are compatible with the
> Presentation API
>     2. Wait until that task is completed
> 4. If last search for screens that are compatible with the Presentation
> API returned an empty list, then:
>     1. Reject P with a "NoScreensAvailable" exception
>     2. Abort all remaining steps
> ]]
>

That seems reasonable to do.  It would capture the case where the page
believes there is an available screen (based on a past availablechange
event) and the user agent has stopped monitoring, before the page invokes
startSession.


>
> 7.5 Join Session
> -----
> The current algorithm returns the first matching presentation. If a Web
> page created two presentation sessions with the same URL and presentation
> ID for two different second screens, how can it resume the second one?
>

As the algorithm defined the user agent should only allow the page to join
one of the two presentations; the prose part of the spec reads:

    <p>
      If the browser knows of multiple matching sessions, it should connect
the
      page to the session that was most recently connected to; if that
cannot
      be determined by the browser (for example, if the matching sessions
have
      never been connected), then the <code>Promise</code> should remain
      unresolved.
    </p>

To implement that, we need to keep track of the last connected time for
each presentation and update the algorithm accordingly.

Instead, if we would like to allow resumption of multiple sessions that
share a URL+ID, then several changes would be required:
 - The user agent would need to assign an internal unique identifier to
each presentation (or to each screen) so it could track them using
something other than URL+ID.
 - joinSession() would resolve to an array of PresentationSessions in case
there were multiple matches.


>
>
> 7.6 Session Close
> -----
> What is the purpose of step 4? Why is it not enough to "queue a task to
> fire an event named statechange at S.onstatechange" given that S is known
> right from the start?
>

That was a long winded attempt to ensure that all pages connected to a
session get the event.  I agree this should be simplified and explained
that events fired on a PresentationSession are sent to all pages that
currently hold a reference to it.


>
> Also, in the event where a page created two presentation sessions with the
> same URL and presentation ID for two different second screens, calling
> "close" on the first presentation session would trigger a "statechange"
> event on the second one as well, which seems wrong.
>

If we allow multiple sessions that share a URL+ID to coexist in the user
agent (by being presented to multiple screens) we will need a way to
distinguish these sessions; adding a screen identifier to the session (at
least, for internal tracking) seems like the simplest approach.

7.7 Presentation Connection
> -----
> Same remark as above for step 3.3.


Similar response; will add the screen ID to the spec and that should
resolve the ambiguity.


>
>
>> I am newly acquainted with the indented-list style of pseudocode used by
>> the W3C so if anything is unclear please provide feedback here, or in
>> conversation on the PR.
>>
>
> Note the style used for pseudo-code is not in any way mandatory within
> W3C. The group may use whatever style it wants, so feel free to propose
> alternatives! That said, it is true that the indented-list style has become
> the norm to define algorithms.
>

Thanks :)  I suggest sticking with it unless it becomes cumbersome and
unsuitable for our purpose.


>
> Thanks,
> Francois.
>
>
>
>
>
>  I had some difficulty using the current Makefile to generate cross
>> references.  It seems like the content of the xrefs repo in the CG was
>> not fully ported to the w3c repo - anolis gives an error when trying to
>> process cross references.  Perhaps that can be fixed separately and I
>> can rebase my changes so I don't include a hacked up Makefile in my PR.
>>
>> Cheers and Happy Holidays,
>> Mark
>>
>> [1] https://github.com/w3c/presentation-api/pull/37
>> [2] http://w3c.github.io/presentation-api/
>>
>>