Editorial: try to clarify the JS API (#212)

Ms2ger · web-flow · commit 8deee83209c2 · 2023-09-28T07:55:33.000+01:00
diff --git a/document/js-api/index.bs b/document/js-api/index.bs
@@ -150,7 +150,7 @@ urlPrefix: https://heycam.github.io/webidl/; spec: WebIDL
     type: dfn
         text: create a namespace object; url: create-a-namespace-object
 urlPrefix: https://tc39.es/proposal-resizablearraybuffer/; spec: ResizableArrayBuffer proposal
-    type: dfn
+    type: abstract-op
         text: IsFixedLengthArrayBuffer; url: sec-isfixedarraybuffer
         text: HostResizeArrayBuffer; url: sec-hostresizearraybuffer
         text: HostGrowSharedArrayBuffer; url: sec-hostgrowsharedarraybuffer
@@ -618,41 +618,51 @@ which can be simultaneously referenced by multiple {{Instance}} objects. Each
 <div algorithm>
     To <dfn>create a fixed length memory buffer</dfn> from a [=memory address=] |memaddr|, perform the following steps:
 
-    1. Let |block| be a [=Data Block=] which is [=identified with=] the underlying memory of |memaddr|.
-    1. If |block| is a [=Shared Data Block=],
+    1. Let |store| be the [=surrounding agent=]'s [=associated store=].
+    1. Let <var ignore>limits</var> |share| be [=mem_type=](|store|, |memaddr|).
+    1. If |share| is shared,
+        1. Let |block| be a [=Shared Data Block=] which is [=identified with=] the underlying memory of |memaddr|.
         1. Let |buffer| be a new {{SharedArrayBuffer}} with the internal slots \[[ArrayBufferData]] and \[[ArrayBufferByteLength]].
         1. Set |buffer|.\[[ArrayBufferData]] to |block|.
         1. Set |buffer|.\[[ArrayBufferByteLength]] to the length of |block|.
         1. Perform ! [$SetIntegrityLevel$](|buffer|, `"frozen"`).
     1. Otherwise,
+        1. Let |block| be a [=Data Block=] which is [=identified with=] the underlying memory of |memaddr|.
         1. Let |buffer| be a new {{ArrayBuffer}} with the internal slots \[[ArrayBufferData]], \[[ArrayBufferByteLength]], and \[[ArrayBufferDetachKey]].
         1. Set |buffer|.\[[ArrayBufferData]] to |block|.
         1. Set |buffer|.\[[ArrayBufferByteLength]] to the length of |block|.
         1. Set |buffer|.\[[ArrayBufferDetachKey]] to "WebAssembly.Memory".
     1. Return |buffer|.
 </div>
 
-Note: (TODO) Check whether only SharedArrayBuffers need integrity level "frozen" (see the Threads Proposal Overview).
+Issue: (TODO) Check whether only SharedArrayBuffers need integrity level "frozen" (see the Threads Proposal Overview).
 
 To create a resizable memory buffer we perform the same steps as above, but also setting the buffer's maximum size.
 
 <div algorithm>
-    To <dfn>create a resizable memory buffer</dfn> from a [=memory address=] |memaddr| and a |maxsize|, perform the following steps:
+    To <dfn>create a resizable memory buffer</dfn> from a [=memory address=] |memaddr|, perform the following steps:
 
-    1. Let |block| be a [=Data Block=] which is [=identified with=] the underlying memory of |memaddr|.
-    1. Let |length| be the length of |block|.
-    1. If |maxsize| &gt; (65536 &times; 65536),
-        1. Throw a {{RangeError}} exception.
-    1. If |block| is a [=Shared Data Block=],
+    1. Let |store| be the [=surrounding agent=]'s [=associated store=].
+    1. Let { |min|, |max| } |share| be [=mem_type=](|store|, |memaddr|).
+    1. If |max| is not empty,
+        1. If |max| &gt; (65536 &times; 65536),
+            1. Issue: Can this happen?
+            1. Throw a {{RangeError}} exception.
+        1. Let |maxsize| be |max|.
+    1. Otherwise,
+        1. Let |maxsize| be 65536 &times; 65536.
+    1. If |share| is shared,
+        1. Let |block| be a [=Shared Data Block=] which is [=identified with=] the underlying memory of |memaddr|.
         1. Let |buffer| be a new {{SharedArrayBuffer}} with the internal slots \[[ArrayBufferData]], \[[ArrayBufferByteLength]], and \[[ArrayBufferMaxByteLength]].
         1. Set |buffer|.\[[ArrayBufferData]] to |block|.
-        1. Set |buffer|.\[[ArrayBufferByteLength]] to the length of |block|.
+        1. Set |buffer|.\[[ArrayBufferByteLength]] to |min|.
         1. Set |buffer|.\[[ArrayBufferMaxByteLength]] to |maxsize|.
         1. Perform ! [$SetIntegrityLevel$](|buffer|, `"frozen"`).
     1. Otherwise,
+        1. Let |block| be a [=Data Block=] which is [=identified with=] the underlying memory of |memaddr|.
         1. Let |buffer| be a new {{ArrayBuffer}} with the internal slots \[[ArrayBufferData]], \[[ArrayBufferByteLength]], \[[ArrayBufferMaxByteLength]], and \[[ArrayBufferDetachKey]].
         1. Set |buffer|.\[[ArrayBufferData]] to |block|.
-        1. Set |buffer|.\[[ArrayBufferByteLength]] to |length|.
+        1. Set |buffer|.\[[ArrayBufferByteLength]] to |min|.
         1. Set |buffer|.\[[ArrayBufferMaxByteLength]] to |maxsize|.
         1. Set |buffer|.\[[ArrayBufferDetachKey]] to "WebAssembly.Memory".
     1. Return |buffer|.
@@ -684,9 +694,9 @@ To create a resizable memory buffer we perform the same steps as above, but also
     1. Let |initial| be |descriptor|["initial"].
     1. If |descriptor|["maximum"] [=map/exists=], let |maximum| be |descriptor|["maximum"]; otherwise, let |maximum| be empty.
     1. If |maximum| is not empty and |maximum| &lt; |initial|, throw a {{RangeError}} exception.
-    1. Let |shared| be |descriptor|["shared"].
-    1. If |shared| is true and |maximum| is empty, throw a {{TypeError}} exception.
-    1. Let |memtype| be { min |initial|, max |maximum|, shared |shared| }.
+    1. Let |share| be shared if |descriptor|["shared"] is true and unshared otherwise.
+    1. If |share| is shared and |maximum| is empty, throw a {{TypeError}} exception.
+    1. Let |memtype| be ({ min |initial|, max |maximum| }, |share|).
     1. Let |store| be the [=surrounding agent=]'s [=associated store=].
     1. Let (|store|, |memaddr|) be [=mem_alloc=](|store|, |memtype|). If allocation fails, throw a {{RangeError}} exception.
     1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
@@ -700,12 +710,13 @@ To create a resizable memory buffer we perform the same steps as above, but also
     1. Assert: |map|[|memaddr|] [=map/exists=].
     1. Let |memory| be |map|[|memaddr|].
     1. Let |buffer| be |memory|.\[[BufferObject]].
-    1. If [=IsFixedLengthArrayBuffer=](|buffer|) is true,
-        1. If |memory|.\[[BufferObject]] is an {{ArrayBuffer}},
+    1. If [$IsFixedLengthArrayBuffer$](|buffer|) is true,
+        1. If [$IsSharedArrayBuffer$](|buffer|) is false,
             1. Perform [=!=] [$DetachArrayBuffer$](|buffer|, "WebAssembly.Memory").
-        1. Let |buffer| be the result of [=create a fixed length memory buffer|creating a fixed length memory buffer=] from |memaddr|.
-        1. Set |memory|.\[[BufferObject]] to |buffer|.
+        1. Let |newBuffer| be the result of [=create a fixed length memory buffer|creating a fixed length memory buffer=] from |memaddr|.
+        1. Set |memory|.\[[BufferObject]] to |newBuffer|.
     1. Otherwise,
+        1. Issue: Is this safe for a SharedArrayBuffer?
         1. Let |block| be a [=Data Block=] which is [=identified with=] the underlying memory of |memaddr|.
         1. Set |buffer|.\[[ArrayBufferData]] to |block|.
         1. Set |buffer|.\[[ArrayBufferByteLength]] to the length of |block|.
@@ -743,8 +754,8 @@ Immediately after a WebAssembly [=memory.grow=] instruction executes, perform th
     The <dfn method for="Memory">toFixedLengthBuffer()</dfn> method, when invoked, performs the following steps:
     1. Let |buffer| be **this**.\[[BufferObject]].
     1. Let |memaddr| be **this**.\[[Memory]].
-    1. If |buffer| is an {{ArrayBuffer}},
-        1. If [=IsFixedLengthArrayBuffer=](|buffer|) is true, return |buffer|.
+    1. If [$IsSharedArrayBuffer$](|buffer|) is false,
+        1. If [$IsFixedLengthArrayBuffer$](|buffer|) is true, return |buffer|.
         1. Otherwise,
             1. Let |fixedBuffer| be the result of [=create a fixed length memory buffer|creating a fixed length memory buffer=] from |memaddr|.
             1. Perform [=!=] [$DetachArrayBuffer$](|buffer|, "WebAssembly.Memory").
@@ -762,31 +773,25 @@ Immediately after a WebAssembly [=memory.grow=] instruction executes, perform th
 <div algorithm=dom-Memory-toResizableBuffer>
     The <dfn method for="Memory">toResizableBuffer()</dfn> method, when invoked, performs the following steps:
     1. Let |buffer| be **this**.\[[BufferObject]].
-    1. If [=IsFixedLengthArrayBuffer=](|buffer|) is false, return |buffer|.
+    1. If [$IsFixedLengthArrayBuffer$](|buffer|) is false, return |buffer|.
     1. Let |memaddr| be **this**.\[[Memory]].
-    1. Let |store| be the [=surrounding agent=]'s [=associated store=].
-    1. Let |memtype| be [=mem_type=](|store|, |memaddr|).
-    1. If |memtype| has a max,
-        1. Let |maxsize| be the max value in |memtype|.
-    1. Otherwise,
-        1. Let |maxsize| be 65536 &times; 65536.
-    1. Let |resizableBuffer| be the result of [=create a resizable memory buffer|creating a resizable memory buffer=] from |memaddr| and |maxsize|.
-    1. If |buffer| is an {{ArrayBuffer}},
+    1. Let |resizableBuffer| be the result of [=create a resizable memory buffer|creating a resizable memory buffer=] from |memaddr|.
+    1. If [$IsSharedArrayBuffer$](|buffer|) is false,
         1. Perform [=!=] [$DetachArrayBuffer$](|buffer|, "WebAssembly.Memory").
     1. Set **this**.\[[BufferObject]] to |resizableBuffer|.
     1. Return |resizableBuffer|.
 </div>
 
-{{ArrayBuffer}} and {{SharedArrayBuffer}} objects returned by a {{Memory}} object must have size that is a  multiple of a WebAssembly [=page size=] (the constant 65536). For this reason [=HostResizeArrayBuffer=] and [=HostGrowSharedArrayBuffer=] are redefined as follows.
+{{ArrayBuffer}} and {{SharedArrayBuffer}} objects returned by a {{Memory}} object must have size that is a  multiple of a WebAssembly [=page size=] (the constant 65536). For this reason [$HostResizeArrayBuffer$] and [$HostGrowSharedArrayBuffer$] are redefined as follows.
 
-<div algorithm>
-    The <dfn>abstract operation [=HostResizeArrayBuffer=]</dfn> takes arguments an {{ArrayBuffer}} |buffer| and |newLength|. It performs the following steps when called.
+<div algorithm export>
+    The <dfn>abstract operation [$HostResizeArrayBuffer$]</dfn> takes arguments an {{ArrayBuffer}} |buffer| and |newLength|. It performs the following steps when called.
 
     1. If |buffer|.\[[ArrayBufferDetachKey]] is "WebAssembly.Memory",
         1. Let |map| be the [=surrounding agent=]'s associated [=Memory object cache=].
         1. Assert: |buffer| is the \[[BufferObject]] of exactly one value in |map|.
         1. [=map/iterate|For each=] |memaddr| &rarr; |mem| in |map|,
-            1. If [=SameValue=](mem.\[[BufferObject]], |buffer|) is true,
+            1. If [=SameValue=](|mem|.\[[BufferObject]], |buffer|) is true,
                 1. Assert: |buffer|.\[[ArrayBufferByteLength]] modulo 65536 is 0.
                 1. Let |lengthDelta| be |newLength| - |buffer|.\[[ArrayBufferByteLength]].
                 1. If |lengthDelta| &lt; 0 or |lengthDelta| modulo 65536 is not 0,
@@ -797,13 +802,13 @@ Immediately after a WebAssembly [=memory.grow=] instruction executes, perform th
     1. Otherwise, return unhandled.
 </div>
 
-<div algorithm>
-    The <dfn>abstract operation [=HostGrowSharedArrayBuffer=]</dfn> takes arguments a {{SharedArrayBuffer}} |buffer| and |newLength|. It performs the following steps when called.
+<div algorithm export>
+    The <dfn>abstract operation [$HostGrowSharedArrayBuffer$]</dfn> takes arguments a {{SharedArrayBuffer}} |buffer| and |newLength|. It performs the following steps when called.
 
     1. Let |map| be the [=surrounding agent=]'s associated [=Memory object cache=].
     1. Assert: |buffer| is the \[[BufferObject]] of exactly one value in |map|.
     1. [=map/iterate|For each=] |memaddr| &rarr; |mem| in |map|,
-        1. If [=SameValue=](mem.\[[BufferObject]], |buffer|) is true,
+        1. If [=SameValue=](|mem|.\[[BufferObject]], |buffer|) is true,
             1. Assert: |buffer|.\[[ArrayBufferByteLength]] modulo 65536 is 0.
             1. Let |lengthDelta| be |newLength| - |buffer|.\[[ArrayBufferByteLength]].
             1. If |lengthDelta| &lt; 0 or |lengthDelta| modulo 65536 is not 0,
@@ -813,7 +818,7 @@ Immediately after a WebAssembly [=memory.grow=] instruction executes, perform th
     1. If |newLength| &lt; |buffer|.\[[ArrayBufferByteLength]] or |newLength| &gt; |buffer|.\[[ArrayBufferMaxByteLength]], throw a {{RangeError}} exception.
     1. Let |agentRecord| be the surrounding agent's [=Agent Record=].
     1. Let |isLittleEndian| be |agentRecord|.\[[LittleEndian]] .
-    1. Let |event| be an implementation defined [=ReadModifyWriteSharedMemory=] event, whose \[[Order]] is "SeqCst", \[[Payload]] is  [§NumericToRawBytes$](Bigint, |newLength|, |isLittleEndian|), \[[Block]] is |buffer|.\[[ArrayBufferByteLengthData]], \[[ByteIndex]] is 0, and \[[ElementSize]] is 8.
+    1. Let |event| be an implementation defined [=ReadModifyWriteSharedMemory=] event, whose \[[Order]] is "SeqCst", \[[Payload]] is [$NumericToRawBytes$](Bigint, |newLength|, |isLittleEndian|), \[[Block]] is |buffer|.\[[ArrayBufferByteLengthData]], \[[ByteIndex]] is 0, and \[[ElementSize]] is 8.
     1. Let |eventsRecord| be the [=Agent Events Record|EventsRecord=] in |agentRecord|.\[[CandidateExecution]].\[[EventsRecords]] that corresponds to the surrounding agent's signifier |agentRecord|.\[[Signifier]].
     1. Append |event| to |eventsRecord|.\[[EventsList]].
     1. Return handled.
