Merge pull request #127 from SystemFw/adjustable

Adjustable controls

Author: SystemFw

.github/workflows/ci.yml

@@ -26,19 +26,21 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        scala: [2.13.6, 3.0.0, 2.12.14]
-        java: [[email protected]11]
+        scala: [2.13.6, 3.1.0, 2.12.14]
+        java: [temurin@11]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout current branch (full)
         uses: actions/checkout@v2
         with:
           fetch-depth: 0
 
-      - name: Setup Java and Scala
-        uses: olafurpg/setup-scala@v13
+      - name: Setup Java (temurin@11)
+        if: matrix.java == 'temurin@11'
+        uses: actions/setup-java@v2
         with:
-          java-version: ${{ matrix.java }}
+          distribution: temurin
+          java-version: 11
 
       - name: Cache sbt
         uses: actions/cache@v2
@@ -77,18 +79,20 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         scala: [2.13.6]
-        java: [[email protected]11]
+        java: [temurin@11]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout current branch (full)
         uses: actions/checkout@v2
         with:
           fetch-depth: 0
 
-      - name: Setup Java and Scala
-        uses: olafurpg/setup-scala@v13
+      - name: Setup Java (temurin@11)
+        if: matrix.java == 'temurin@11'
+        uses: actions/setup-java@v2
         with:
-          java-version: ${{ matrix.java }}
+          distribution: temurin
+          java-version: 11
 
       - name: Cache sbt
         uses: actions/cache@v2
@@ -112,12 +116,12 @@ jobs:
           tar xf targets.tar
           rm targets.tar
 
-      - name: Download target directories (3.0.0)
+      - name: Download target directories (3.1.0)
         uses: actions/download-artifact@v2
         with:
-          name: target-${{ matrix.os }}-3.0.0-${{ matrix.java }}
+          name: target-${{ matrix.os }}-3.1.0-${{ matrix.java }}
 
-      - name: Inflate target directories (3.0.0)
+      - name: Inflate target directories (3.1.0)
         run: |
           tar xf targets.tar
           rm targets.tar
@@ -145,7 +149,7 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         scala: [2.13.6]
-        java: [[email protected]11]
+        java: [temurin@11]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Download target directories (2.13.6)
@@ -158,12 +162,12 @@ jobs:
           tar xf targets.tar
           rm targets.tar
 
-      - name: Download target directories (3.0.0)
+      - name: Download target directories (3.1.0)
         uses: actions/download-artifact@v2
         with:
-          name: target-${{ matrix.os }}-3.0.0-${{ matrix.java }}
+          name: target-${{ matrix.os }}-3.1.0-${{ matrix.java }}
 
-      - name: Inflate target directories (3.0.0)
+      - name: Inflate target directories (3.1.0)
         run: |
           tar xf targets.tar
           rm targets.tar

build.sbt

@@ -18,10 +18,8 @@ Global / excludeLintKeys += scmInfo
 val Scala213 = "2.13.6"
 ThisBuild / spiewakMainBranches := Seq("main")
 
-ThisBuild / crossScalaVersions := Seq(Scala213, "3.0.0", "2.12.14")
-ThisBuild / versionIntroduced := Map("3.0.0" -> "0.4.0")
+ThisBuild / crossScalaVersions := Seq(Scala213, "3.1.0", "2.12.14")
 ThisBuild / scalaVersion := (ThisBuild / crossScalaVersions).value.head
