[html5] "internal slot"

[Domenic Denicola]

From: Help [mailto:help-bounces at lists.whatwg.org] On Behalf Of Gomer Thomas

> Is that correct?

This isn't quite correct. You may benefit from reading some introductory material on JS, e.g. http://exploringjs.com/es6/ch_classes.html should help.

One thing relevant to what you were talking about is the fact that internal slots are per-instance. They do not participate in any inheritance hierarchy, but instead are installed by constructors. So if you do

class X extends ReadableStream {
  constructor() {
    // purposefully empty
  }
}

const x = new X();

then x will not have any of ReadableStream's internal slots. Whereas if you replace `// purposefully empty` with `super()`, the super-constructor call will install the internal slots on the instance, so `x` will have them.

>        In the Streams specification, I am particularly interested in the
> ReadableStream class. As I understand it, Section 3.2.1 (Class Definition) only
> provides a skeleton of the Class definition, and the rest of the definition is
> contained in the remaining sub-sections of section 3.2.

Yes, that section is non-normative. It is meant to give you an understanding of what the public API surface is, and does not say anything about how the class works. That is left for the normative specification algorithms.

>        I'm still pretty fuzzy about the "underlyingSource" object used in the
> constructor. As far as I can tell, it must implement the methods
> "start(controller)", "pull(controller)", "cancel(reason)", and it must have the
> properties "type" and "autoAllocateChunkSize". It is not at all clear what calls
> the "start(controller)" and "pull(controller)" methods, and where the
> "controller" argument comes from.

This is detailed extensively in the specification. I'm interested to know how we can we make it clearer for readers like yourself; suggestions appreciated.

> Are these supposed to be called by the
> JavaScript code that created the ReadableStream object, or are they
> supposed to be called by the ReadableStream object itself, or what?

The latter.

> Does
> the "controller" argument come implicitly from the object in the
> [[readableStreamController]] slot? As far as I can tell, this must be a
> ReadableByteStreamController or a ReadableStreamDefaultController.

The controller object is constructed by the ReadableStream constructor (as the spec for the constructor details). This is explained in the non-normative note at the top of the constructor:

> If the underlyingSource object contains a property type set to "bytes", this readable stream is a readable byte stream, and can successfully vend BYOB readers. In that case, the passed controller object will be an instance of ReadableByteStreamController. Otherwise, it will be an instance of ReadableStreamDefaultController.

You may enjoy https://blog.domenic.me/the-revealing-constructor-pattern/, which explains this pattern in general.

> The
> Class definitions of these seem very vague. Is it true that these objects must
> be implemented on an application-by-application basis, in order to provide
> the desired functionality for the underlying source stream in the specific
> application scenario?

If you are creating your own custom readable streams, then you indeed supply their own custom underlying source objects to give them desired behavior. Readable streams, like promises, are just containers for data; without the underlying source code to fill them up with data, they can't exist.

If you are receiving readable streams from another source, such as the Fetch API, then you are not creating the stream, so you don't need to supply the data or behavior, so you don't need to supply an underlying source. You can see an example at https://fetch.spec.whatwg.org/#fetch-api (last code snippet), where the `res.body` stream is given to you by the fetch API, and then you use the public API (mainly .getReader(), and reader.read()) to consume it.

Creating your own readable streams is generally done when you want to use a streaming interface to automatically handle concerns like buffering and backpressure. For example, see https://streams.spec.whatwg.org/#creating-examples. This would generally be done by library authors, whereas most application developers would simply use streams that were given to them, either by the platform (a la fetch) or by library authors.

> 
>        Regards, Gomer Thomas
> 
>               --
>               Gomer Thomas Consulting, LLC
>               9810 132nd St NE
>               Arlington, WA 98223
>               Cell: 425-309-9933
> 
> 
>               -----Original Message-----
>        From: Help [mailto:help-bounces at lists.whatwg.org] On Behalf Of Gomer
> Thomas
>        Sent: Monday, April 11, 2016 9:30 PM
>        To: 'Domenic Denicola' <d at domenic.me>; help at lists.whatwg.org
>        Subject: Re: [html5] "internal slot"
> 
>                      Thanks for the response.
>                       I found the statement "We use the notation x@[[y]] to refer to
> internal slots of an object", but I could not find a definition of what an
> "internal slot" is. What am I missing?
>                      Regards, Gomer Thomas
>                      --
>                      Gomer Thomas Consulting, LLC
>                      9810 132nd St NE
>                      Arlington, WA 98223
>                      Cell: 425-309-9933
> 
>                      -----Original Message-----
>               From: Domenic Denicola [mailto:d at domenic.me]
>               Sent: Monday, April 11, 2016 3:25 PM
>               To: Gomer Thomas <gomer at gomert-consulting.com>;
> help at lists.whatwg.org
>               Subject: RE: [html5] "internal slot"
> 
>                      It is defined in
> https://streams.spec.whatwg.org/#conventions.
> 
> 
>               _______________________________________________
>               whatwg at whatwg.org
>               https://whatwg.org/mailing-list#specs
> 
> _______________________________________________
> whatwg at whatwg.org
> https://whatwg.org/mailing-list#specs