Intent to Prototype and Ship: SerialPort BYOB reader support

153 views
Skip to first unread message

Reilly Grant

unread,
Aug 8, 2022, 9:39:32 PM8/8/22
to blink-dev, Domenic Denicola

Contact emails

rei...@chromium.org


Explainer

Full explainer should not be necessary; see the Summary section below for an overview of this change


Specification

https://wicg.github.io/serial/#readable-attribute


Summary

The SerialPort interface provides a ReadableStream and WritableStream for communication with the connected device. This change updates the underlying data source for the ReadableStream to make it a readable byte stream. This is how this stream should have originally been specified but at the time Chromium did not support implementing byte streams in C++. This has recently been fixed and so this change can be implemented. The change is backwards compatible because existing code calling port.readable.getReader() will continue to work while new code can detect support for BYOB readers by calling getReader({ mode: 'byob' }) and catching the TypeError thrown by older implementations.


BYOB readers allow developers to specify the buffer into which data is read instead of the stream allocating a buffer for each chunk. In addition to the potential reduction in memory pressure this allows script to control how much data is received in a chunk as the stream cannot return more than there is space for in the provided buffer.


The ability to read a particular amount of data from a port has been a frequently requested feature by developers used to programming against the Windows and POSIX APIs for serial devices, which operate on this same "bring your own buffer" principle. The current API, in contrast, requires developers to code defensively against extra unwanted data instead of receiving only what they are ready to process.


Blink component

Blink>Serial


TAG review

https://github.com/w3ctag/design-reviews/issues/431

https://github.com/w3ctag/design-reviews/issues/567


TAG review status

Not applicable, the W3C TAG has already reviewed the Web Serial and byte stream APIs independently. This change integrates them in an obvious manner.



Risks


Interoperability and Compatibility


Gecko: Harmful (https://mozilla.github.io/standards-positions/#webserial)

Mozilla is opposed to the Web Serial API in general. This incremental change is not expected to change their position.


WebKit: Negative (https://webkit.org/tracking-prevention)

Apple is opposed to the Web Serial API in general. This incremental change is not expected to change their position.


Web developers: Positive (https://github.com/WICG/serial/issues/125#issuecomment-786937083)

Multiple developers have asked for the ability to read a specific number of bytes from the port, which is enabled by using a BYOB reader.


WebView application risks

WebView is not supported because this API is not available on Android.



Debuggability

This feature is debuggable using the normal DevTools JavaScript debugger.


Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

No, the Web Serial API is only available on desktop platforms because Android does not provide a serial API. A polyfill for Android which uses WebUSB (and can be expanded using Web Bluetooth) provides an implementation of the missing platform features. An issue has been filed to update the polyfill with BYOB reader support.


Is this feature fully tested by web-platform-tests?

Yes (in the patch)


Requires code in //chrome?

No


Tracking bug

https://bugs.chromium.org/p/chromium/issues/detail?id=1182905


Sample links

https://googlechromelabs.github.io/serial-terminal


Estimated milestones

M-106


Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/6716022686482432


This intent message was generated by Chrome Platform Status and lovingly edited by hand.

Reilly Grant | Software Engineer | rei...@chromium.org | Google Chrome

Yoav Weiss

unread,
Aug 10, 2022, 11:15:45 AM8/10/22
to blink-dev, Reilly Grant, Domenic Denicola
LGTM1

Mike Taylor

unread,
Aug 10, 2022, 11:56:15 AM8/10/22
to Yoav Weiss, blink-dev, Reilly Grant, Domenic Denicola
LGTM2
--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/4c022c60-2d3e-4976-883d-80cbe6639845n%40chromium.org.


Daniel Bratell

unread,
Aug 10, 2022, 12:00:14 PM8/10/22
to Mike Taylor, Yoav Weiss, blink-dev, Reilly Grant, Domenic Denicola

I have one question about what you get back with you call getReader(). You write that such code will continue to work. Does that mean that the return value is the same or does it mean that what you get back has the exact same API surface as what you got before?

/Daniel

Reilly Grant

unread,
Aug 10, 2022, 12:23:22 PM8/10/22
to Daniel Bratell, Mike Taylor, Yoav Weiss, blink-dev, Domenic Denicola
On Wed, Aug 10, 2022 at 9:00 AM Daniel Bratell <brat...@gmail.com> wrote:

I have one question about what you get back with you call getReader(). You write that such code will continue to work. Does that mean that the return value is the same or does it mean that what you get back has the exact same API surface as what you got before?

When getReader() is called without the newly supported { mode: 'byob' } argument it will continue to return the ReadableStreamDefaultReader interface. It only returns the new ReadableStreamBYOBReader interface when that argument (which prior to this change causes getReader() to throw a TypeError) is passed. So existing code can't observe a difference.

Daniel Bratell

unread,
Aug 11, 2022, 5:36:08 AM8/11/22
to Reilly Grant, Mike Taylor, Yoav Weiss, blink-dev, Domenic Denicola

LGTM3

/Daniel

Reply all
Reply to author
Forward
0 new messages