From dd52822e45852f706fd76842dd36775b2033d510 Mon Sep 17 00:00:00 2001 From: Jake Archibald Date: Mon, 25 Sep 2017 10:17:36 +0100 Subject: [PATCH 1/3] Making functional events simpler --- docs/index.bs | 60 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 39 insertions(+), 21 deletions(-) diff --git a/docs/index.bs b/docs/index.bs index 192f8d50..598c27d4 100644 --- a/docs/index.bs +++ b/docs/index.bs @@ -2144,13 +2144,9 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe
-

Request Functional Event Dispatch

+

Firing Functional Events

- To request a functional event dispatch to a [=/service worker=], specifications *may* invoke Handle Functional Event algorithm with its [=/service worker registration=] registration and the algorithm |callbackSteps| as the arguments. - - Specifications *may* define an algorithm |callbackSteps| where the corresponding functional event can be created and fired with specification specific objects. The algorithm is passed globalObject (a {{ServiceWorkerGlobalScope}} object) at which it *may* fire its functional events. This algorithm is called on a task queued by Handle Functional Event algorithm. - - Note: See an example hook defined in Notifications API. + To request a functional event dispatch to the [=service worker registration/active worker=] of a [=/service worker registration=], specifications *may* invoke fire a functional event.
@@ -2813,35 +2809,57 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe
-

Handle Functional Event

+

Fire a Functional Event

: Input - :: |event|, an {{ExtendableEvent}} object + :: |eventName|, a DOMString + :: |eventConstructor|, an event constructor that extends {{ExtendableEvent}} :: |registration|, a [=/service worker registration=] - :: |callbackSteps|, an algorithm + :: |initializationSteps|, optional steps to initialise |event|, constructed from |eventConstructor| + :: |postDispatchSteps|, optional steps to run on the [=service worker registration/active worker=]'s event loop, with |dispatchedEvent| set to the instance of |eventConstructor| that was [=dispatched=]. : Output :: None - 1. Assert: scope to registration map contains a value equal to |registration|. - 1. Assert: |registration|'s active worker is not null. - 1. Let |activeWorker| be |registration|'s active worker. - 1. If |activeWorker|'s set of event types to handle does not [=set/contain=] |event|'s {{Event/type}}, then: - 1. Return and continue running these steps in parallel. - 1. If the time difference in seconds calculated by the current time minus |registration|'s last update check time is greater than 86400, invoke Soft Update algorithm with |registration|. + 1. Assert: [=scope to registration map=] contains a value equal to |registration|. + 1. Assert: |registration|'s [=active worker=] is not null. + 1. Let |activeWorker| be |registration|'s [=active worker=]. + 1. If |activeWorker|'s [=set of event types to handle=] does not [=set/contain=] |eventName|, then return and run the following steps [=in parallel=]: + 1. If the time difference in seconds calculated by the current time minus |registration|'s [=last update check time=] is greater than 86400, invoke [=Soft Update=] algorithm with |registration|. 1. Abort these steps. Note: To avoid unnecessary delays, the Handle Functional Event enforces early return when no event listeners have been deterministically added in the service worker's global during the very first script execution. - 1. If |activeWorker|'s state is *activating*, wait for |activeWorker|'s state to become *activated*. - 1. Invoke Run Service Worker algorithm with |activeWorker| as the argument. - 1. Queue a task |task| to run these substeps: - 1. Invoke |callbackSteps| with |activeWorker|'s [=service worker/global object=] as its argument. + 1. If |activeWorker|'s [=state=] is *activating*, wait for |activeWorker|'s [=state=] to become *activated*. + 1. Invoke [=Run Service Worker=] algorithm with |activeWorker| as the argument. + 1. [=Queue a task=] |task| to run these substeps: + 1. Let |event| be the result of [=creating an event=] with |eventConstructor| and the [=relevant realm=] of |activeWorker|'s [=service worker/global object=]. + 1. If |initializationSteps| is not null, then initialize |event| with |initializationSteps|. + 1. [=Dispatch=] |event| on |activeWorker|'s [=service worker/global object=]. 1. Invoke [=Update Service Worker Extended Events Set=] with |activeWorker| and |event|. + 1. If |postDispatchSteps| is not null, then run |postDispatchSteps| passing |event| as |dispatchedEvent|. - The |task| *must* use |activeWorker|'s event loop and the handle functional event task source. + The |task| *must* use |activeWorker|'s [=event loop=] and the [=handle functional event task source=]. 1. Wait for |task| to have executed or been discarded. - 1. If the time difference in seconds calculated by the current time minus |registration|'s last update check time is greater than 86400, invoke Soft Update algorithm with |registration|. + 1. If the time difference in seconds calculated by the current time minus |registration|'s [=last update check time=] is greater than 86400, invoke [=Soft Update=] algorithm with |registration|. + +
+ To fire an "`amazingthing`" event (which is of type `AmazingThingEvent`) on a particular |serviceWorkerRegistration|, and initialize the event object's properties, the prose would be: + + 1. [=Fire a functional event=] named "`amazingthing`" using `AmazingThingEvent` on |serviceWorkerRegistration| with the following properties: + : propertyName + :: value + : anotherPropertyName + :: anotherValue + + Then run the following steps with |dispatchedEvent|: + + 1. Do whatever you need to with |dispatchedEvent|. + + Note that the initialization steps and post-dispatch steps are optional. If they aren't needed, the prose would be: + + 1. [=Fire a functional event=] named "`whatever`" using {{ExtendableEvent}} on |serviceWorkerRegistration|. +
From dae02eb2c84338d9d9e71407a4dba507177bfac1 Mon Sep 17 00:00:00 2001 From: Jake Archibald Date: Fri, 15 Jun 2018 11:58:59 +0100 Subject: [PATCH 2/3] Addressing nits and porting to v1 --- docs/index.bs | 16 ++++++------- docs/v1/index.bs | 60 +++++++++++++++++++++++++++++++----------------- 2 files changed, 47 insertions(+), 29 deletions(-) diff --git a/docs/index.bs b/docs/index.bs index 598c27d4..52c3a05b 100644 --- a/docs/index.bs +++ b/docs/index.bs @@ -2146,7 +2146,7 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe

