Skip to content

Commit

Permalink
Normative: integrate SharedArrayBuffer proposal section 2
Browse files Browse the repository at this point in the history
  • Loading branch information
@syg @bterlson
syg authored and bterlson committed Feb 1, 2017
1 parent 0378ed6 commit 034da0d
Showing 1 changed file with 64 additions and 4 deletions.
68 changes: 64 additions & 4 deletions spec.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ <h1>Web Scripting</h1>
<h1>ECMAScript Overview</h1>
<p>The following is an informal overview of ECMAScript&mdash;not all parts of the language are described. This overview is not part of the standard proper.</p>
<p>ECMAScript is object-based: basic language and host facilities are provided by objects, and an ECMAScript program is a cluster of communicating objects. In ECMAScript, an <em>object</em> is a collection of zero or more <em>properties</em> each with <em>attributes</em> that determine how each property can be used&mdash;for example, when the Writable attribute for a property is set to *false*, any attempt by executed ECMAScript code to assign a different value to the property fails. Properties are containers that hold other objects, <em>primitive values</em>, or <em>functions</em>. A primitive value is a member of one of the following built-in types: <b>Undefined</b>, <b>Null</b>, <b>Boolean</b>, <b>Number</b>, <b>String</b>, and <b>Symbol;</b> an object is a member of the built-in type <b>Object</b>; and a function is a callable object. A function that is associated with an object via a property is called a <em>method</em>.</p>
<p>ECMAScript defines a collection of <em>built-in objects</em> that round out the definition of ECMAScript entities. These built-in objects include the global object; objects that are fundamental to the runtime semantics of the language including `Object`, `Function`, `Boolean`, `Symbol`, and various `Error` objects; objects that represent and manipulate numeric values including `Math`, `Number`, and `Date`; the text processing objects `String` and `RegExp`; objects that are indexed collections of values including `Array` and nine different kinds of Typed Arrays whose elements all have a specific numeric data representation; keyed collections including `Map` and `Set` objects; objects supporting structured data including the `JSON` object, `ArrayBuffer`, and `DataView`; objects supporting control abstractions including generator functions and `Promise` objects; and, reflection objects including `Proxy` and `Reflect`.</p>
<p>ECMAScript defines a collection of <em>built-in objects</em> that round out the definition of ECMAScript entities. These built-in objects include the global object; objects that are fundamental to the runtime semantics of the language including `Object`, `Function`, `Boolean`, `Symbol`, and various `Error` objects; objects that represent and manipulate numeric values including `Math`, `Number`, and `Date`; the text processing objects `String` and `RegExp`; objects that are indexed collections of values including `Array` and nine different kinds of Typed Arrays whose elements all have a specific numeric data representation; keyed collections including `Map` and `Set` objects; objects supporting structured data including the `JSON` object, `ArrayBuffer`, `SharedArrayBuffer`, and `DataView`; objects supporting control abstractions including generator functions and `Promise` objects; and, reflection objects including `Proxy` and `Reflect`.</p>
<p>ECMAScript also defines a set of built-in <em>operators</em>. ECMAScript operators include various unary operations, multiplicative operators, additive operators, bitwise shift operators, relational operators, equality operators, binary bitwise operators, binary logical operators, assignment operators, and the comma operator.</p>
<p>Large ECMAScript programs are supported by <em>modules</em> which allow a program to be divided into multiple sequences of statements and declarations. Each module explicitly identifies declarations it uses that need to be provided by other modules and which of its declarations are available for use by other modules.</p>
<p>ECMAScript syntax intentionally resembles Java syntax. ECMAScript syntax is relaxed to enable it to serve as an easy-to-use scripting language. For example, a variable is not required to have its type declared nor are types associated with properties, and defined functions are not required to have their declarations appear textually before calls to them.</p>
Expand Down Expand Up @@ -945,7 +945,7 @@ <h1>Well-Known Symbols</h1>
<h1>The Number Type</h1>
<p>The Number type has exactly 18437736874454810627 (that is, <emu-eqn>2<sup>64</sup>-2<sup>53</sup>+3</emu-eqn>) values, representing the double-precision 64-bit format IEEE 754-2008 values as specified in the IEEE Standard for Binary Floating-Point Arithmetic, except that the 9007199254740990 (that is, <emu-eqn>2<sup>53</sup>-2</emu-eqn>) distinct &ldquo;Not-a-Number&rdquo; values of the IEEE Standard are represented in ECMAScript as a single special *NaN* value. (Note that the *NaN* value is produced by the program expression `NaN`.) In some implementations, external code might be able to detect a difference between various Not-a-Number values, but such behaviour is implementation-dependent; to ECMAScript code, all *NaN* values are indistinguishable from each other.</p>
<emu-note>
<p>The bit pattern that might be observed in an ArrayBuffer (see <emu-xref href="#sec-arraybuffer-objects"></emu-xref>) after a Number value has been stored into it is not necessarily the same as the internal representation of that Number value used by the ECMAScript implementation.</p>
<p>The bit pattern that might be observed in an ArrayBuffer (see <emu-xref href="#sec-arraybuffer-objects"></emu-xref>) or a SharedArrayBuffer (see <emu-xref href="#sec-sharedarraybuffer-objects">) after a Number value has been stored into it is not necessarily the same as the internal representation of that Number value used by the ECMAScript implementation.</p>
</emu-note>
<p>There are two other special values, called *positive Infinity* and *negative Infinity*. For brevity, these values are also referred to for expository purposes by the symbols *+&infin;* and *-&infin;*, respectively. (Note that these two infinite Number values are produced by the program expressions `+Infinity` (or simply `Infinity`) and `-Infinity`.)</p>
<p>The other 18437736874454810624 (that is, <emu-eqn>2<sup>64</sup>-2<sup>53</sup></emu-eqn>) values are called the finite numbers. Half of these are positive numbers and half are negative numbers; for every finite positive Number value there is a corresponding negative value having the same magnitude.</p>
Expand Down Expand Up @@ -1616,6 +1616,17 @@ <h1>Well-Known Intrinsic Objects</h1>
The initial value of the `values` data property of %ArrayPrototype% (<emu-xref href="#sec-array.prototype.values"></emu-xref>)
</td>
</tr>
<tr>
<td>
%Atomics%
</td>
<td>
`Atomics`
</td>
<td>
The initial value of the `Atomics` data property (<emu-xref href="#sec-atomics-object"></emu-xref>)
</td>
</tr>
<tr>
<td>
%Boolean%
Expand Down Expand Up @@ -2269,6 +2280,28 @@ <h1>Well-Known Intrinsic Objects</h1>
The initial value of the `prototype` data property of %Set%
</td>
</tr>
<tr>
<td>
%SharedArrayBuffer%
</td>
<td>
`SharedArrayBuffer`
</td>
<td>
The `SharedArrayBuffer` constructor (<emu-xref href="#sec-sharedarraybuffer-constructor"></emu-xref>)
</td>
</tr>
<tr>
<td>
%SharedArrayBufferPrototype%
</td>
<td>
`SharedArrayBuffer.prototype`
</td>
<td>
The initial value of the `prototype` data property of %SharedArrayBuffer%.
</td>
</tr>
<tr>
<td>
%String%
Expand Down Expand Up @@ -2972,6 +3005,9 @@ <h1>The Lexical Environment and Environment Record Specification Types</h1>
<h1>Data Blocks</h1>
<p>The <dfn>Data Block</dfn> specification type is used to describe a distinct and mutable sequence of byte-sized (8 bit) numeric values. A Data Block value is created with a fixed number of bytes that each have the initial value 0.</p>
<p>For notational convenience within this specification, an array-like syntax can be used to access the individual bytes of a Data Block value. This notation presents a Data Block value as a 0-origined integer indexed sequence of bytes. For example, if _db_ is a 5 byte Data Block value then _db_[2] can be used to access its 3<sup>rd</sup> byte.</p>
<p>A data block that resides in memory that can be referenced from multiple agents concurrently is designated a <dfn>Shared Data Block</dfn>. A Shared Data Block has an identity (for the purposes of equality testing Shared Data Block values) that is <em>address-free</em>: it is tied not to the virtual addresses the block is mapped to in any process, but to the set of locations in memory that the block represents. Shared Data Blocks can also be distinguished from Data Blocks.</p>
<p>The semantics of Shared Data Blocks is defined using Shared Data Block events by the Atomics memory model. Abstract operations below introduce Shared Data Block events and act as the interface between evaluation semantics and the event semantics of the memory model. The events form a candidate execution, on which the memory model acts as a filter. Please consult the memory model for full semantics.</p>
<p>Shared Data Block events are modeled by Records, defined in the Atomics memory model. All agents in an agent cluster share the same candidate execution record in its Agent Record's [[CandidateExecution] field, which is initialized to an empty candidate execution Record.</p>
<p>The following abstract operations are used in this specification to operate upon Data Block values:</p>

