From 28084b3bf698298bca8f14e43820babcf17885db Mon Sep 17 00:00:00 2001 From: Alan Jeffrey Date: Tue, 1 Aug 2017 13:33:30 -0500 Subject: [PATCH 1/3] Added text allowing speculative evaluation. --- css-paint-api/Overview.bs | 16 ++++++++++++---- worklets/Overview.bs | 24 ++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/css-paint-api/Overview.bs b/css-paint-api/Overview.bs index ab25d54f..f208e174 100644 --- a/css-paint-api/Overview.bs +++ b/css-paint-api/Overview.bs @@ -437,7 +437,8 @@ Note: The user agent can optionally defer drawing images which are paint-inva The draw a paint image function is invoked by the user agent during the object size -negotiation algorithm which is responsible for rendering an <>. +negotiation algorithm which is responsible for rendering an <>, +with |concreteObjectSize| set to the concrete object size of the box. For the purposes of the object size negotiation algorithm, the paint image has no intrinsic dimensions. @@ -450,6 +451,13 @@ Note: In a future version of the spec, the author could have the ability to spec The {{PaintSize}} object represents the size of the image that the author should draw. This is the concrete object size given by the user agent. +The draw a paint image function may be speculatively invoked by +the user agent at any point, with any |concreteObjectSize|. The +resulting image is discarded. + +Note: Although the image is discarded, it may still be cached, so subsequent invocations + of <> may use the cached image. + 
 [Exposed=PaintWorklet]
 interface PaintSize {
@@ -461,12 +469,12 @@ interface PaintSize {
 

 When the user agent wants to draw a paint image of a <> function for a |box|
 into its appropriate stacking level (as defined by the property the CSS property its associated
-with), given its |concreteObjectSize| (concrete object size) it must run the
-following steps:
+with), given |concreteObjectSize| it must run the following steps:
     1. Let |paintFunction| be the <> function on the |box| which the user agent wants to
         draw.
 
-    2. If the paint valid flag for the |paintFunction| is paint-valid the user agent
+    2. If the paint valid flag for the |paintFunction| is paint-valid,
+        and the previous invocation had the same |concreteObjectSize|, the user agent
         may use the drawn image from the previous invocation. If so it may abort
         all these steps and use the previously drawn image.
 
diff --git a/worklets/Overview.bs b/worklets/Overview.bs
index 06c4d17b..399eca24 100644
--- a/worklets/Overview.bs
+++ b/worklets/Overview.bs
@@ -119,6 +119,30 @@ The following techniques are used in order to encourage authors to write code in
 
  - User agents can create and destroy {{WorkletGlobalScope}}s at any time for these specifications.
 
+Speculative Evaluation {#speculative-evaluation}
+------------------------------------------------
+
+Some specifications which use worklets ([[css-paint-api-1]]) may
+invoke methods on a class based on the state of the user agent. To
+increase the concurrency between threads, a user agent may invoke a
+method speculatively, before a consistent snapshot of the state is
+known.
+
+In these specifications user agents might invoke methods on a class at
+any time, and with any arguments, not just ones corresponding to
+consistent states of the user agent. The results of such speculative
+evaluations will be discarded, but may be cached for later use, thus
+increasing the concurrency between the user agent and worklet threads.
+
+As a result of this, to prevent this compatibility risk between user
+agents, authors who register classes on the global scope using these
+APIs, should make their code stateless. That is, the only effect of
+invoking a method should be its result, not any side-effects such as
+updating mutable state.
+
+The same techniques which encourage code idempotence also encourage
+authors to write stateless code.
+
 Infrastructure {#infrastructure}
 ================================
 

From 5e309c7bde3b22fdb7502fe0cb28ca8e430dcefe Mon Sep 17 00:00:00 2001
From: Alan Jeffrey 
Date: Tue, 1 Aug 2017 16:22:40 -0500
Subject: [PATCH 2/3] Responding to review comment.

---
 css-paint-api/Overview.bs |  7 +++++--
 worklets/Overview.bs      | 10 +++++-----
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/css-paint-api/Overview.bs b/css-paint-api/Overview.bs
index f208e174..3ed24c0a 100644
--- a/css-paint-api/Overview.bs
+++ b/css-paint-api/Overview.bs
@@ -453,9 +453,12 @@ the concrete object size given by the user agent.
 
 The draw a paint image function may be speculatively invoked by
 the user agent at any point, with any |concreteObjectSize|. The
-resulting image is discarded.
+resulting image is not displayed.
 
-Note: Although the image is discarded, it may still be cached, so subsequent invocations
+Note: User agents may use any heuristic to speculate a possible future value
+    for |concretObjectSize|, for example speculating that the size remains unchanged.
+
+Note: Although the image is not displayed, it may still be cached, and subsequent invocations
     of <> may use the cached image.
 
 
diff --git a/worklets/Overview.bs b/worklets/Overview.bs
index 399eca24..4812d121 100644
--- a/worklets/Overview.bs
+++ b/worklets/Overview.bs
@@ -125,14 +125,14 @@ Speculative Evaluation {#speculative-evaluation}
 Some specifications which use worklets ([[css-paint-api-1]]) may
 invoke methods on a class based on the state of the user agent. To
 increase the concurrency between threads, a user agent may invoke a
-method speculatively, before a consistent snapshot of the state is
-known.
+method speculatively, based on potential future states.
 
 In these specifications user agents might invoke methods on a class at
 any time, and with any arguments, not just ones corresponding to
-consistent states of the user agent. The results of such speculative
-evaluations will be discarded, but may be cached for later use, thus
-increasing the concurrency between the user agent and worklet threads.
+the current state of the user agent. The results of such speculative
+evaluations are not displayed immediately, but may be cached for use
+if the user agent state matches the speculated state.
+This may increase the concurrency between the user agent and worklet threads.
 
 As a result of this, to prevent this compatibility risk between user
 agents, authors who register classes on the global scope using these

From ac505d88620655010fc6fe27333a249ad6294678 Mon Sep 17 00:00:00 2001
From: Alan Jeffrey 
Date: Fri, 11 Aug 2017 17:03:23 -0500
Subject: [PATCH 3/3] Filled to column 100.

---
 css-paint-api/Overview.bs |  5 ++---
 worklets/Overview.bs      | 32 ++++++++++++++------------------
 2 files changed, 16 insertions(+), 21 deletions(-)

diff --git a/css-paint-api/Overview.bs b/css-paint-api/Overview.bs
index 3ed24c0a..fec53983 100644
--- a/css-paint-api/Overview.bs
+++ b/css-paint-api/Overview.bs
@@ -451,9 +451,8 @@ Note: In a future version of the spec, the author could have the ability to spec
 The {{PaintSize}} object represents the size of the image that the author should draw. This is
 the concrete object size given by the user agent.
 
-The draw a paint image function may be speculatively invoked by
-the user agent at any point, with any |concreteObjectSize|. The
-resulting image is not displayed.
+The draw a paint image function may be speculatively invoked by the user agent at any point,
+with any |concreteObjectSize|. The resulting image is not displayed.
 
 Note: User agents may use any heuristic to speculate a possible future value
     for |concretObjectSize|, for example speculating that the size remains unchanged.
diff --git a/worklets/Overview.bs b/worklets/Overview.bs
index 4812d121..edd68eb8 100644
--- a/worklets/Overview.bs
+++ b/worklets/Overview.bs
@@ -122,26 +122,22 @@ The following techniques are used in order to encourage authors to write code in
 Speculative Evaluation {#speculative-evaluation}
 ------------------------------------------------
 
-Some specifications which use worklets ([[css-paint-api-1]]) may
-invoke methods on a class based on the state of the user agent. To
-increase the concurrency between threads, a user agent may invoke a
+Some specifications which use worklets ([[css-paint-api-1]]) may invoke methods on a class based on
+the state of the user agent. To increase the concurrency between threads, a user agent may invoke a
 method speculatively, based on potential future states.
 
-In these specifications user agents might invoke methods on a class at
-any time, and with any arguments, not just ones corresponding to
-the current state of the user agent. The results of such speculative
-evaluations are not displayed immediately, but may be cached for use
-if the user agent state matches the speculated state.
-This may increase the concurrency between the user agent and worklet threads.
-
-As a result of this, to prevent this compatibility risk between user
-agents, authors who register classes on the global scope using these
-APIs, should make their code stateless. That is, the only effect of
-invoking a method should be its result, not any side-effects such as
-updating mutable state.
-
-The same techniques which encourage code idempotence also encourage
-authors to write stateless code.
+In these specifications user agents might invoke methods on a class at any time, and with any
+arguments, not just ones corresponding to the current state of the user agent. The results of such
+speculative evaluations are not displayed immediately, but may be cached for use if the user agent
+state matches the speculated state.  This may increase the concurrency between the user agent and
+worklet threads.
+
+As a result of this, to prevent this compatibility risk between user agents, authors who register
+classes on the global scope using these APIs, should make their code stateless. That is, the only
+effect of invoking a method should be its result, not any side-effects such as updating mutable
+state.
+
+The same techniques which encourage code idempotence also encourage authors to write stateless code.
 
 Infrastructure {#infrastructure}
 ================================