Firing Functional Events

- To request a functional event dispatch to the [=service worker registration/active worker=] of a [=/service worker registration=], specifications *may* invoke fire a functional event. + To request a [=functional event=] dispatch to the [=service worker registration/active worker=] of a [=/service worker registration=], specifications *may* invoke [=Fire Functional Event=].
@@ -2809,13 +2809,13 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe
-

Fire a Functional Event

+

Fire Functional Event

: Input - :: |eventName|, a DOMString + :: |eventName|, a string :: |eventConstructor|, an event constructor that extends {{ExtendableEvent}} :: |registration|, a [=/service worker registration=] - :: |initializationSteps|, optional steps to initialise |event|, constructed from |eventConstructor| + :: |initialization|, optional property initialization for |event|, constructed from |eventConstructor| :: |postDispatchSteps|, optional steps to run on the [=service worker registration/active worker=]'s event loop, with |dispatchedEvent| set to the instance of |eventConstructor| that was [=dispatched=]. : Output :: None @@ -2833,7 +2833,7 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe 1. Invoke [=Run Service Worker=] algorithm with |activeWorker| as the argument. 1. [=Queue a task=] |task| to run these substeps: 1. Let |event| be the result of [=creating an event=] with |eventConstructor| and the [=relevant realm=] of |activeWorker|'s [=service worker/global object=]. - 1. If |initializationSteps| is not null, then initialize |event| with |initializationSteps|. + 1. If |initialization| is not null, then initialize |event| with |initialization|. 1. [=Dispatch=] |event| on |activeWorker|'s [=service worker/global object=]. 1. Invoke [=Update Service Worker Extended Events Set=] with |activeWorker| and |event|. 1. If |postDispatchSteps| is not null, then run |postDispatchSteps| passing |event| as |dispatchedEvent|. @@ -2846,7 +2846,7 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe
To fire an "`amazingthing`" event (which is of type `AmazingThingEvent`) on a particular |serviceWorkerRegistration|, and initialize the event object's properties, the prose would be: - 1. [=Fire a functional event=] named "`amazingthing`" using `AmazingThingEvent` on |serviceWorkerRegistration| with the following properties: + 1. [=Fire Functional Event=] "`amazingthing`" using `AmazingThingEvent` on |serviceWorkerRegistration| with the following properties: : propertyName :: value : anotherPropertyName @@ -2854,11 +2854,11 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe Then run the following steps with |dispatchedEvent|: - 1. Do whatever you need to with |dispatchedEvent|. + 1. Do whatever you need to with |dispatchedEvent| on the service worker's event loop. Note that the initialization steps and post-dispatch steps are optional. If they aren't needed, the prose would be: - 1. [=Fire a functional event=] named "`whatever`" using {{ExtendableEvent}} on |serviceWorkerRegistration|. + 1. [=Fire Functional Event=] "`whatever`" using {{ExtendableEvent}} on |serviceWorkerRegistration|.
diff --git a/docs/v1/index.bs b/docs/v1/index.bs index f9d46c61..a3338cef 100644 --- a/docs/v1/index.bs +++ b/docs/v1/index.bs @@ -2071,13 +2071,9 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe
-

