Allow tensors for graph constants.

As noted in the issue, sharing weights between graphs is a effective way
to enable reuse of device buffers, allowing web developers to manage
weight data in graphs similarly to other input or output buffers.

Resolves #760

Author: bbernhar

index.bs

@@ -869,6 +869,7 @@ interface MLContext {
   undefined dispatch(MLGraph graph, MLNamedTensors inputs, MLNamedTensors outputs);
 
   Promise<MLTensor> createTensor(MLTensorDescriptor descriptor);
+  Promise<MLConstantTensor> createConstantTensor(MLOperandDescriptor descriptor, AllowSharedBufferSource inputData);
 
   Promise<ArrayBuffer> readTensor(MLTensor tensor);
   Promise<undefined> readTensor(MLTensor tensor, AllowSharedBufferSource outputData);
@@ -941,6 +942,7 @@ The <dfn>context type</dfn> is the type of the execution context that manages th
     1. [=map/For each=] |name| → |tensor| of |namedTensors|:
         1. If |namedDescriptors|[|name|] does not [=map/exist=], then return false.
         1. If |tensor|.{{MLTensor/[[descriptor]]}} is not [=MLOperandDescriptor/equal=] to |namedDescriptors|[|name|], then return false.
+        1. If |tensor| is a {{MLConstantTensor}} then return false.
     1. Return true.
 </details>
 
@@ -1065,6 +1067,41 @@ Creates an {{MLTensor}} associated with this {{MLContext}}.
     1. Return |promise|.
 </details>
 
+### {{MLContext/createConstantTensor()}}  ### {#api-mlcontext-createconstanttensor}
+
+Creates an {{MLConstantTensor}} associated with this {{MLContext}}.
+
+<div dfn-for="MLContext/createConstantTensor(descriptor, inputData)" dfn-type=argument>
+    **Arguments:**
+      - <dfn>descriptor</dfn>: an {{MLOperandDescriptor}}.
+      - <dfn>inputData</dfn>: an {{AllowSharedBufferSource}}. The buffer whose bytes will be written into the tensor.
+
+    **Returns:** {{Promise}}<{{MLConstantTensor}}>.
+</div>
+
+<details open algorithm>
+  <summary>
+    The <dfn method for=MLContext>createConstantTensor(|descriptor|, |inputData|)</dfn> method steps are:
+  </summary>
+    1. Let |global| be [=this=]'s [=relevant global object=].
+    1. Let |realm| be [=this=]'s [=relevant realm=].
+    1. If [=this=] [=MLContext/is lost=], then return [=a new promise=] in |realm| [=rejected=] with an "{{InvalidStateError}}" {{DOMException}}.
+    1. If [=MLOperandDescriptor/checking dimensions=] given |descriptor| returns false, then [=exception/throw=] a {{TypeError}}.
+    1. If [=validating buffer with descriptor=] given |inputData| and |descriptor| returns false, then return [=a new promise=] in |realm| [=rejected=] with a {{TypeError}}.
+    1. Let |bytes| be the result of [=getting a copy of the bytes held by the buffer source=] given |inputData|.
+    1. [=Assert=]: |bytes|'s [=byte sequence/length=] is equal to |descriptor|'s [=MLOperandDescriptor/byte length=].
+    1. Let |tensor| be the result of [=creating an MLConstantTensor=] given [=this=], and |descriptor|.
+    1. Let |promise| be [=a new promise=] in |realm|.
+    1. Enqueue the following steps to [=this=].{{MLContext/[[timeline]]}}:
+        1. Run these steps, but [=/abort when=] [=this=] [=MLContext/is lost=]:
+            1. Create |tensor|.{{MLConstantTensor/[[data]]}} given |descriptor| and initialize all bytes to zeros.
+            1. Copy |bytes| to |tensor|.{{MLConstantTensor/[[data]]}}.
+            1. If that fails, then [=queue an ML task=] with |global| to [=reject=] |promise| with an "{{UnknownError}}" {{DOMException}}, and abort these steps.
+            1. Otherwise, [=queue an ML task=] with |global| to [=resolve=] |promise| with |tensor|.
+        1. [=/If aborted=], then [=queue an ML task=] with |global| to [=reject=] |promise| with an "{{InvalidStateError}}" {{DOMException}}.
+    1. Return |promise|.
+</details>
+
 ### {{MLContext/readTensor(tensor)}}  ### {#api-mlcontext-readtensor}
 
 Reads back the {{MLTensor/[[data]]}} of an {{MLTensor}} from the {{MLContext}}.{{MLContext/[[timeline]]}} to script.
@@ -1627,6 +1664,90 @@ Releases the resources associated with the {{MLTensor}}. This method is idempote
 
 Note: Since no further operations can be enqueued using this tensor, implementations can free any additional resource allocations associated with this tensor once all previously submitted operations using it are complete.
 
+## {{MLConstantTensor}} interface ## {#api-mlconstanttensor}
+
+The {{MLConstantTensor}} interface represents a tensor which may be used as a constant to an {{MLGraph}}. The memory backing an {{MLConstantTensor}} should be allocated in an [=implementation-defined=] fashion according to the requirements of the {{MLContext}} and the {{MLOperandDescriptor}} used to create it. Operations involving the {{MLConstantTensor/[[data]]}} of an {{MLConstantTensor}} occur on the {{MLContext/[[timeline]]}} of its associated {{MLContext}}.
+
+The [=implementation-defined=] requirements of how an {{MLConstantTensor}} is allocated may include constraints such as that the memory is allocated with a particular byte alignment or in a particular memory pool.
+
+<script type=idl>
+[SecureContext, Exposed=(Window, Worker)]
+interface MLConstantTensor : MLTensor {
+};
+</script>
+
+<div class=internal-slots>
+{{MLConstantTensor}} has the following internal slots:
+  <dl dfn-type=attribute dfn-for="MLConstantTensor">
+    : <dfn>\[[context]]</dfn> of type {{MLContext}}
+    ::
+        The {{MLConstantTensor}}'s associated context.
+
+    : <dfn>\[[descriptor]]</dfn> of type {{MLOperandDescriptor}}
+    ::
+        The {{MLConstantTensor}}'s descriptor.
+
+    : <dfn>\[[isDestroyed]]</dfn> of type {{boolean}}
+    ::
+        Whether the {{MLConstantTensor}}.{{MLConstantTensor/destroy()}} steps have been run. Once destroyed, the {{MLConstantTensor}} can no longer be used.
+
+    : <dfn>\[[data]]</dfn> of an [=implementation-defined=] type
+    ::
+        The bytes backing the {{MLConstantTensor}}. This data may only be accessed or modified from the {{MLConstantTensor/[[context]]}}.{{MLContext/[[timeline]]}}.
+  </dl>
+</div>
+
+An {{MLConstantTensor}}'s <dfn for=MLConstantTensor>dataType</dfn> is its {{MLConstantTensor/[[descriptor]]}}'s {{MLOperandDescriptor/dataType}}.
+
+An {{MLConstantTensor}}'s <dfn for=MLConstantTensor>shape</dfn> is its {{MLConstantTensor/[[descriptor]]}}'s {{MLOperandDescriptor/shape}}.
+
+The <dfn attribute for=MLConstantTensor>dataType</dfn> [=getter steps=] are to return [=this=]'s [=MLConstantTensor/dataType=].
+
+The <dfn attribute for=MLConstantTensor>shape</dfn> [=getter steps=] are to return [=this=]'s [=MLConstantTensor/shape=].
+
+The <dfn attribute for=MLConstantTensor>readable</dfn> [=getter steps=] are to return true.
+
+The <dfn attribute for=MLConstantTensor>writable</dfn> [=getter steps=] are to return false.
+
+### Creating an {{MLConstantTensor}} ### {#api-mlconstanttensor-create}
+
+An {{MLConstantTensor}} is created by its associated {{MLContext}}.
+
+<details open algorithm>
+  <summary>
+    To <dfn>create an MLConstantTensor</dfn> given {{MLContext}} |context|, {{MLOperandDescriptor}} |descriptor|, and {{AllowSharedBufferSource}} |inputData|, run the following steps:
+  </summary>
+    1. Let |realm| be |context|'s [=relevant realm=].
+    1. Let |tensor| be a new {{MLConstantTensor}} in |realm|.
+    1. Set |tensor|.{{MLConstantTensor/[[context]]}} to |context|.
+    1. Set |tensor|.{{MLConstantTensor/[[descriptor]]}} to |descriptor|.
+    1. Set |tensor|.{{MLConstantTensor/[[data]]}} to |inputData|.
+    1. Set |tensor|.{{MLConstantTensor/[[isDestroyed]]}} to false.
+    1. Set |tensor|.{{MLConstantTensor/[[descriptor]]}}.{{MLTensorDescriptor/readable}} to true.
+    1. Set |tensor|.{{MLConstantTensor/[[descriptor]]}}.{{MLTensorDescriptor/writable}} to false.
+    1. Return |tensor|.
+</details>
+
+### {{MLConstantTensor/destroy()}} ### {#api-mlconstanttensor-destroy}
+
+Releases the resources associated with the {{MLConstantTensor}}. This method is idempotent.
+
+<div dfn-for="MLConstantTensor/destroy()" dfn-type=argument>
+    **Returns:** {{undefined}}.
+</div>
+
+<details open algorithm>
+  <summary>
+    The <dfn method for=MLConstantTensor>destroy()</dfn> method steps are:
+  </summary>
+    1. Set [=this=].{{MLConstantTensor/[[isDestroyed]]}} to true.
+    1. Enqueue the following steps to [=this=].{{MLConstantTensor/[[context]]}}.{{MLContext/[[timeline]]}}:
+        1. Release [=this=].{{MLConstantTensor/[[data]]}}.
+    1. Return {{undefined}}.
+</details>
+
+Note: Since no further operations can be enqueued using this tensor, implementations can free any additional resource allocations associated with this tensor once all previously submitted operations using it are complete.
+
 ## {{MLGraphBuilder}} interface ## {#api-mlgraphbuilder}
 
 The {{MLGraphBuilder}} interface defines a set of operations as identified by the [[#usecases]] that can be composed into a computational graph. It also represents the intermediate state of a graph building session.
@@ -1649,6 +1770,9 @@ interface MLGraphBuilder {
   // Create a scalar operand from the specified number of the specified type.
   MLOperand constant(MLOperandDataType type, MLNumber value);
 
+  // Create an operand from a specified tensor.
+  MLOperand constant(MLConstantTensor tensor);
+
   // Compile the graph up to the specified output operands asynchronously.
   Promise<MLGraph> build(MLNamedOperands outputs);
 };
@@ -1749,6 +1873,28 @@ Create a constant {{MLOperand}} of the specified data type and shape that contai
     1. Return |operand|.
 </details>
 
+#### {{MLGraphBuilder/constant(tensor)}} #### {#api-mlgraphbuilder-constant-tensor}
+Create a constant {{MLOperand}} of the specified data type and shape that contains the initialized data.
+
+<div dfn-for="MLGraphBuilder/constant(tensor)" dfn-type=argument>
+    **Arguments:**
+        - <dfn>tensor</dfn>: an {{MLConstantTensor}}. The tensor containing the initialized data.
+    **Returns:** an {{MLOperand}}. The constant output tensor.
+</div>
+
+<details open algorithm>
+  <summary>
+    The <dfn method for=MLGraphBuilder>constant(|tensor|)</dfn> method steps are:
+  </summary>
+    1. If |tensor|.{{MLConstantTensor/[[context]]}} is not [=this=], then [=exception/throw=] a {{TypeError}}.
+    1. If |tensor|.{{MLConstantTensor/[[isDestroyed]]}} is true, then [=exception/throw=] a {{TypeError}}.
+    1. If [=this=] [=MLGraphBuilder/can not build=], then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.
+    1. *Make graph connections:*
+        1. Let |operand| be the result of [=creating an MLOperand=] given [=this=] and |tensor|.{{MLConstantTensor/[[descriptor]]}}.
+        1. Add |operand| to [=this=]'s [=MLGraphBuilder/graph=]'s [=computational graph/constants=] with |tensor| as value.
+    1. Return |operand|.
+</details>
+
 #### {{MLGraphBuilder/constant(type, value)}} #### {#api-mlgraphbuilder-constant-type-value}
 Create a scalar constant {{MLOperand}} of the specified value and data type.