[webrtc-pc] Improve description for semantics of updating bufferedAmount

soareschen has just created a new issue for https://github.com/w3c/webrtc-pc:

== Improve description for semantics of updating bufferedAmount ==
I was writing test for `bufferedAmount` at w3c/web-platform-tests#6215, got confused by the description, and found #1111.

>From @taylor-b's comment:
> Meaning that within an individual task execution, the value of bufferedAmount doesn't change, unless send() is called, causing it to increase.
> Here's one idea for what to say: "Unless otherwise stated, all readonly attributes must behave as though they return the value of an internal slot, which is only updated inside a queued microtask."

The understanding is that when calling `send()`, `bufferedAmount` can only be increased within step 3. Any act of decreasing `bufferedAmount` after data is sent through underlying data transport must be done in separate microtask after returning to the event loop.

I think the description for `bufferedAmount` can be improved to better describe the semantics of updating the attribute. 

Step 5 of `send()` says _"Attempt to send data on channel's underlying data transport"_. At first glance this seems to suggest that in theory the underlying data transport could synchronously send the data and then decrease `bufferedAmount` before returning from `send()`. Perhaps if we queue that as a task then the ambiguity could be clarified.

For quick reference, here is the current description for `bufferedAmount`:

> bufferedAmount of type unsigned long, readonly
> The bufferedAmount attribute must return the number of bytes of application data (UTF-8 text and binary data) that have been queued using send() but that, as of the last time the event loop started executing a task, had not yet been transmitted to the network. (This thus includes any text sent during the execution of the current task, regardless of whether the user agent is able to transmit text asynchronously with script execution.) This does not include framing overhead incurred by the protocol, or buffering done by the operating system or network hardware. If the channel is closed, this attribute's value will only increase with each call to the send() method (the attribute does not reset to zero once the channel closes).

Please view or discuss this issue at https://github.com/w3c/webrtc-pc/issues/1376 using your GitHub account

Received on Tuesday, 13 June 2017 03:09:04 UTC