-Global / excludeLintKeys += versionIntroduced
 ThisBuild / initialCommands := """
   |import cats._, data._, syntax.all._
   |import cats.effect._, concurrent._
@@ -34,6 +32,7 @@ ThisBuild / initialCommands := """
 """.stripMargin
 
 ThisBuild / testFrameworks += new TestFramework("munit.Framework")
+ThisBuild / Test / parallelExecution := false
 
 def dep(org: String, prefix: String, version: String)(modules: String*)(testModules: String*) =
   modules.map(m => org %% (prefix ++ m) % version) ++
@@ -50,12 +49,12 @@ lazy val core = project
     name := "upperbound",
     scalafmtOnCompile := true,
     libraryDependencies ++=
-      dep("org.typelevel", "cats-", "2.6.1")("core")() ++
-      dep("org.typelevel", "cats-effect", "3.3-162-2022ef9")("")("-laws", "-testkit") ++
-      dep("co.fs2", "fs2-", "3.1.3")("core")() ++
+      dep("org.typelevel", "cats-", "2.7.0")("core")() ++
+      dep("org.typelevel", "cats-effect", "3.3.1")("")("-laws", "-testkit") ++
+      dep("co.fs2", "fs2-", "3.2.4")("core")() ++
       dep("org.scalameta", "munit", "0.7.29")()("", "-scalacheck") ++
-      dep("org.typelevel", "", "1.0.5")()("munit-cats-effect-3") ++
-      dep("org.typelevel",  "scalacheck-effect", "1.0.2")()("", "-munit")
+      dep("org.typelevel", "", "1.0.7")()("munit-cats-effect-3") ++
+      dep("org.typelevel",  "scalacheck-effect", "1.0.3")()("", "-munit")
   )
 
 lazy val docs = project
@@ -75,8 +74,6 @@ lazy val docs = project
   .dependsOn(core)
   .enablePlugins(MdocPlugin, NoPublishPlugin)
 
-ThisBuild / githubWorkflowJavaVersions := Seq("[email protected]")
-
 ThisBuild / githubWorkflowBuildPostamble ++= List(
   WorkflowStep.Sbt(
     List("docs/mdoc"),

docs/_coverpage.md

@@ -4,7 +4,7 @@
 
 - Interval-based design to prevent bursts
 - Prioritised jobs
-- Controls both rate and concurrency
+- Dynamic controls over both rate and concurrency
 
 [Getting started](installing.md)
 

docs/_sidebar.md

@@ -1,4 +1,3 @@
 - [Installing](installing.md)
 - [Design](design.md)
 - [Limiter](limiter.md)
-- [Migration guide](migration.md)

docs/design.md

@@ -10,6 +10,7 @@ It's intended as a simple, minimal library, but with enough control to
 be broadly applicable, including:
 - Job execution rate
 - Maximum concurrency of jobs
+- Dynamically adjustable rate and concurrency
 - Prioritisation of jobs
 
 **upperbound** is a purely functional library, built on top of

docs/limiter.md

@@ -52,8 +52,8 @@ new limiter and starts processing jobs submitted to it.
 object Limiter {
   def start[F[_]: Temporal](
     minInterval: FiniteDuration,
-    maxQueued: Int = Int.MaxValue,
-    maxConcurrent: Int = Int.MaxValue
+    maxConcurrent: Int = Int.MaxValue,
+    maxQueued: Int = Int.MaxValue
   ): Resource[F, Limiter[F]]
 }
 ```
@@ -174,13 +174,46 @@ limiter.use { limiter =>
 ```
 
 If you struggled to make sense of the examples in this section, it's
-recommended to watch [this
-talk](https://github.com/SystemFw/scala-italy-2018).
+recommended to watch [this talk](https://github.com/SystemFw/scala-italy-2018.)
 
+## Adjusting rate and concurrency
+
+**upperbound** lets you control both the rate of submission and the
+maximum concurrency dynamically, through the following methods on
+`Limiter`:
+
+```scala
+def minInterval: F[FiniteDuration]
+def setMinInterval(newMinInterval: FiniteDuration): F[Unit]
+def updateMinInterval(update: FiniteDuration => FiniteDuration): F[Unit]
+
+def maxConcurrent: F[Int]
+def setMaxConcurrent(newMaxConcurrent: Int): F[Unit]
+def updateMaxConcurrent(update: Int => Int): F[Unit]
+```
+
+The `*minInterval` methods let you change the rate of submission by
+varying the minimum time interval between two tasks. If the interval
+changes while the limiter is sleeping between tasks, the duration of
+the sleep is adjusted on the fly, taking into account any elapsed
+time. This might mean waking up instantly if the entire new interval
+has already elapsed.
+
+The `*maxConcurrent` methods let you change the maximum number of
+concurrent tasks that can be executing at any given time. If the
+concurrency limit gets changed while the limiter is already blocked
+waiting for some tasks to finish, the limiter will then be unblocked
+as soon as the number of running tasks goes below the new concurrency
+limit. Note however that if the limit shrinks the limiter will not try to
+interrupt tasks that are already running, so for some time it might be
+that `runningTasks > maxConcurrent`.
+  
+    
 ## Test limiter
 
 **upperbound** also provides `Limiter.noOp` for testing purposes, which is
 a stub `Limiter` with no actual rate limiting and a synchronous
 `submit` method.
 
 
+