Request Functional Event Dispatch

+

Firing Functional Events

- To request a functional event dispatch to a [=/service worker=], specifications *may* invoke Handle Functional Event algorithm with its [=/service worker registration=] registration and the algorithm |callbackSteps| as the arguments. - - Specifications *may* define an algorithm |callbackSteps| where the corresponding functional event can be created and fired with specification specific objects. The algorithm is passed globalObject (a {{ServiceWorkerGlobalScope}} object) at which it *may* fire its functional events. This algorithm is called on a task queued by Handle Functional Event algorithm. - - Note: See an example hook defined in Notifications API. + To request a [=functional event=] dispatch to the [=service worker registration/active worker=] of a [=/service worker registration=], specifications *may* invoke [=Fire Functional Event=].
@@ -2672,35 +2668,57 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe
-

Handle Functional Event

+

Fire Functional Event

: Input - :: |event|, an {{ExtendableEvent}} object + :: |eventName|, a string + :: |eventConstructor|, an event constructor that extends {{ExtendableEvent}} :: |registration|, a [=/service worker registration=] - :: |callbackSteps|, an algorithm + :: |initialization|, optional property initialization for |event|, constructed from |eventConstructor| + :: |postDispatchSteps|, optional steps to run on the [=service worker registration/active worker=]'s event loop, with |dispatchedEvent| set to the instance of |eventConstructor| that was [=dispatched=]. : Output :: None - 1. Assert: scope to registration map contains a value equal to |registration|. - 1. Assert: |registration|'s active worker is not null. - 1. Let |activeWorker| be |registration|'s active worker. - 1. If |activeWorker|'s set of event types to handle does not [=set/contain=] |event|'s {{Event/type}}, then: - 1. Return and continue running these steps in parallel. - 1. If the time difference in seconds calculated by the current time minus |registration|'s last update check time is greater than 86400, invoke Soft Update algorithm with |registration|. + 1. Assert: [=scope to registration map=] contains a value equal to |registration|. + 1. Assert: |registration|'s [=active worker=] is not null. + 1. Let |activeWorker| be |registration|'s [=active worker=]. + 1. If |activeWorker|'s [=set of event types to handle=] does not [=set/contain=] |eventName|, then return and run the following steps [=in parallel=]: + 1. If the time difference in seconds calculated by the current time minus |registration|'s [=last update check time=] is greater than 86400, invoke [=Soft Update=] algorithm with |registration|. 1. Abort these steps. Note: To avoid unnecessary delays, the Handle Functional Event enforces early return when no event listeners have been deterministically added in the service worker's global during the very first script execution. - 1. If |activeWorker|'s state is *activating*, wait for |activeWorker|'s state to become *activated*. - 1. Invoke Run Service Worker algorithm with |activeWorker| as the argument. - 1. Queue a task |task| to run these substeps: - 1. Invoke |callbackSteps| with |activeWorker|'s [=service worker/global object=] as its argument. + 1. If |activeWorker|'s [=state=] is *activating*, wait for |activeWorker|'s [=state=] to become *activated*. + 1. Invoke [=Run Service Worker=] algorithm with |activeWorker| as the argument. + 1. [=Queue a task=] |task| to run these substeps: + 1. Let |event| be the result of [=creating an event=] with |eventConstructor| and the [=relevant realm=] of |activeWorker|'s [=service worker/global object=]. + 1. If |initialization| is not null, then initialize |event| with |initialization|. + 1. [=Dispatch=] |event| on |activeWorker|'s [=service worker/global object=]. 1. Invoke [=Update Service Worker Extended Events Set=] with |activeWorker| and |event|. + 1. If |postDispatchSteps| is not null, then run |postDispatchSteps| passing |event| as |dispatchedEvent|. - The |task| *must* use |activeWorker|'s event loop and the handle functional event task source. + The |task| *must* use |activeWorker|'s [=event loop=] and the [=handle functional event task source=]. 1. Wait for |task| to have executed or been discarded. - 1. If the time difference in seconds calculated by the current time minus |registration|'s last update check time is greater than 86400, invoke Soft Update algorithm with |registration|. + 1. If the time difference in seconds calculated by the current time minus |registration|'s [=last update check time=] is greater than 86400, invoke [=Soft Update=] algorithm with |registration|. + +
+ To fire an "`amazingthing`" event (which is of type `AmazingThingEvent`) on a particular |serviceWorkerRegistration|, and initialize the event object's properties, the prose would be: + + 1. [=Fire Functional Event=] "`amazingthing`" using `AmazingThingEvent` on |serviceWorkerRegistration| with the following properties: + : propertyName + :: value + : anotherPropertyName + :: anotherValue + + Then run the following steps with |dispatchedEvent|: + + 1. Do whatever you need to with |dispatchedEvent| on the service worker's event loop. + + Note that the initialization steps and post-dispatch steps are optional. If they aren't needed, the prose would be: + + 1. [=Fire Functional Event=] "`whatever`" using {{ExtendableEvent}} on |serviceWorkerRegistration|. +
From 2c858162370562fa0e2375a65219baecac94fee4 Mon Sep 17 00:00:00 2001 From: Jake Archibald Date: Thu, 21 Jun 2018 14:04:37 +0100 Subject: [PATCH 3/3] 'should' --- docs/index.bs | 2 +- docs/v1/index.bs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.bs b/docs/index.bs index 52c3a05b..ac8c0d64 100644 --- a/docs/index.bs +++ b/docs/index.bs @@ -2146,7 +2146,7 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe

Firing Functional Events

- To request a [=functional event=] dispatch to the [=service worker registration/active worker=] of a [=/service worker registration=], specifications *may* invoke [=Fire Functional Event=]. + To request a [=functional event=] dispatch to the [=service worker registration/active worker=] of a [=/service worker registration=], specifications *should* invoke [=Fire Functional Event=].
diff --git a/docs/v1/index.bs b/docs/v1/index.bs index a3338cef..d952e2d1 100644 --- a/docs/v1/index.bs +++ b/docs/v1/index.bs @@ -2073,7 +2073,7 @@ spec: webappsec-referrer-policy; urlPrefix: https://w3c.github.io/webappsec-refe

Firing Functional Events

- To request a [=functional event=] dispatch to the [=service worker registration/active worker=] of a [=/service worker registration=], specifications *may* invoke [=Fire Functional Event=]. + To request a [=functional event=] dispatch to the [=service worker registration/active worker=] of a [=/service worker registration=], specifications *should* invoke [=Fire Functional Event=].