Release 0.5.8

Author: adamw

README.md

@@ -23,13 +23,13 @@ the project!
 To test Ox, use the following dependency, using either [sbt](https://www.scala-sbt.org):
 
 ```scala
-"com.softwaremill.ox" %% "core" % "0.5.7"
+"com.softwaremill.ox" %% "core" % "0.5.8"
 ```
 
 Or [scala-cli](https://scala-cli.virtuslab.org):
 
 ```scala
-//> using dep "com.softwaremill.ox::core:0.5.7"
+//> using dep "com.softwaremill.ox::core:0.5.8"
 ```
 
 Documentation is available at [https://ox.softwaremill.com](https://ox.softwaremill.com), ScalaDocs can be browsed at [https://javadoc.io](https://www.javadoc.io/doc/com.softwaremill.ox).

generated-doc/out/index.md

@@ -2,7 +2,7 @@
 
 Safe direct-style concurrency and resiliency for Scala on the JVM. Requires JDK 21 & Scala 3.
 
-To start using Ox, add the `com.softwaremill.ox::core:0.5.7` [dependency](info/dependency.md) to your project. 
+To start using Ox, add the `com.softwaremill.ox::core:0.5.8` [dependency](info/dependency.md) to your project. 
 Then, take a look at the tour of Ox, or follow one of the topics listed in the menu to get to know Ox's API!
 
 In addition to this documentation, ScalaDocs can be browsed at [https://javadoc.io](https://www.javadoc.io/doc/com.softwaremill.ox).

generated-doc/out/info/dependency.md

@@ -4,10 +4,10 @@ To use ox core in your project, add:
 
 ```scala
 // sbt dependency
-"com.softwaremill.ox" %% "core" % "0.5.7"
+"com.softwaremill.ox" %% "core" % "0.5.8"
 
 // scala-cli dependency
-//> using dep com.softwaremill.ox::core:0.5.7
+//> using dep com.softwaremill.ox::core:0.5.8
 ```
 
 Ox core depends only on the Java [jox](https://github.com/softwaremill/jox) project, where channels are implemented. There are no other direct or transitive dependencies.

generated-doc/out/integrations/kafka.md

@@ -3,7 +3,7 @@
 Dependency:
 
 ```scala
-"com.softwaremill.ox" %% "kafka" % "0.5.7"
+"com.softwaremill.ox" %% "kafka" % "0.5.8"
 ```
 
 `Flow`s which read from a Kafka topic, mapping stages and drains which publish to Kafka topics are available through

generated-doc/out/integrations/mdc-logback.md

@@ -3,7 +3,7 @@
 Dependency:
 
 ```scala
-"com.softwaremill.ox" %% "mdc-logback" % "0.5.7"
+"com.softwaremill.ox" %% "mdc-logback" % "0.5.8"
 ```
 
 Ox provides support for setting inheritable MDC (mapped diagnostic context) values, when using the [Logback](https://logback.qos.ch)

generated-doc/out/streaming/flows.md

@@ -171,7 +171,7 @@ To obtain a `org.reactivestreams.Publisher` instance, you'll need to add the fol
 bring the `toReactiveStreamsPublisher` method into scope:
 
 ```scala
-// sbt dependency: "com.softwaremill.ox" %% "flow-reactive-streams" % "0.5.7"
+// sbt dependency: "com.softwaremill.ox" %% "flow-reactive-streams" % "0.5.8"
 
 import ox.supervised
 import ox.flow.Flow

generated-doc/out/tour.md

@@ -66,6 +66,14 @@ def computationR: Int = ???
 repeat(RepeatConfig.fixedRateForever(100.millis))(computationR)
 ```
 
+[Rate limit](utils/rate-limiter.md) computations:
+
+```scala
+supervised:
+  val rateLimiter = RateLimiter.fixedWindowWithStartTime(2, 1.second)
+  rateLimiter.runBlocking({ /* ... */ })
+```
+
 Allocate a [resource](utils/resources.md) in a scope:
 
 ```scala

generated-doc/out/utils/rate-limiter.md

@@ -1,6 +1,8 @@
 # Rate limiter
 
-The rate limiter mechanism allows controlling the rate at which operations are executed. It ensures that at most a certain number of operations are run concurrently within a specified time frame, preventing system overload and ensuring fair resource usage. Note that the implemented limiting mechanism only takes into account the start of execution and not the whole execution of an operation. 
+The rate limiter mechanism allows controlling the rate at which operations are executed. It ensures that at most a certain number of operations are run concurrently within a specified time frame, preventing system overload and ensuring fair resource usage. 
+
+Several rate limiting algorithms are available, either taking into account only the start time of the operation, or the entire duration of its execution.
 
 ## API
 
@@ -11,10 +13,8 @@ import ox.supervised
 import ox.resilience.*
 import scala.concurrent.duration.*
 
-val algorithm = RateLimiterAlgorithm.FixedWindow(2, 1.second)
-
 supervised: 
-  val rateLimiter = RateLimiter(algorithm)
+  val rateLimiter = RateLimiter.fixedWindowWithStartTime(2, 1.second)
 
   type T
   def operation: T = ???
@@ -34,24 +34,28 @@ The `operation` can be provided directly using a by-name parameter, i.e. `f: =>
 ## Configuration
 
 The configuration of a `RateLimiter` depends on an underlying algorithm that controls whether an operation can be executed or not. The following algorithms are available:
-- `RateLimiterAlgorithm.FixedWindow(rate: Int, dur: FiniteDuration)` - where `rate` is the maximum number of operations to be executed in fixed windows of `dur` duration.
-- `RateLimiterAlgorithm.SlidingWindow(rate: Int, dur: FiniteDuration)` - where `rate` is the maximum number of operations to be executed in any window of time of duration `dur`.
-- `RateLimiterAlgorithm.Bucket(maximum: Int, dur: FiniteDuration)` - where `maximum` is the maximum capacity of tokens available in the token bucket algorithm and one token is added each `dur`. It can represent both the leaky bucket algorithm or the token bucket algorithm.
+- `StartTimeRateLimiterAlgorithm.FixedWindow(rate: Int, per: FiniteDuration)` - where `rate` is the maximum number of operations to be executed in fixed windows of `per` duration.
+- `StartTimeRateLimiterAlgorithm.SlidingWindow(rate: Int, per: FiniteDuration)` - where `rate` is the maximum number of operations to be executed in any window of time of duration `per`.
+- `StartTimeRateLimiterAlgorithm.LeakyBucket(maximum: Int, per: FiniteDuration)` - where `rate` is the maximum capacity of tokens available in the token bucket algorithm and one token is added each `per`. It can represent both the leaky bucket algorithm or the token bucket algorithm.
+- `DurationRateLimiterAlgorithm.FixedWindow(rate: Int, per: FiniteDuration)` - where `rate` is the maximum number of operations which execution spans fixed windows of `per` duration. Considers whole execution time of an operation. Operation spanning more than one window blocks permits in all windows that it spans.
+- `DurationRateLimiterAlgorithm.SlidingWindow(rate: Int, per: FiniteDuration)` - where `rate` is the maximum number of operations which execution spans any window of time of duration `per`. Considers whole execution time of an operation. Operation release permit after `per` passed since operation ended.
 
 ### API shorthands
 
 You can use one of the following shorthands to define a Rate Limiter with the corresponding algorithm:
 
-- `RateLimiter.fixedWindow(rate: Int, dur: FiniteDuration)`,
-- `RateLimiter.slidingWindow(rate: Int, dur: FiniteDuration)`,
-- `RateLimiter.leakyBucket(maximum: Int, dur: FiniteDuration)`,
+- `RateLimiter.fixedWindowWithStartTime(maxOperations: Int, window: FiniteDuration)`
+- `RateLimiter.slidingWindowWithStartTime(maxOperations: Int, window: FiniteDuration)`
+- `RateLimiter.leakyBucket(maxTokens: Int, refillInterval: FiniteDuration)`
+- `RateLimiter.fixedWindowWithDuration(maxOperations: Int, window: FiniteDuration)`
+- `RateLimiter.slidingWindowWithDuration(maxOperations: Int, window: FiniteDuration)`
 
 See the tests in `ox.resilience.*` for more.
 
 ## Custom rate limiter algorithms
 
-The `RateLimiterAlgorithm` employed by `RateLimiter` can be extended to implement new algorithms or modify existing ones. Its interface is modelled like that of a `Semaphore` although the underlying implementation could be different. For best compatibility with the existing interface of `RateLimiter`, methods `acquire` and `tryAcquire` should offer the same guaranties as Java's `Semaphores`.
+The `RateLimiterAlgorithm` employed by `RateLimiter` can be extended to implement new algorithms or modify existing ones. Its interface is modelled like that of a `Semaphore` although the underlying implementation could be different. For best compatibility with the existing interface of `RateLimiter`, methods `acquire` and `tryAcquire` should offer the same guaranties as Java's `Semaphores`. There is also method `def runOperation[T](operation: => T, permits: Int): T` for cases where considering span of execution may be necessary (see implementations in `DurationRateLimiterAlgorithm`).
 
-Additionally, there are two methods employed by the `GenericRateLimiter` for updating its internal state automatically:
+Additionally, there are two methods employed by the `RateLimiter` for updating its internal state automatically:
 - `def update(): Unit`: Updates the internal state of the rate limiter to reflect its current situation. Invoked in a background fork repeatedly, when a rate limiter is created.
 - `def getNextUpdate: Long`: Returns the time in nanoseconds after which a new `update` needs to be called.