diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..aff82a1 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5207dce..4c94d84 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,16 +9,18 @@ name: Continuous Integration on: pull_request: - branches: ['**'] + branches: ['**', '!update/**', '!pr/**'] push: - branches: ['**'] + branches: ['**', '!update/**', '!pr/**'] tags: [v*] env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }} + PGP_PASSPHRASE: ${{ secrets.PGP_PASSPHRASE }} SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }} + SONATYPE_CREDENTIAL_HOST: ${{ secrets.SONATYPE_CREDENTIAL_HOST }} + SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }} PGP_SECRET: ${{ secrets.PGP_SECRET }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} jobs: build: @@ -26,23 +28,34 @@ jobs: strategy: matrix: os: [ubuntu-latest] - scala: [2.11.12, 2.12.14, 2.13.6, 3.0.2] - java: [adopt@1.8] + scala: [2.11.12, 2.12.16, 2.13.7, 3.1.3] + java: [temurin@8] ci: [ciNode, ciFirefox, ciChrome, ciJSDOMNodeJS] runs-on: ${{ matrix.os }} steps: - name: Checkout current branch (full) - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: fetch-depth: 0 - - name: Setup Java and Scala - uses: olafurpg/setup-scala@v13 + - name: Download Java (temurin@8) + id: download-java-temurin-8 + if: matrix.java == 'temurin@8' + uses: typelevel/download-java@v2 + with: + distribution: temurin + java-version: 8 + + - name: Setup Java (temurin@8) + if: matrix.java == 'temurin@8' + uses: actions/setup-java@v3 with: - java-version: ${{ matrix.java }} + distribution: jdkfile + java-version: 8 + jdkFile: ${{ steps.download-java-temurin-8.outputs.jdkFile }} - name: Cache sbt - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: | ~/.sbt @@ -53,44 +66,58 @@ jobs: ~/Library/Caches/Coursier/v1 key: ${{ runner.os }}-sbt-cache-v2-${{ hashFiles('**/*.sbt') }}-${{ hashFiles('project/build.properties') }} - - name: Setup NodeJS v14 LTS + - name: Setup sbt + uses: sbt/setup-sbt@v1 + + - name: Setup NodeJS v18 LTS if: matrix.ci == 'ciNode' || matrix.ci == 'ciJSDOMNodeJS' - uses: actions/setup-node@v2.1.2 + uses: actions/setup-node@v3 with: - node-version: 14 + node-version: 18 + cache: npm - name: Install jsdom if: matrix.ci == 'ciJSDOMNodeJS' run: npm install - name: Check that workflows are up to date - run: sbt ++${{ matrix.scala }} githubWorkflowCheck + run: sbt githubWorkflowCheck - - run: sbt ++${{ matrix.scala }} '${{ matrix.ci }}' + - run: sbt '++ ${{ matrix.scala }}' '${{ matrix.ci }}' publish: name: Publish Artifacts needs: [build] - if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v')) + if: github.event_name != 'pull_request' && (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main') strategy: matrix: os: [ubuntu-latest] - scala: [3.0.2] - java: [adopt@1.8] + java: [temurin@8] runs-on: ${{ matrix.os }} steps: - name: Checkout current branch (full) - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: fetch-depth: 0 - - name: Setup Java and Scala - uses: olafurpg/setup-scala@v13 + - name: Download Java (temurin@8) + id: download-java-temurin-8 + if: matrix.java == 'temurin@8' + uses: typelevel/download-java@v2 with: - java-version: ${{ matrix.java }} + distribution: temurin + java-version: 8 + + - name: Setup Java (temurin@8) + if: matrix.java == 'temurin@8' + uses: actions/setup-java@v3 + with: + distribution: jdkfile + java-version: 8 + jdkFile: ${{ steps.download-java-temurin-8.outputs.jdkFile }} - name: Cache sbt - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: | ~/.sbt @@ -102,15 +129,34 @@ jobs: key: ${{ runner.os }}-sbt-cache-v2-${{ hashFiles('**/*.sbt') }}-${{ hashFiles('project/build.properties') }} - name: Import signing key - env: - PGP_PASSPHRASE: ${{ secrets.PGP_PASSPHRASE }} + if: env.PGP_SECRET != '' && env.PGP_PASSPHRASE == '' + run: echo $PGP_SECRET | base64 -di | gpg --import + + - name: Import signing key and strip passphrase + if: env.PGP_SECRET != '' && env.PGP_PASSPHRASE != '' run: | - echo "$PGP_SECRET" | base64 -d > /tmp/signing-key.gpg + echo "$PGP_SECRET" | base64 -di > /tmp/signing-key.gpg echo "$PGP_PASSPHRASE" | gpg --pinentry-mode loopback --passphrase-fd 0 --import /tmp/signing-key.gpg + (echo "$PGP_PASSPHRASE"; echo; echo) | gpg --command-fd 0 --pinentry-mode loopback --change-passphrase $(gpg --list-secret-keys --with-colons 2> /dev/null | grep '^sec:' | cut --delimiter ':' --fields 5 | tail -n 1) - - name: Strip passphrase from signing key - env: - PGP_PASSPHRASE: ${{ secrets.PGP_PASSPHRASE }} - run: (echo "$PGP_PASSPHRASE"; echo; echo) | gpg --command-fd 0 --pinentry-mode loopback --change-passphrase 5EBC14B0F6C55083 + - name: Setup sbt + uses: sbt/setup-sbt@v1 + + - name: Publish + run: sbt tlCiRelease + + validate-steward: + name: Validate Steward Config + strategy: + matrix: + os: [ubuntu-latest] + runs-on: ${{ matrix.os }} + steps: + - name: Checkout current branch (fast) + uses: actions/checkout@v3 + + - uses: coursier/setup-action@v1 + with: + apps: scala-steward - - run: sbt ++${{ matrix.scala }} release + - run: scala-steward validate-repo-config .scala-steward.conf diff --git a/.scala-steward.conf b/.scala-steward.conf new file mode 100644 index 0000000..f556581 --- /dev/null +++ b/.scala-steward.conf @@ -0,0 +1,4 @@ +updates.ignore = [ + { groupId = "org.scala-lang" }, + { groupId = "org.scala-js" } +] diff --git a/README.md b/README.md index 2d49dfb..0f7efc0 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ An implementation of `ExecutionContext` in terms of JavaScript's [`setImmediate` ## Usage ```sbt -libraryDependencies += "org.scala-js" %%% "scala-js-macrotask-executor" % "1.0.0" +libraryDependencies += "org.scala-js" %%% "scala-js-macrotask-executor" % "1.1.1" ``` 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. @@ -46,14 +46,64 @@ The `loop()` future will run forever when using the default Scala.js executor, w 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 fixable by using a `setTimeout`-based executor, such as the `QueueExecutionContext.timeouts()` implementation in Scala.js. Unfortunately, this runs into an even more serious issue: `setTimeout` is *clamped* in all JavaScript environments. In particular, it is clamped to a minimum of 4ms and, in practice, usually somewhere between 4ms and 10ms. This clamping kicks in whenever more than 5 consecutive timeouts have been scheduled. You can read more details [in the MDM documentation](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers.setTimeout#Minimum.2F_maximum_delay_and_timeout_nesting). +### `setTimeout` -The only solution to this mess is to yield to the macrotask queue *without* using `setTimeout`. This is precisely what `setImmediate` does on Edge and Node.js. In particular, `setImmediate(...)` is *semantically* equivalent to `setTimeout(0, ...)`, except without the associated clamping. Unfortunately, due to the fact that only a pair of platforms support this function, alternative implementations are required across other major browsers. In particular, *most* environments take advantage of `postMessage` in some way. +This is fixable by using a `setTimeout`-based executor, such as the `QueueExecutionContext.timeouts()` implementation in Scala.js. Available in all browsers since the dawn of time, `setTimeout` takes two arguments: a time delay and a callback to invoke. The callback is invoked by the event loop once the time delay expires, and this is implemented by pushing the callback onto the back of the event queue at the appropriate time. Calling `setTimeout` with a delay of `0` would seem to achieve *exactly* the semantics we want: yield back to the event loop and allow it to resume our callback when it's our turn once again. + +Unfortunately, `setTimeout` is slow. Very, very, very slow. The timing mechanism imposes quite a bit of overhead, even when the delay is `0`, and there are other complexities which ultimately impose a performance penalty too severe to accept. Any significant application of an `ExecutionContext` backed by `setTimeout`, would be almost unusable. + +To make matters worse, `setTimeout` is *clamped* in all JavaScript environments. In particular, it is clamped to a minimum of 4ms and, in practice, usually somewhere between 4ms and 10ms. This clamping kicks in whenever more than 5 consecutive timeouts have been scheduled: + +```javascript +setTimeout(() => { + setTimeout(() => { + setTimeout(() => { + setTimeout(() => { + setTimeout(() => { + // this one (and all after it) are clamped! + }, 0); + }, 0); + }, 0); + }, 0); +}, 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 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*. + +You can read more details [in the MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers.setTimeout#Minimum.2F_maximum_delay_and_timeout_nesting). + +### `setImmediate` + +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 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. + +Unfortunately, `setImmediate` isn't available on every platform. For reasons of... their own, Mozilla, Google, and Apple have all strenuously objected to the inclusion of `setImmediate` in the W3C standard set, despite the proposal (which originated at Microsoft) and obvious usefulness. This in turn has resulted in inconsistency across the JavaScript space. + +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 Scala.js, wrapped up in an `ExecutionContext` interface. The only elements of the polyfill which are *not* implemented are as follows: + +- `process.nextTick` is used by the JavaScript polyfill when running on Node.js versions below 0.9. However, Scala.js itself does not support Node.js 0.9 or below, so there's really no point in supporting this case. +- Similarly, older versions of IE (6 through 8, specifically) allow a particular exploitation of the `onreadystatechange` event fired when a `