Merge CE `setImmediate` docs into README #28

armanbilge · 2021-10-18T04:23:10Z

Tried to keep the best of both explanations, while adjusting for the wider audience here!

armanbilge · 2021-10-18T04:24:11Z

README.md

+}, 0);
+```
+
+Each timeout sets a new timeout, and so on and so on. This is exactly the sort of situation that we get into when chaining `Future`s, where each `map`/`flatMap`/`transform`/etc. schedules a another `Future` which, in turn will schedule another... etc. etc. This is exactly where we see clamping. In particular, the innermost `setTimeout` in this example will be clamped to 4 milliseconds (meaning there is no difference between `setTimeout(.., 0)` and `setTimeout(.., 4)`), which would slow down execution *even more*.


Did I explain this right, in terms of Future?

sjrd · 2021-10-18T09:11:23Z

README.md

@@ -44,16 +44,66 @@ loop()

 The `loop()` future will run forever when using the default Scala.js executor, which is written in terms of JavaScript's `Promise`. The *reason* this will run forever stems from the fact that JavaScript includes two separate work queues: the [microtask and the macrotask queue](https://javascript.info/event-loop). The microtask queue is used exclusively by `Promise`, while the macrotask queue is used by everything else, including UI rendering, `setTimeout`, and I/O such as Fetch or Node.js things. The semantics are such that, whenever the microtask queue has work, it takes full precedence over the macrotask queue until the microtask queue is completely exhausted.

-This explains why the above snippet will run forever on a `Promise`-based executor: the microtask queue is *never* empty because we're constantly adding new tasks! Thus, `setTimeout` is never able to run because the macrotask queue never receives control.
+This explains why the above snippet will run forever on a `Promise`-based executor: the microtask queue is *never* empty because we're constantly adding new tasks! Thus, `setTimeout` is never able to run because the macrotask queue never receives control. This is horrible, even by JavaScript standards.


Could we avoid being condescending at JavaScript, please? Scala.js doesn't make that kind of judgment calls. I don't think this new sentence brings any positive value.

I'm sorry, I knew better but I shoe-horned this in anyway. Besides adjusting for the new audience I forgot to adjust for the new venue.

I suppose line 81 below should be dropped/reworked too? Anything else?

Yes, perhaps remove "an all-too familiar patchwork of" from line 81. The sentence should otherwise stand on its own.

Other than that I think it's fine.

sjrd · 2021-10-18T09:14:28Z

README.md

+
+Fortunately, we aren't the only ones to have this problem. What we *want* is something which uses the macrotask queue (so we play nicely with `setTimeout`, I/O, and other macrotasks), but which doesn't have as much overhead as `setTimeout`. The answer is `setImmediate`.
+
+The `setImmediate` function was first introduced in NodeJS, and its purpose is to solve *exactly* this problem: a faster `setTimeout(..., 0)`. In particular, `setImmediate(...)` is *semantically* equivalent to `setTimeout(0, ...)`, except without the associated clamping: it doesn't include a delay mechanism of any sort, it simply takes a callback and immediately submits it to the event loop, which in turn will run the callback as soon as its turn comes up.


Suggested change

The `setImmediate` function was first introduced in NodeJS, and its purpose is to solve *exactly* this problem: a faster `setTimeout(..., 0)`. In particular, `setImmediate(...)` is *semantically* equivalent to `setTimeout(0, ...)`, except without the associated clamping: it doesn't include a delay mechanism of any sort, it simply takes a callback and immediately submits it to the event loop, which in turn will run the callback as soon as its turn comes up.

The `setImmediate` function was first introduced in Node.js, and its purpose is to solve *exactly* this problem: a faster `setTimeout(..., 0)`. In particular, `setImmediate(...)` is *semantically* equivalent to `setTimeout(0, ...)`, except without the associated clamping: it doesn't include a delay mechanism of any sort, it simply takes a callback and immediately submits it to the event loop, which in turn will run the callback as soon as its turn comes up.

There are more of those in the page.

sjrd · 2021-10-18T09:16:19Z

README.md

+
+That's the bad news. The good news is that all modern browsers include *some* sort of functionality which can be exploited to emulate `setImmediate` with similar performance characteristics. In particular, *most* environments take advantage of `postMessage` in some way. If you're interested in the nitty-gritty details of how this works, you are referred to [this excellent readme](https://github.com/YuzuJS/setImmediate#the-tricks).
+
+scala-js-macrotask-executor implements *most* of the `setImmediate` polyfill in terms of ScalaJS, wrapped up in an `ExecutionContext` interface. The only elements of the polyfill which are *not* implemented are as follows:


Suggested change

scala-js-macrotask-executor implements *most* of the `setImmediate` polyfill in terms of ScalaJS, wrapped up in an `ExecutionContext` interface. The only elements of the polyfill which are *not* implemented are as follows:

scala-js-macrotask-executor implements *most* of the `setImmediate` polyfill in terms of Scala.js, wrapped up in an `ExecutionContext` interface. The only elements of the polyfill which are *not* implemented are as follows:

There are more of those in the page.

sjrd · 2021-10-18T11:07:09Z

README.md

@@ -13,7 +13,7 @@ libraryDependencies += "org.scala-js" %%% "scala-js-macrotask-executor" % "1.0.0
 Published for Scala 2.11, 2.12, 2.13, 3. Functionality is fully supported on all platforms supported by Scala.js (including web workers). In the event that a given platform does *not* have the necessary functionality to implement `setImmediate`-style yielding (usually `postMessage` is what is required), the implementation will transparently fall back to using `setTimeout`, which will drastically inhibit performance but remain otherwise functional.

 ```scala
