API description - Part 1. #5

mugdhalakhani · 2019-11-13T22:07:33Z

@beverloo PTAL.

spec/PeriodicBackgroundSync-index.bs

rayankans · 2019-11-18T12:26:50Z

spec/PeriodicBackgroundSync-index.bs

+    1. Else:
+        1. If |timeSinceLastPeriodicSync| is greater than equal to |minIntervalAcrossOrigins|, set |timeToFire| to |delayForOrigin| + |now|.
+        1. Else, set <var>timeTillNextAllowedPeriodicSync</var> to |minIntervalAcrossOrigins| - |timeSinceLastPeriodicSync|. Set |timeToFire| to the maximum of |delayForOrigin| + |now|, and |timeTillNextAllowedPeriodicSync| + |now|.
+    1. Set the [=time to fire=] of |registration| to |timeToFire|.


|registrations|'s [=time to fire=]

Also, I'd scope [=time to fire=] with the registration dfn, so it is accessible by using [=registration/time to fire=]

Re comment 1: done.
Re comment 2: In terms of how this is visible in the html, there's no difference. Also, if I do this, the same logic would apply to all other definitions under registration. Can you explain your reasoning? Are you worried these will be used outside of the spec?

It's for maintainability

done. The spec is a lot less readable, so I'd still appreciate an example of how this improves maintainability.

Same reason we use scopes and namespaces in code instead of having everything as a global variables. I'm sure you'll appreciate it if you have to amend sections of the spec a few months down the line :)

spec/PeriodicBackgroundSync-index.bs

rayankans · 2019-11-19T12:36:13Z

spec/PeriodicBackgroundSync-index.bs

+The user agent may also decide to retry each failed periodicSync event, capped to a user agent defined <dfn>maximum number of retries</dfn>.
+
+A possible algorithm to calculate the [=time to fire=], <var>timeToFire</var> for |registration| would involve running these steps:
+1. If this is the <dfn>first attempt of firing</dfn> the periodicSync event:


rayankans · 2019-11-19T12:38:16Z

spec/PeriodicBackgroundSync-index.bs

+    1. Else:
+        1. If |timeSinceLastPeriodicSync| is greater than equal to |minIntervalAcrossOrigins|, set |timeToFire| to |delayForOrigin| + |now|.
+        1. Else, set <var>timeTillNextAllowedPeriodicSync</var> to |minIntervalAcrossOrigins| - |timeSinceLastPeriodicSync|. Set |timeToFire| to the maximum of |delayForOrigin| + |now|, and |timeTillNextAllowedPeriodicSync| + |now|.
+    1. Set the [=time to fire=] of |registration| to |timeToFire|.


It's for maintainability

rayankans · 2019-11-19T13:46:16Z

spec/PeriodicBackgroundSync-index.bs