<!-- es6num="6.2.6.1" -->
Expand All @@ -2986,19 +3022,43 @@ <h1>CreateByteDataBlock ( _size_ )</h1>
</emu-alg>
</emu-clause>

<emu-clause id="sec-createsharedbytedatablock" aoid="CreateSharedByteDataBlock">
<h1>CreateSharedByteDataBlock( _size_ )</h1>
<p>When the abstract operation CreateSharedByteDataBlock is called with integer argument _size_, the following steps are taken:</p>
<emu-alg>
1. Assert: _size_&ge;0.
1. Let _db_ be a new Shared Data Block value consisting of _size_ bytes. If it is impossible to create such a Shared Data Block, throw a *RangeError* exception.
1. Let _execution_ be the [[CandidateExecution]] field of the <em>surrounding agent</em>'s Agent Record.
1. Let _eventList_ be the [[EventList]] field of the element in _execution_.[[EventLists]] whose [[AgentSignifier]] is AgentSignifier().
1. Let _zero_ be a List of length 1 that contains *0*.
1. For each index _i_ of _db_:
1. Append WriteSharedMemory{ [[Order]]: `"Init"`, [[NoTear]]: *true*, [[Block]]: _db_, [[ByteIndex]]: _i_, [[ElementSize]]: *1*, [[Payload]]: _zero_ } to _eventList_.
1. Return _db_.
</emu-alg>
</emu-clause>

