Renamed rnd_qu/RndQueue => keequ/KeeQu

why:
  Something like key-queue reflects better what this data structure is
  for. KQueue would be the preferred name but is too general and used
  already in the NIM library.

nimbus/utils/tx_pool.nim

@@ -19,21 +19,21 @@
 
 import
   std/[algorithm, sequtils],
-  ./rnd_qu,
+  ./keequ,
   ./slst,
   ./tx_pool/[tx_item, tx_list, tx_queue],
   eth/[common, keys],
   stew/results
 
 export
   results,
-  rnd_qu,
-  slst,
+  keequ,
   TxItemRef,
   tx_item.id,
   tx_item.info,
   tx_item.local,
-  tx_item.timeStamp
+  tx_item.timeStamp,
+  tx_item.tx
 
 type
   TxInfo* = enum ##\
@@ -77,6 +77,7 @@ proc init*(xp: var TxPool) =
   xp.byGasPrice.txInit
 
 proc initTxPool*: TxPool =
+  ## Ditto
   result.init
 
 # ------------------------------------------------------------------------------
@@ -146,7 +147,7 @@ proc len*(rq: var TxItemList): int =
   ## Returns the number of items on the argument queue `rq` which is typically
   ## the result of an `SLstRef` type object query holding one or more
   ## duplicates relative to the same index.
-  rnd_qu.len(rq)
+  keequ.len(rq)
 
 proc byGasPriceLen*(xp: var TxPool): int =
   ## Number of different gas prices known. Fo each gas price there is at least
@@ -299,30 +300,42 @@ proc byGasPriceLt*(xp: var TxPool; gWei: GasInt): Result[TxItemList,void] =
   err()
 
 iterator byGasPriceIncPairs*(xp: var TxPool;
-                             gWei = GasInt.low): (GasInt,var TxItemList) =
+                             fromGe = GasInt.low): (GasInt,var TxItemList) =
   ## Starting at the lowest, this function traverses increasing gas prices.
   ##
   ## While the returned *list* of transaction containers *must not* be modified
   ## directly, a transaction entry within a container may well be altered.
   ##
-  ## Note: When running in a loop it is ok to add or delete any entries
-  ## vistied or not visited yet.
-  var rc = xp.byGasPrice.ge(gWei)
+  ## Note: When running in a loop it is ok to add or delete any entries,
+  ## visited or not visited yet. So, deleting all entries with gas prices
+  ## greater or equal than `delMin` would look like:
+  ## ::
+  ##  for _, txList in xp.byGasPriceIncPairs(fromGe = delMin):
+  ##    for tx in txList.nextKeys:
+  ##      discard xq.delete(tx)
+  ##
+  var rc = xp.byGasPrice.ge(fromGe)
   while rc.isOk:
     let yKey = rc.value.key
     yield (ykey, rc.value.data)
     rc = xp.byGasPrice.gt(ykey)
 
 iterator byGasPriceDecPairs*(xp: var TxPool;
-                             gWei = GasInt.high): (GasInt,var TxItemList) =
+                             fromLe = GasInt.high): (GasInt,var TxItemList) =
   ## Starting at the highest, this function traverses decreasing gas prices.
   ##
   ## While the returned *list* of transaction containers *must not* be modified
   ## directly, a transaction entry within a container may well be altered.
   ##
-  ## Note: When running in a loop it is ok to add or delete any entries
-  ## vistied or not visited yet.
-  var rc = xp.byGasPrice.le(gWei)
+  ## Note: When running in a loop it is ok to add or delete any entries,
+  ## vistied or not visited yet. So, deleting all entries with gas prices
+  ## less or equal than `delMax` would look like:
+  ## ::
+  ##  for _, txList in xp.byGasPriceDecPairs(fromLe = delMax):
+  ##    for tx in txList.nextKeys:
+  ##      discard xq.delete(tx)
+  ##
+  var rc = xp.byGasPrice.le(fromLe)
   while rc.isOk:
     let yKey = rc.value.key
     yield (yKey, rc.value.data)

nimbus/utils/tx_pool/tx_item.nim

@@ -18,12 +18,13 @@ import
 
 type
   TxItemRef* = ref object of RootObj ##\
-    ## Data container with transaction and meta data.
-    tx*: Transaction ## Transaction, can freely be modified
-    id: Hash256      ## Identifier/transaction key, read-only
-    timeStamp: Time  ## Time when added, read-only
-    info: string     ## Whatever, read-only
-    local: bool      ## Local or remote queue, read-only (setter available)
+    ## Data container with transaction and meta data. Entries are *read-only*\
+    ## by default, for some there is a setter available.
+    tx: Transaction  ## Transaction
+    id: Hash256      ## Identifier/transaction key
+    timeStamp: Time  ## Time when added
+    info: string     ## Whatever
+    local: bool      ## Local or remote queue (setter available)
 
 # ------------------------------------------------------------------------------
 # Private, helpers for debugging and pretty printing
