+1 on Mark's text
On 6 January 2016 at 08:12, Mark Thomas <markt_at_apache.org> wrote:
> On 05/01/2016 20:53, Shing Wai Chan wrote:
> > The #onDataAvailable method will be invoked (after the first time) when
> > the following conditions are satisfied:
> > a) #isReady() has invoked with value false
> > b) data is available, that is #isReady() = true later
>
> Referring to #isReady() == true later is confusing rather than
> clarifying the behaviour.
>
> > So, I suggest to clarify with the following change in p.3-28:
> > Old: The container will invoke the method the first time when data is
> > available to read. The container will subsequently invoke the
> > onDataAvailable method if and only if isReady method on
> > ServletInputStream, described below, returns true.
> >
> > New: servlet.book The container will invoke the method the first time
> > when data is available to read. The container will subsequently invoke
> > the onDataAvailable method if and only if isReady method on
> > ServletInputStream, described below, *has been called with returned
> > value false and data is available to read (i.e. isReady() returns true)
> > later*.
>
> I'd suggest the following wording:
>
> The container will invoke the onDataAvailable() method the first time
> data is available to read. The container will subsequently invoke the
> onDataAvailable() method if and only if the isReady() method on
> ServletInputStream, described below, has been called and returned
> a value of false and data has subsequently become available to read.
>
> > Similarly for #onWritePossible in p.5-47, we would like to change from:
> > Old: The container will subsequently invoke the onWritePossible method
> > if and only if isReady method on ServletOutputStream, described below,
> > returns true.
> >
> > New: servlet.book The container will subsequently invoke the
> > onWritePossible method if and only if isReady method on
> > ServletOutputStream, described below, *has been called with returned
> > value false and a write operation can be performed (i.e. isReady()
> > returns true) later*.
>
> And for this one:
>
> The container will subsequently invoke the onWritePossible() method if
> and only if the isReady() method on ServletOutputStream, described
> below, has been called and returned a value of false and a write
> operation has subsequently become possible.
>
> Mark
>
> >
> > I noticed that similar statements are in javadoc. We may like to update,
> > too once we finalize the change on the spec side.
> >
> > Shing Wai Chan
> >
> > On 12/9/15, 4:00 PM, Greg Wilkins wrote:
> >>
> >> On 10 December 2015 at 00:29, Martin Mulholland <mmulholl_at_us.ibm.com
> >> <mailto:mmulholl_at_us.ibm.com>> wrote:
> >>
> >> GW> Good catch!
> >>
> >> GW> This is just wrong! It is not a perspective thing. A
> >> container will
> >> GW> NEVER call onDataAvailable after the first invocation unless
> >> isReady has
> >> GW> been called AND it returned false.
> >>
> >> ED > This was done under SERVLET_SPEC-127. I have asked Shing-wai
> >> to explain
> >> ED> the rationale for that change. In the meantime, I don't
> >> understand your
> >> ED> assertion Greg. If the container calls
> >> ServletInputStream.isReady() and
> >> ED> it returns false, then it doesn't make sense for the container
> >> to call
> >> ED >ReadListener.onDataAvailable() because *data is not
> >> available*. Right?
> >> ED >Please help me understand.
> >>
> >> The way I interpreted the spec before was that only after an app
> >> calls isReady() and
> >> it returns false should the container be responsible for calling
> >> onDataAvailable again
> >> - when more data is available.
> >>
> >>
> >>
> >> That is exactly what I meant. The container will call
> >> onDataAvailable IFF isReady() has been called AND isReady() returned
> >> false AND there is data available to be read.
> >>
> >>
> >>
> >>
> >> If the app returns without having called isReady() and
> >> got false the container is not on the hook to call onDataAvailable
> >> again.
> >>
> >>
> >> this is how an application can communicate back pressure to the API.
> >> If it has read some data, but is still processing it and not ready to
> >> read any more data, then it can return without having called
> >> isReady(). In that case the container will not call onDataAvailable
> >> again and the container will not read further data and back pressure
> >> will be put over TCP or HTTP2 flow control.
> >>
> >>
> >>
> >>
> >> I have to
> >> come up with a completely different interpretation with false
> >> changed to true. I
> >> agree it makes no sense to call onDataAvailable unless isReady()
> >> will return true, but
> >> this section of the spec previously made a much more important
> >> point than that.
> >>
> >>
> >> I agree that the instant before onDataAvailable is called, a
> >> hyperthetical call to isReady() would return true. But there is no
> >> requirement (and little opportunity) for anything to call isReady()
> >> and get a true return.
> >>
> >> In fact if isReady() has been called and returned false, it would be
> >> dangerous for another thread to call isReady and proceed to do IO if
> >> it got a true return, as it would be in a race with a call to
> >> onDataAvailable.
> >>
> >> The only situation where a non-onDataAvailable dispatched thread can
> >> safely call isReady and proceed to do IO is if a prior onDataAvailable
> >> call has returned without calling isReady at all.
> >>
> >> cheers
> >>
> >>
> >>
> >> --
> >> Greg Wilkins <gregw_at_webtide.com <mailto:gregw_at_webtide.com>> CTO
> >> http://webtide.com
>
>
--
Greg Wilkins <gregw@webtide.com> CTO http://webtide.com