-import org.scalajs.macrotaskexecutor.MacrotaskExecutor.Implicits._
+import org.Scala.js.macrotaskexecutor.MacrotaskExecutor.Implicits._


Search-and-replace artifact ;)

😳 seems I leaked some of my internal implementation details 😉

Suggested change

import org.Scala.js.macrotaskexecutor.MacrotaskExecutor.Implicits._

import org.scalajs.macrotaskexecutor.MacrotaskExecutor.Implicits._

Co-authored-by: Sébastien Doeraene <sjrdoeraene@gmail.com>

README.md

Merge CE setImmediate docs into README

263ca34

armanbilge commented Oct 18, 2021

View reviewed changes

armanbilge mentioned this pull request Oct 18, 2021

Move setImmediate docs to macrotask-executor project typelevel/cats-effect#2426

Merged

Typo

a4c83f9

sjrd requested changes Oct 18, 2021

View reviewed changes

Address feedback

b28d377

sjrd reviewed Oct 18, 2021

View reviewed changes

Fix import

6a0646b

Co-authored-by: Sébastien Doeraene <sjrdoeraene@gmail.com>

armanbilge commented Oct 18, 2021

View reviewed changes

README.md Outdated Show resolved Hide resolved

Play nice

f9b61a4

sjrd approved these changes Oct 18, 2021

View reviewed changes

armanbilge mentioned this pull request Oct 25, 2021

Move setImmediate docs to macrotask project typelevel/cats-effect#2461

Closed

djspiewak merged commit 863ee02 into scala-js:main Nov 9, 2021

armanbilge mentioned this pull request Feb 6, 2023

Add Platforms Tags and Page typelevel/typelevel.github.com#422

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Merge CE `setImmediate` docs into README #28

Merge CE `setImmediate` docs into README #28

Uh oh!

armanbilge commented Oct 18, 2021

Uh oh!

armanbilge Oct 18, 2021

Uh oh!

sjrd Oct 18, 2021

Uh oh!

armanbilge Oct 18, 2021

Uh oh!

sjrd Oct 18, 2021

Uh oh!

sjrd Oct 18, 2021

Uh oh!

sjrd Oct 18, 2021

Uh oh!

sjrd Oct 18, 2021

Uh oh!

armanbilge Oct 18, 2021

Uh oh!

armanbilge Oct 18, 2021

Uh oh!

Uh oh!

Uh oh!


		Fortunately, we aren't the only ones to have this problem. What we want is something which uses the macrotask queue (so we play nicely with `setTimeout`, I/O, and other macrotasks), but which doesn't have as much overhead as `setTimeout`. The answer is `setImmediate`.

		The `setImmediate` function was first introduced in NodeJS, and its purpose is to solve exactly this problem: a faster `setTimeout(..., 0)`. In particular, `setImmediate(...)` is semantically equivalent to `setTimeout(0, ...)`, except without the associated clamping: it doesn't include a delay mechanism of any sort, it simply takes a callback and immediately submits it to the event loop, which in turn will run the callback as soon as its turn comes up.


		That's the bad news. The good news is that all modern browsers include some sort of functionality which can be exploited to emulate `setImmediate` with similar performance characteristics. In particular, most environments take advantage of `postMessage` in some way. If you're interested in the nitty-gritty details of how this works, you are referred to [this excellent readme](https://github.com/YuzuJS/setImmediate#the-tricks).

		scala-js-macrotask-executor implements most of the `setImmediate` polyfill in terms of ScalaJS, wrapped up in an `ExecutionContext` interface. The only elements of the polyfill which are not implemented are as follows:

	import org.Scala.js.macrotaskexecutor.MacrotaskExecutor.Implicits._
	import org.scalajs.macrotaskexecutor.MacrotaskExecutor.Implicits._

Merge CE setImmediate docs into README #28

Merge CE setImmediate docs into README #28

Uh oh!

Conversation

armanbilge commented Oct 18, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Merge CE `setImmediate` docs into README #28

Merge CE `setImmediate` docs into README #28