+
+The user agent MAY include factors such as user engagement with the origin to decide this time interval, allowing origins with high user engagement to update their web apps more often. In addition, the user agent SHOULD have per-origin and cross-origin caps on this interval, as recommended in [[#privacy]] and [[#resources]] sections.
+
+The user agent may also decide to retry each failed periodicSync event, capped to a user agent defined <dfn>maximum number of retries</dfn>.


I'd add a type here, the algorithm below would also benefit from types for variables

spec/PeriodicBackgroundSync-index.bs

mugdhalakhani · 2019-11-19T18:00:10Z

@rayankans I've moved global constants to Constructs, and added scoped references and types to the algorithms. PTAL.

rayankans

LGTM % Few minor comments & removing the periodicsync registration definition duplication

spec/PeriodicBackgroundSync-index.bs

rayankans · 2019-11-19T18:32:45Z

spec/PeriodicBackgroundSync-index.bs


-The <dfn>registration state</dfn> is one of <dfn>pending</dfn>, <dfn>waiting</dfn>, <dfn>firing</dfn>, or <dfn>reregisteredWhileFiring</dfn>. It is initially set to [=pending=].
+The <dfn>options</dfn> are a dictionary containing {{options/minInterval}}, a long long. <dfn attribute for=options>minInterval</dfn> is used to specify the minimum interval, in milliseconds, at which the periodic synchronization should happen. {{options/minInterval}} is a suggestion to the user agent. The actual interval at which <code>periodicsync</code> events are fired MUST be greater than or equal to this.
+Enclosing [=periodicsync registration/options=] in a dictionary allows this spec to be extended with more [=periodicsync registration/options=] in the future without adversely affecting existing usage.


I wouldn't include this line

This was a recommendation by Peter in a previous comment on this CL.

rayankans · 2019-11-19T18:35:29Z

spec/PeriodicBackgroundSync-index.bs


-The options are a dictionary containing [=minInterval=], a long long. <dfn>minInterval</dfn> is used to specify the minimum interval, in milliseconds, at which the periodic synchronization should happen. [=minInterval=] is a suggestion to the user agent. The actual interval at which <code>periodicsync</code> events are fired MUST be greater than or equal to this.
-Enclosing options in a dictionary allows this spec to be extended with more options in the future without adversely affecting existing usage.
+The <dfn>tag</dfn> is a {{DOMString}}. Within one [=list of periodicsync registrations=] each [=periodicsync registration=] MUST have a unique [=periodicsync registration/tag=]. Periodic Background Sync doesn't share namespace with Background Sync, so an [=origin can have registrations of both types with the same tag.


[=/string=]

I don't need to include any default-links with DOMString, whereas with =/string= there's still ambiguity:
Arbitrarily chose https://drafts.csswg.org/css-values-4/#string
To auto-select one of the following refs, insert one of these lines into a
block:
spec:infra; type:dfn; text:string
spec:css-values-4; type:dfn; text:string

spec/PeriodicBackgroundSync-index.bs

mugdhalakhani mentioned this pull request Nov 13, 2019

API Description + algorithm for register() WICG/background-sync#158

Closed

mugdhalakhani force-pushed the algorithms_1 branch from 916918a to b2a9e7a Compare November 14, 2019 16:09

beverloo reviewed Nov 14, 2019

View reviewed changes

mugdhalakhani force-pushed the algorithms_1 branch from b2a9e7a to 01c61a8 Compare November 15, 2019 16:54

mugdhalakhani commented Nov 15, 2019

View reviewed changes

spec/PeriodicBackgroundSync-index.bs Outdated Show resolved Hide resolved

mugdhalakhani force-pushed the algorithms_1 branch from 01c61a8 to cd4864c Compare November 15, 2019 17:23

rayankans requested changes Nov 18, 2019

View reviewed changes

mugdhalakhani force-pushed the algorithms_1 branch from cd4864c to 51a23f6 Compare November 18, 2019 14:11

mugdhalakhani requested a review from rayankans November 18, 2019 14:12

mugdhalakhani force-pushed the algorithms_1 branch 2 times, most recently from e66d43c to 1ddd11c Compare November 19, 2019 11:49

rayankans reviewed Nov 19, 2019

View reviewed changes

mugdhalakhani force-pushed the algorithms_1 branch from 1ddd11c to f53d536 Compare November 19, 2019 17:59

rayankans approved these changes Nov 19, 2019

View reviewed changes

mugdhalakhani force-pushed the algorithms_1 branch from f53d536 to 21916ca Compare November 19, 2019 19:27

API description - Part 1.

b6643e6

mugdhalakhani force-pushed the algorithms_1 branch from 21916ca to b6643e6 Compare November 19, 2019 19:28

mugdhalakhani merged commit 30e2c20 into master Nov 20, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API description - Part 1. #5

API description - Part 1. #5

mugdhalakhani commented Nov 13, 2019

rayankans Nov 18, 2019

mugdhalakhani Nov 18, 2019 •

edited

Loading

rayankans Nov 19, 2019

mugdhalakhani Nov 19, 2019

rayankans Nov 19, 2019

rayankans Nov 19, 2019

rayankans Nov 19, 2019

rayankans Nov 19, 2019

mugdhalakhani Nov 19, 2019

mugdhalakhani commented Nov 19, 2019

rayankans left a comment

rayankans Nov 19, 2019

mugdhalakhani Nov 19, 2019

rayankans Nov 19, 2019

mugdhalakhani Nov 19, 2019 •

edited

Loading


		The user agent MAY include factors such as user engagement with the origin to decide this time interval, allowing origins with high user engagement to update their web apps more often. In addition, the user agent SHOULD have per-origin and cross-origin caps on this interval, as recommended in [[#privacy]] and [[#resources]] sections.

		The user agent may also decide to retry each failed periodicSync event, capped to a user agent defined <dfn>maximum number of retries</dfn>.

API description - Part 1. #5

API description - Part 1. #5

Conversation

mugdhalakhani commented Nov 13, 2019

Choose a reason for hiding this comment

mugdhalakhani Nov 18, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mugdhalakhani commented Nov 19, 2019

rayankans left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mugdhalakhani Nov 19, 2019 • edited Loading

Choose a reason for hiding this comment

mugdhalakhani Nov 18, 2019 •

edited

Loading

mugdhalakhani Nov 19, 2019 •

edited

Loading