532357 - nsIAsync{In,Out}putStream docs need some clarifications

Status: NEW

(Core :: XPCOM, enhancement)

Description

[Jeff Walden [:Waldo]]

== The Effect of Waiting When a Pending Callback Hasn't Happened ==

It is unspecified what happens if asyncWait is called twice with a non-null callback with no intervening on{In,Out}putStreamReady callback.  For example, this has unspecified behavior:

  outStream.asyncWait(callback1, 0, 1, eventTarget);
  outStream.asyncWait(callback2, 0, 1, eventTarget);

Existing implementations treat the second asyncWait call as implicitly dropping |callback1| and replacing it with |callback2|, i.e. the above is in essence interpreted this way:

  outStream.asyncWait(callback1, 0, 1, eventTarget);
  outStream.asyncWait(null, 0, 1, eventTarget); // remove callback1
  outStream.asyncWait(callback2, 0, 1, eventTarget); // new callback specified

The docs should explicitly address this method of interaction.

== Are Callbacks Requiring No Delay Dispatched Normally or Synchronously? ==

"dispatched immediately" suggests that aEventTarget.dispatch(...) occurs immediately, but the description of aEventTarget suggests that the callback might occur synchronously.  Alternately, I may easily be reading it wrong; my first skim suggested the callback occurred immediately, not that the ready-event would be dispatched to be handled when that event target's loop had spun enough.  Whatever's really supposed to happen, I think the wording on this point could be clearer.

Comment 1

[Boris Zbarsky [:bzbarsky]]

> my first skim suggested the callback occurred immediately

At least for pipes, if aEventTarget is null and there is nothing to wait for, the callback will be called before asyncWait returns.