@@ -95,6 +96,10 @@ proc id*(item: TxItemRef): Hash256 {.inline.} =
   ## Getter
   item.id
 
+proc tx*(item: TxItemRef): Transaction {.inline.} =
+  ## Getter
+  item.tx
+
 proc timeStamp*(item: TxItemRef): Time {.inline.} =
   ## Getter
   item.timeStamp
@@ -147,7 +152,6 @@ proc pp*(tx: Transaction): string =
   result &= ",VRS=" & tx.V.toXX(tx.R,tx.S)
   result &= ")"
 
-
 proc pp*(w: TxItemRef): string =
   ## Pretty print item (use for debugging)
   let s = w.tx.pp

nimbus/utils/tx_pool/tx_list.nim

@@ -17,7 +17,7 @@
 
 import
   std/[hashes],
-  ../rnd_qu,
+  ../keequ,
   ../slst,
   ./tx_item,
   eth/common,
@@ -32,7 +32,7 @@ type
   TxItemList* = ##\
     ## Chronologically ordered queue/fifo with random access. This is\
     ## typically used when queuing items for the same key (e.g. gas price.)
-    RndQueue[TxItemRef,TxMark]
+    KeeQu[TxItemRef,TxMark]
 
   TxGasItemLst* = ##\
     ## Generic item list indexed by gas price

nimbus/utils/tx_pool/tx_queue.nim

@@ -17,7 +17,7 @@
 
 import
   std/[tables],
-  ../rnd_qu,
+  ../keequ,
   ./tx_item,
   eth/common,
   stew/results
@@ -30,11 +30,11 @@ type
 
   TxQueuePair* = ##\
     ## Queue handler wrapper, needed in `first()`, `next()`, etc.
-    RndQueuePair[Hash256,TxItemRef]
+    KeeQuPair[Hash256,TxItemRef]
 
   TxQueue* = object ##\
     ## Chronological queue and ID table, fifo
-    q: array[TxQueueSchedule, RndQueue[Hash256,TxItemRef]]
+    q: array[TxQueueSchedule, KeeQu[Hash256,TxItemRef]]
 
 {.push raises: [Defect].}
 
