experiment: try to optimize real time queue by re-ordering tests and avoiding redundant allocations

Changelog.md

@@ -2,6 +2,9 @@
 
 ## Next
 
+* Add `reverse` function to the `pure/Queue` module (#229).
+* Add `pure/RealTimeQueue` module - an alternative immutable double-ended queue implementation with worst-case `O(1)` time complexity for all operations but worse amortized performance (#229).
+  - Refer to the `Queues.bench.mo` benchmark for comparison with other queue implementations.
 * Rename `Map.replaceIfExists()` to `Map.replace()` (#286).
 * Add `entriesFrom` and `reverseEntriesFrom` to `Map`, `valuesFrom` and `reverseValuesFrom` to `Set` and `Text.toText` (#272).
 * Update code examples in doc comments (#224, #282).

bench/Queues.bench.mo

@@ -0,0 +1,108 @@
+import Bench "mo:bench";
+
+import Array "../src/Array";
+import Nat "../src/Nat";
+import Option "../src/Option";
+import OldQueue "../src/pure/Queue";
+import NewQueue "../src/pure/RealTimeQueue";
+import MutQueue "../src/Queue";
+import Runtime "../src/Runtime";
+
+module {
+  public func init() : Bench.Bench {
+    let bench = Bench.Bench();
+
+    bench.name("Different queue implementations");
+    bench.description("Compare the performance of the following queue implementations_:
+- `pure/Queue`: The default immutable double-ended queue implementation.
+  * Pros: Good amortized performance, meaning that the average cost of operations is low `O(1)`.
+  * Cons: In worst case, an operation can take `O(size)` time rebuilding the queue as demonstrated in the `Pop front 2 elements` scenario.
+- `pure/RealTimeQueue`
+  * Pros: Every operation is guaranteed to take at most `O(1)` time and space.
+  * Cons: Poor amortized performance: Instruction cost is on average 4x for *pop* and 10x for *push* compared to `pure/Queue`.
+- mutable `Queue`
+  * Pros: Also `O(1)` guarantees with a lower constant factor than `pure/RealTimeQueue`. Amortized performance is comparable to `pure/Queue`.
+  * Cons: It is mutable and cannot be used in `shared` types (not shareable)_.");
+
+    bench.rows([
+      "Initialize with 2 elements",
+      "Push 500 elements",
+      "Pop front 2 elements",
+      "Pop 150 front&back"
+    ]);
+    bench.cols([
+      "pure/Queue",
+      "pure/RealTimeQueue",
+      "mutable Queue"
+    ]);
+
+    let init = Array.repeat(1, 2);
+    var newQ = NewQueue.empty<Nat>();
+    var oldQ = OldQueue.empty<Nat>();
+    var mutQ = MutQueue.empty<Nat>();
+
+    let toPush = Array.repeat(7, 500);
+
+    bench.runner(
+      func(row, col) = switch (col, row) {
+        case ("pure/RealTimeQueue", "Initialize with 2 elements") newQ := NewQueue.fromIter<Nat>(init.vals());
+        case ("pure/Queue", "Initialize with 2 elements") oldQ := OldQueue.fromIter<Nat>(init.vals());
+        case ("mutable Queue", "Initialize with 2 elements") mutQ := MutQueue.fromIter<Nat>(init.vals());
+        case ("pure/RealTimeQueue", "Push 500 elements") {
+          for (i in toPush.vals()) {
+            newQ := NewQueue.pushBack<Nat>(newQ, i)
+          }
+        };
+        case ("pure/Queue", "Push 500 elements") {
+          for (i in toPush.vals()) {
+            oldQ := OldQueue.pushBack<Nat>(oldQ, i)
+          }
+        };
+        case ("mutable Queue", "Push 500 elements") {
+          for (i in toPush.vals()) {
+            MutQueue.pushBack<Nat>(mutQ, i)
+          }
+        };
+        case ("pure/RealTimeQueue", "Pop front 2 elements") Option.unwrap(
+          do ? {
+            newQ := NewQueue.popFront<Nat>(NewQueue.popFront<Nat>(newQ)!.1)!.1
+          }
+        );
+        case ("pure/Queue", "Pop front 2 elements") Option.unwrap(
+          do ? {
+            oldQ := OldQueue.popFront<Nat>(OldQueue.popFront<Nat>(oldQ)!.1)!.1
+          }
+        );
+        case ("mutable Queue", "Pop front 2 elements") Option.unwrap(
+          do ? {
+            ignore MutQueue.popFront<Nat>(mutQ);
+            ignore MutQueue.popFront<Nat>(mutQ)
+          }
+        );
+        case ("pure/RealTimeQueue", "Pop 150 front&back") {
+          for (i in Nat.range(0, 150)) Option.unwrap(
+            do ? {
+              newQ := NewQueue.popBack<Nat>(NewQueue.popFront<Nat>(newQ)!.1)!.0
+            }
+          )
+        };
+        case ("pure/Queue", "Pop 150 front&back") {
+          for (i in Nat.range(0, 150)) Option.unwrap(
+            do ? {
+              oldQ := OldQueue.popBack<Nat>(OldQueue.popFront<Nat>(oldQ)!.1)!.0
+            }
+          )
+        };
+        case ("mutable Queue", "Pop 150 front&back") {
+          for (i in Nat.range(0, 150)) {
+            ignore MutQueue.popFront<Nat>(mutQ);
+            ignore MutQueue.popBack<Nat>(mutQ)
+          }
+        };
+        case _ Runtime.unreachable()
+      }
+    );
+
+    bench
+  }
+}

log

@@ -0,0 +1,63 @@
+
+> @dfinity/[email protected] bench
+> mops bench Queues
+
+Benchmark files:
+• bench/Queues.bench.mo
+
+==================================================
+
+Starting dfx replica...
+Deploying canisters...
+
+--------------------------------------------------
+
+Running bench/Queues.bench.mo...
+
+
+
+Different queue implementations
+
+Compare the performance of the following queue implementations_:
+- `pure/Queue`: The default immutable double-ended queue implementation.
+  * Pros: Good amortized performance, meaning that the average cost of operations is low `O(1)`.
+  * Cons: In worst case, an operation can take `O(size)` time rebuilding the queue as demonstrated in the `Pop front 2 elements` scenario.
+- `pure/RealTimeQueue`
+  * Pros: Every operation is guaranteed to take at most `O(1)` time and space.
+  * Cons: Poor amortized performance: Instruction cost is on average 4x for *pop* and 10x for *push* compared to `pure/Queue`.
+- mutable `Queue`
+  * Pros: Also `O(1)` guarantees with a lower constant factor than `pure/RealTimeQueue`. Amortized performance is comparable to `pure/Queue`.
+  * Cons: It is mutable and cannot be used in `shared` types (not shareable)_.
+
+
+Instructions
+
+|                            | pure/Queue | pure/RealTimeQueue | mutable Queue |
+| :------------------------- | ---------: | -----------------: | ------------: |
+| Initialize with 2 elements |      3_571 |              2_934 |         3_401 |
+| Push 500 elements          |    103_492 |            966_398 |       243_585 |
+| Pop front 2 elements       |     98_792 |              5_009 |         4_326 |
+| Pop 150 front&back         |    106_545 |            394_667 |       140_211 |
+
+
+Heap
+
+|                            | pure/Queue | pure/RealTimeQueue | mutable Queue |
+| :------------------------- | ---------: | -----------------: | ------------: |
+| Initialize with 2 elements |      324 B |              300 B |         352 B |
+| Push 500 elements          |   8.08 KiB |           8.17 KiB |      19.8 KiB |
+| Pop front 2 elements       |      240 B |              240 B |         192 B |
+| Pop 150 front&back         |  -4.42 KiB |             -492 B |    -11.45 KiB |
+
+
+Garbage Collection
+
+|                            | pure/Queue | pure/RealTimeQueue | mutable Queue |
+| :------------------------- | ---------: | -----------------: | ------------: |
+| Initialize with 2 elements |      508 B |              472 B |         456 B |
+| Push 500 elements          |   10.1 KiB |         166.63 KiB |         344 B |
+| Pop front 2 elements       |  12.19 KiB |              528 B |         424 B |
+| Pop 150 front&back         |  15.61 KiB |          60.38 KiB |      12.1 KiB |
+
+
+Stopping replica...

src/pure/Queue.mo

@@ -20,6 +20,10 @@
 ///
 /// `n` denotes the number of elements stored in the queue.
 ///
+/// Note that some operations that traverse the elements of the queue (e.g. `forEach`, `values`) preserve the order of the elements,
+/// whereas others (e.g. `map`, `contains`) do NOT guarantee that the elements are visited in any order.
+/// The order is undefined to avoid allocations, making these operations more efficient.
+///
 /// ```motoko name=import
 /// import Queue "mo:base/pure/Queue";
 /// ```
@@ -115,9 +119,9 @@ module {
   /// }
   /// ```
   ///
-  /// Runtime: O(size)
+  /// Runtime: `O(size)`
   ///
-  /// Space: O(1)
+  /// Space: `O(1)`
   public func contains<T>(queue : Queue<T>, equal : (T, T) -> Bool, item : T) : Bool = List.contains(queue.0, equal, item) or List.contains(queue.2, equal, item);
 
   /// Inspect the optional element on the front end of a queue.
@@ -370,11 +374,11 @@ module {
   /// }
   /// ```
   ///
-  /// Runtime: O(size)
+  /// Runtime: `O(size)`
   ///
-  /// Space: O(size) as the current implementation uses `values` to iterate over the queue.
+  /// Space: `O(size)` as the current implementation uses `values` to iterate over the queue.
   ///
-  /// *Runtime and space assumes that `f` runs in O(1) time and space.
+  /// *Runtime and space assumes that the `predicate` runs in `O(1)` time and space.
   public func all<T>(queue : Queue<T>, predicate : T -> Bool) : Bool {
     for (item in values queue) if (not (predicate item)) return false;
     return true
@@ -392,11 +396,11 @@ module {
   /// }
   /// ```
   ///
-  /// Runtime: O(size)
+  /// Runtime: `O(size)`
   ///
-  /// Space: O(size) as the current implementation uses `values` to iterate over the queue.
+  /// Space: `O(size)` as the current implementation uses `values` to iterate over the queue.
   ///
-  /// *Runtime and space assumes that `f` runs in O(1) time and space.
+  /// *Runtime and space assumes that the `predicate` runs in `O(1)` time and space.
   public func any<T>(queue : Queue<T>, predicate : T -> Bool) : Bool {
     for (item in values queue) if (predicate item) return true;
     return false
@@ -415,17 +419,18 @@ module {
   /// }
   /// ```
   ///
-  /// Runtime: O(size)
+  /// Runtime: `O(size)`
   ///
-  /// Space: O(size)
+  /// Space: `O(size)`
   ///
-  /// *Runtime and space assumes that `f` runs in O(1) time and space.
+  /// *Runtime and space assumes that `f` runs in `O(1)` time and space.
   public func forEach<T>(queue : Queue<T>, f : T -> ()) = for (item in values queue) f item;
 
   /// Call the given function `f` on each queue element and collect the results
   /// in a new queue.
   ///
   /// Note: The order of visiting elements is undefined with the current implementation.
+  ///
   /// Example:
   /// ```motoko include=import
   /// import Iter "mo:base/Iter";
@@ -438,10 +443,11 @@ module {
   /// }
   /// ```
   ///
-  /// Runtime: O(size)
+  /// Runtime: `O(size)`
   ///
-  /// Space: O(size)
-  /// *Runtime and space assumes that `f` runs in O(1) time and space.
+  /// Space: `O(size)`
+  ///
+  /// *Runtime and space assumes that `f` runs in `O(1)` time and space.
   public func map<T1, T2>(queue : Queue<T1>, f : T1 -> T2) : Queue<T2> {
     let (fr, n, b) = queue;
     (List.map(fr, f), n, List.map(b, f))
@@ -461,13 +467,15 @@ module {
   /// }
   /// ```
   ///
-  /// Runtime: O(size)
+  /// Runtime: `O(size)`
   ///
-  /// Space: O(size)
-  public func filter<T>(queue : Queue<T>, f : T -> Bool) : Queue<T> {
+  /// Space: `O(size)`
+  ///
+  /// *Runtime and space assumes that `predicate` runs in `O(1)` time and space.
+  public func filter<T>(queue : Queue<T>, predicate : T -> Bool) : Queue<T> {
     let (fr, _, b) = queue;
-    let front = List.filter(fr, f);
-    let back = List.filter(b, f);
+    let front = List.filter(fr, predicate);
+    let back = List.filter(b, predicate);
     check(front, List.size front + List.size back, back)
   };
 
@@ -488,11 +496,11 @@ module {
   /// }
   /// ```
   ///
-  /// Runtime: O(size)
+  /// Runtime: `O(size)`
   ///
-  /// Space: O(size)
+  /// Space: `O(size)`
   ///
-  /// *Runtime and space assumes that `f` runs in O(1) time and space.
+  /// *Runtime and space assumes that `f` runs in `O(1)` time and space.
   public func filterMap<T, U>(queue : Queue<T>, f : T -> ?U) : Queue<U> {
     let (fr, _n, b) = queue;
     let front = List.filterMap(fr, f);
@@ -513,9 +521,9 @@ module {
   /// }
   /// ```
   ///
-  /// Runtime: O(size)
+  /// Runtime: `O(size)`
   ///
-  /// Space: O(size)
+  /// Space: `O(size)`
   public func toText<T>(queue : Queue<T>, f : T -> Text) : Text {
     var text = "PureQueue[";
     func add(item : T) {
@@ -540,11 +548,11 @@ module {
   /// }
   /// ```
   ///
-  /// Runtime: O(size)
+  /// Runtime: `O(size)`
   ///
-  /// Space: O(size)
+  /// Space: `O(size)`
   ///
-  /// *Runtime and space assumes that argument `compare` runs in O(1) time and space.
+  /// *Runtime and space assumes that argument `compareItem` runs in `O(1)` time and space.
   public func compare<T>(queue1 : Queue<T>, queue2 : Queue<T>, compareItem : (T, T) -> Order.Order) : Order.Order {
     let (i1, i2) = (values queue1, values queue2);
     loop switch (i1.next(), i2.next()) {
@@ -556,6 +564,23 @@ module {
       case (null, _) return #less;
       case (_, null) return #greater
     }
-  }
+  };
 
+  /// Reverse the order of elements in a queue.
+  /// This operation is cheap, it does NOT require copying the elements.
+  ///
+  /// Example:
+  /// ```motoko include=import
+  /// persistent actor {
+  ///   let queue = Queue.fromIter([1, 2, 3].values());
+  ///   let reversed = Queue.reverse(queue);
+  ///   assert Queue.peekFront(reversed) == ?3;
+  ///   assert Queue.peekBack(reversed) == ?1;
+  /// }
+  /// ```
+  ///
+  /// Runtime: `O(1)`
+  ///
+  /// Space: `O(1)`
+  public func reverse<T>(queue : Queue<T>) : Queue<T> = (queue.2, queue.1, queue.0)
 }