<!-- es6num="6.2.6.2" -->
<emu-clause id="sec-copydatablockbytes" aoid="CopyDataBlockBytes">
<h1>CopyDataBlockBytes ( _toBlock_, _toIndex_, _fromBlock_, _fromIndex_, _count_ )</h1>
<p>When the abstract operation CopyDataBlockBytes is called, the following steps are taken:</p>
<emu-alg>
1. Assert: _fromBlock_ and _toBlock_ are distinct Data Block values.
1. Assert: _fromBlock_ and _toBlock_ are distinct Data Block or Shared Data Block values.
1. Assert: _fromIndex_, _toIndex_, and _count_ are integer values &ge; 0.
1. Let _fromSize_ be the number of bytes in _fromBlock_.
1. Assert: _fromIndex_+_count_ &le; _fromSize_.
1. Let _toSize_ be the number of bytes in _toBlock_.
1. Assert: _toIndex_+_count_ &le; _toSize_.
1. Repeat, while _count_&gt;0
1. Set _toBlock_[_toIndex_] to the value of _fromBlock_[_fromIndex_].
1. If _fromBlock_ is a Shared Data Block then
1. Let _execution_ be the [[CandidateExecution]] field of the <em>surrounding agent</em>'s Agent Record.
1. Let _eventList_ be the [[EventList]] field of the element in _execution_.[[EventLists]] whose [[AgentSignifier]] is AgentSignifier().
1. Let _bytes_ be a List of length *1* that contains a nondeterministically chosen byte value.
1. NOTE: In implementations, _bytes_ is the result of a non-atomic read instruction on the underlying hardware. The nondeterminism is a semantic prescription of the memory model to describe observable behavior of hardware with weak consistency.
1. Let _readEvent_ be ReadSharedMemory{ [[Order]]: `"Unordered"`, [[NoTear]]: *true*, [[Block]]: _fromBlock_, [[ByteIndex]]: _fromIndex_, [[ElementSize]]: *1* }.
1. Append _readEvent_ to _eventList_.
1. Append WriteSharedMemory{ [[Order]]: `"Unordered"`, [[NoTear]]: *true*, [[Block]]: _toBlock_, [[ByteIndex]]: _toIndex_, [[ElementSize]]: *1*, [[Payload]]: _bytes_ } to the _eventList_.
1. Append { [[Event]]: _readEvent_, [[ChosenValue]]: _bytes_ } to _execution_.[[ChosenValues]].
1. Otherwise, set _toBlock_[_toIndex_] to _fromBlock_[_fromIndex_].
1. Increment _toIndex_ and _fromIndex_ each by 1.
1. Decrement _count_ by 1.
1. Return NormalCompletion(~empty~).
Expand Down

0 comments on commit 034da0d

Please sign in to comment.