@@ -68,7 +68,7 @@ proc txDelete*(ap: var TxQueue;
     return ok(rc.value.data)
   err()
 
-proc txVerify*(aq: var TxQueue): Result[void,RndQueueInfo]
+proc txVerify*(aq: var TxQueue): Result[void,KeeQuInfo]
     {.gcsafe,raises: [Defect,KeyError].} =
   for sched in TxQueueSchedule:
     let rc = aq.q[sched].verify

tests/all_tests.nim

@@ -38,6 +38,6 @@ cliBuilder:
           ./test_graphql,
           ./test_lru_cache,
           ./test_clique,
-          ./test_rndqu,
+          ./test_keequ,
           ./test_slst,
           ./test_txpool

tests/test_rndqu.nim → tests/test_keequ.nim

@@ -10,7 +10,7 @@
 
 import
   std/[algorithm, sequtils, strformat, strutils, tables],
-  ../nimbus/utils/rnd_qu,
+  ../nimbus/utils/keequ,
   eth/rlp,
   unittest2
 
@@ -30,10 +30,10 @@ const
 # Helpers
 # ------------------------------------------------------------------------------
 
-proc `$`(rc: RndQueuePair[uint,uint]): string =
+proc `$`(rc: KeeQuPair[uint,uint]): string =
   "(" & $rc.key & "," & $rc.data & ")"
 
-proc `$`(rc: Result[RndQueuePair[uint,uint],void]): string =
+proc `$`(rc: Result[KeeQuPair[uint,uint],void]): string =
   result = "<"
   if rc.isOK:
     result &= $rc.value.key & "," & $rc.value.data
@@ -57,15 +57,15 @@ proc toKey(n: int): uint =
 proc fromKey(n: uint): int =
   n.int
 
-proc toQueue(a: openArray[int]): RndQueue[uint,uint] =
+proc toQueue(a: openArray[int]): KeeQu[uint,uint] =
   for n in a:
     result[n.toKey] = n.toValue
 
 proc toUnique(a: openArray[int]): seq[uint] =
   var q = a.toQueue
   toSeq(q.nextKeys)
 
-proc addOrFlushGroupwise(rq: var RndQueue[uint,uint];
+proc addOrFlushGroupwise(rq: var KeeQu[uint,uint];
                          grpLen: int; seen: var seq[int]; n: int;
                          noisy = true) =
   seen.add n
@@ -85,7 +85,7 @@ proc addOrFlushGroupwise(rq: var RndQueue[uint,uint];
 # Test Runners
 # ------------------------------------------------------------------------------
 
-proc runRndQueue(noisy = true) =
+proc runKeeQu(noisy = true) =
   let
     uniqueKeys = keyList.toUnique
     numUniqeKeys = keyList.toSeq.mapIt((it,false)).toTable.len
@@ -94,20 +94,20 @@ proc runRndQueue(noisy = true) =
   suite "Data queue with keyed random access":
     block:
       var
-        fwdRq, revRq: RndQueue[uint,uint]
+        fwdRq, revRq: KeeQu[uint,uint]
         fwdRej, revRej: seq[int]
 
       test &"Append/traverse {keyList.len} items, " &
           &"rejecting {numKeyDups} duplicates":
         var
-          rq: RndQueue[uint,uint]
+          rq: KeeQu[uint,uint]
           rej: seq[int]
         for n in keyList:
           if not rq.push(n.toKey, n.toValue): # synonymous for append()
             rej.add n
           let check = rq.verify
           if check.isErr:
-            check check.error[2] == rndQuOk
+            check check.error[2] == keeQuOk
         check rq.len == numUniqeKeys
         check rej.len == numKeyDups
         check rq.len + rej.len == keyList.len
@@ -121,14 +121,14 @@ proc runRndQueue(noisy = true) =
       test &"Prepend/traverse {keyList.len} items, " &
           &"rejecting {numKeyDups} duplicates":
         var
-          rq: RndQueue[uint,uint]
+          rq: KeeQu[uint,uint]
           rej: seq[int]
         for n in keyList:
           if not rq.unshift(n.toKey, n.toValue): # synonymous for prepend()
             rej.add n
           let check = rq.verify
           if check.isErr:
-            check check.error[2] == rndQuOk
+            check check.error[2] == keeQuOk
         check rq.len == numUniqeKeys
         check rej.len == numKeyDups
         check rq.len + rej.len == keyList.len
@@ -181,10 +181,10 @@ proc runRndQueue(noisy = true) =
             seen.add key.fromKey
 
           if fwdRqCheck.isErr:
-            check fwdRqCheck.error[2] == rndQuOk
+            check fwdRqCheck.error[2] == keeQuOk
           check fwdData.isOk == canDeleteOk
           if revRqCheck.isErr:
-            check revRqCheck.error[2] == rndQuOk
+            check revRqCheck.error[2] == keeQuOk
           check revData.isOk == canDeleteOk
 
           if canDeleteOk:
@@ -428,12 +428,12 @@ proc runRndQueue(noisy = true) =
 # Main function(s)
 # ------------------------------------------------------------------------------
 
-proc rndQuMain*(noisy = defined(debug)) =
-  noisy.runRndQueue
+proc keeQuMain*(noisy = defined(debug)) =
+  noisy.runKeeQu
 
 when isMainModule:
   let noisy = defined(debug)
-  noisy.runRndQueue
+  noisy.runKeeQu
 
 # ------------------------------------------------------------------------------
 # End

tests/test_txpool.nim

@@ -208,7 +208,7 @@ proc runTxStepper(noisy = true;
       test &"Load/delete with gas price less equal {delMax.toKMG}, " &
           &"out of price range {gasPrices[0].toKMG}..{gasPrices[^1].toKMG}":
         noisy.showElapsed(&"Deleting gas prices less equal {delMax.toKMG}"):
-          for (gp,itemList) in xq.byGasPriceDecPairs(delMax):
+          for (gp,itemList) in xq.byGasPriceDecPairs(fromLe = delMax):
             for item in itemList.nextKeys:
               count.inc
               check xq.delete(item).isOK
@@ -230,7 +230,7 @@ proc runTxStepper(noisy = true;
       test &"Load/delete with gas price greater equal {delMin.toKMG}, " &
           &"out of price range {gasPrices[0].toKMG}..{gasPrices[^1].toKMG}":
         noisy.showElapsed(&"Deleting gas prices greater than {delMin.toKMG}"):
-          for (gp,itemList) in xq.byGasPriceIncPairs(delMin):
+          for gp, itemList in xq.byGasPriceIncPairs(fromGe = delMin):
             for item in itemList.nextKeys:
               count.inc
               check xq.delete(item).isOK