[nop] Housekeeping

CHANGELOG.md

@@ -28,7 +28,7 @@ And as always **please report any unexpected problems** - thank you! 🙏
 
 ## New since `v3.3.2` (2023-10-24)
 
-* 8196415f [new] Update Redis command spec (2024-05-27)
+* 12c4100d [new] Update Redis command spec (2024-05-27)
 * Several wiki and docstring improvements
 
 ---

README.md

@@ -21,11 +21,11 @@ See [here][GitHub releases] for earlier releases.
 ## Why Carmine?
 
 - High-performance **pure-Clojure** library
-- [Fully documented API](#documentation) with support for the **latest Redis commands and features**
+- [Fully documented API](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine) with support for the **latest Redis commands and features**
 - Easy-to-use, production-ready **connection pooling**
 - Auto **de/serialization** of Clojure data types via [Nippy](https://www.taoensso.com/nippy)
-- Fast, simple **message queue** API
-- Fast, simple **distributed lock** API
+- Fast, simple [message queue](../../wiki/3-Message-queue) API
+- Fast, simple [distributed lock](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.locks) API
 
 ## Documentation
 

src/taoensso/carmine/connections.clj

@@ -1,6 +1,7 @@
 (ns taoensso.carmine.connections
-  "Handles socket connection lifecycle. Pool is implemented with Apache Commons
-  pool. Originally adapted from redis-clojure."
+  "Handles socket connection lifecycle.
+  Pool is implemented with Apache Commons pool.
+  Originally adapted from `redis-clojure`."
   {:author "Peter Taoussanis"}
   (:require
    [clojure.string            :as str]

src/taoensso/carmine/locks.clj

@@ -1,14 +1,15 @@
 (ns taoensso.carmine.locks
   "Alpha - subject to change.
-  Distributed lock implementation for Carmine based on work by Ronen Narkis
-  and Josiah Carlson. Redis 2.6+.
+  Distributed lock implementation for Carmine.
+  Based on work by Ronen Narkis and Josiah Carlson.
 
   Redis keys:
     * carmine:lock:<lock-name> -> ttl str, lock owner's UUID.
 
-  Ref. http://goo.gl/5UalQ for implementation details."
-  (:require [taoensso.timbre  :as timbre]
-            [taoensso.carmine :as car :refer (wcar)]))
+  Ref. <http://goo.gl/5UalQ> for implementation details."
+  (:require
+   [taoensso.timbre  :as timbre]
+   [taoensso.carmine :as car :refer (wcar)]))
 
 (def ^:private lkey (partial car/key :carmine :lock))
 

src/taoensso/carmine/message_queue.clj

@@ -85,7 +85,8 @@
       idx-qname-end     (- (count ":messages"))]
 
   (defn queue-names
-    "Returns a non-empty set of existing queue names, or nil."
+    "Returns a non-empty set of existing queue names, or nil.
+    Executes a Redis scan command, so O(n) of the number of keys in db."
     ([conn-opts        ] (queue-names conn-opts "*"))
     ([conn-opts pattern]
      (when-let [qks (not-empty (car/scan-keys conn-opts (qkey pattern :messages)))]
@@ -292,9 +293,9 @@
 ;;;; Implementation
 
 (do ; Lua scripts
-  (def lua-msg-status_ (delay (enc/have (enc/slurp-resource "taoensso/carmine/lua/mq/msg-status.lua"))))
-  (def lua-enqueue_    (delay (enc/have (enc/slurp-resource "taoensso/carmine/lua/mq/enqueue.lua"))))
-  (def lua-dequeue_    (delay (enc/have (enc/slurp-resource "taoensso/carmine/lua/mq/dequeue.lua")))))
+  (def ^:private lua-msg-status_ (delay (enc/have (enc/slurp-resource "taoensso/carmine/lua/mq/msg-status.lua"))))
+  (def ^:private lua-enqueue_    (delay (enc/have (enc/slurp-resource "taoensso/carmine/lua/mq/enqueue.lua"))))
+  (def ^:private lua-dequeue_    (delay (enc/have (enc/slurp-resource "taoensso/carmine/lua/mq/dequeue.lua")))))
 
 (defn message-status
   "Returns current message status, e/o:
@@ -607,7 +608,7 @@
 ;;;; Workers
 
 (defprotocol IWorker
-  "Implementation detail."
+  "Private, please don't use this."
   (^:no-doc start [this])
   (^:no-doc stop  [this]))
 
@@ -861,12 +862,11 @@
 
       Can be overridden on a per-message basis via `enqueue`.
 
-    `:throttle-ms` (default `:auto`)
+    `:throttle-ms` (default `default-throttle-ms-fn`)
       Thread sleep period (in milliseconds) between each poll.
-      Can be a (fn [queue-size]) -> ?sleep-msecs,
-      or `:auto` (to use `default-throttle-ms-fn`).
+      Can be a (fn [queue-size]) -> ?sleep-msecs.
 
-    `:eoq-backoff-ms` (default `exp-backoff` fn)
+    `:eoq-backoff-ms` (default `exp-backoff`)
       Max time (in milliseconds) to sleep thread each time end of queue is reached.
       Can be a (fn [ndry-runs]) -> msecs for n<=5.
       Sleep may be interrupted when new messages are enqueued.
@@ -886,7 +886,7 @@
       lock-ms (enc/ms :mins 60)
       nthreads-worker  1
       nthreads-handler 1
-      throttle-ms    :auto #_200
+      throttle-ms    default-throttle-ms-fn
       eoq-backoff-ms exp-backoff
       auto-start     true}}]
 
@@ -904,7 +904,7 @@
             :nthreads-worker  nthreads-worker
             :nthreads-handler nthreads-handler
             :throttle-ms
-            (if (identical? throttle-ms :auto)
+            (if (identical? throttle-ms :auto) ; Back compatibility
               default-throttle-ms-fn
               throttle-ms)})
 

src/taoensso/carmine/ring.clj

@@ -1,9 +1,10 @@
 (ns taoensso.carmine.ring
   "Carmine-backed Ring session store."
   {:author "Peter Taoussanis"}
-  (:require [ring.middleware.session]
-            [taoensso.encore  :as enc]
-            [taoensso.carmine :as car :refer (wcar)]))
+  (:require
+   [ring.middleware.session]
+   [taoensso.encore  :as enc]
+   [taoensso.carmine :as car :refer [wcar]]))
 
 (defrecord CarmineSessionStore [conn-opts prefix ttl-secs extend-on-read?]
   ring.middleware.session.store/SessionStore
@@ -24,21 +25,22 @@
       k)))
 
 (defn carmine-store
-  "Creates and returns a Carmine-backed Ring SessionStore.
+  "Creates and returns a Carmine-backed Ring `SessionStore`.
+
   Options include:
-    :expiration-secs - How long session data should persist after last
-                       write. nil => persist forever.
-    :extend-on-read? - If true, expiration will also be extended by
-                       session reads."
+    `:expiration-secs` - How long session data should persist after last
+                         write. nil => persist forever.
+    `:extend-on-read?` - If true, expiration will also be extended by
+                         session reads."
   [conn-opts & [{:keys [key-prefix expiration-secs extend-on-read?]
                  :or   {key-prefix      "carmine:session"
                         expiration-secs (enc/secs :days 30)
                         extend-on-read? false}}]]
   (->CarmineSessionStore conn-opts key-prefix expiration-secs extend-on-read?))
 
 (enc/deprecated
-  (defn ^:deprecated make-carmine-store ; 1.x backwards compatiblity
-    "DEPRECATED. Use `carmine-store` instead."
+  (defn ^:no-doc ^:deprecated make-carmine-store ; 1.x backwards compatiblity
+    "Prefer `carmine-store`."
     [& [s1 s2 & sn :as args]]
     (if (instance? taoensso.carmine.connections.ConnectionPool s1)
       (carmine-store {:pool s1 :spec s2} (apply hash-map sn))

wiki/0-Breaking-changes.md

@@ -8,7 +8,7 @@ Thanks for your understanding - [Peter Taoussanis](https://www.taoensso.com)
 
 There are **breaking changes** to the **Carmine message queue API** that **may affect** a small proportion of message queue users.
 
-- If you **DO NOT** use Carmine's [message queue API](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html), no migration should be necessary.
+- If you **DO NOT** use Carmine's [message queue API](https://github.com/taoensso/carmine/wiki/3-Message-queue), no migration should be necessary.
 - If you **DO** use Carmine's message queue API, **please read the below checklist carefully**!!
 
 ## Migration checklist for message queue users
@@ -29,9 +29,9 @@ There are **breaking changes** to the **Carmine message queue API** that **may a
 
    The fn now **always returns a map** with `{:keys [success? mid action error]}`.
 
-   See the updated `enqueue` [docstring](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-enqueue) for details.
+   See the updated `enqueue` [docstring](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#enqueue) for details.
 
-3. [`queue-status`](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-queue-status) **return value has changed**.
+3. [`queue-status`](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#queue-status) **return value has changed**.
 
    This change is relevant to you iff you use the `queue-status` util.
 
@@ -40,7 +40,7 @@ There are **breaking changes** to the **Carmine message queue API** that **may a
    The fn now returns a small map in O(1) with `{:keys [nwaiting nlocked nbackoff ntotal]}`.
 
    If you want the detailed map of all queue content in O(queue-size),
-   use the new [`queue-content`](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-queue-content) util.
+   use the new [`queue-content`](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#queue-content) util.
 
 4. **The definition of "queue-size" has changed**.
 
@@ -51,9 +51,9 @@ There are **breaking changes** to the **Carmine message queue API** that **may a
 
    Most users won't be negatively affected by this change since the new definition better corresponds to how most users actually understood the term before.
 
-5. [`clear-queues`](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-clear-queues) **has been deprecated**.
+5. `clear-queues` **has been deprecated**.
 
-   This utility is now called [`queues-clear!!`](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-queues-clear.21.21) to better match the rest of the API.
+   This utility is now called [`queues-clear!!`](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#queues-clear!!) to better match the rest of the API.
 
 6. **Handling order of queued messages has changed**.
 
@@ -75,7 +75,7 @@ There are **breaking changes** to the **Carmine message queue API** that **may a
 
   The default `:throttle-ms` value is now `:auto`, which uses such a function.
 
-  See the updated `worker` [docstring](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-worker) for details.
+  See the updated `worker` [docstring](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#worker) for details.
 
 - **Worker threads are now auto desynchronized** to reduce contention.
 
@@ -85,15 +85,15 @@ There are **breaking changes** to the **Carmine message queue API** that **may a
 - Added `enqueue` option: `:can-update?` to support **message updating**.
 - Handler fn data now includes `:worker`, `:queue-size` keys.
 - Handler fn data now includes `:age-ms` key, enabling **easy integration with Tufte or other profiling tools**.
-- Added utils: [`queue-size`](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-queue-size), [`queue-names`](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-queue-names), [`queue-content`](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-queue-content), [`queues-clear!!`](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-queues-clear.21.21), [`queues-clear-all!!!`](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-queues-clear-all.21.21.21).
+- Added utils: [`queue-size`](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#queue-size), [`queue-names`](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#queue-names), [`queue-content`](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#queue-content), [`queues-clear!!`](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#queues-clear!!), [`queues-clear-all!!!`](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#queues-clear-all!!!).
 - `Worker` object's string/pprint representation is now more useful.
 - `Worker` object can now be derefed to get **state and stats useful for monitoring**.
 
   In particular, the new `:stats` key contains **detailed statistics on queue size, queueing time, handling time, etc**.
 
 - `Worker` objects can now be invoked as fns to execute common actions.
 
-  Actions [include](https://taoensso.github.io/carmine/taoensso.carmine.message-queue.html#var-worker): `:start`, `:stop`, `:queue-size`, `:queue-status`.
+  Actions [include](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine.message-queue#worker): `:start`, `:stop`, `:queue-size`, `:queue-status`.
 
 - Various improvements to docstrings, error messages, and logging output.
 - Improved message queue [state diagram](https://github.com/taoensso/carmine/blob/master/mq-architecture.svg).

wiki/1-Getting-started.md

@@ -31,7 +31,7 @@ This `my-wcar-opts` can then be provided to Carmine's `wcar` ("with Carmine") AP
 (wcar my-wcar-opts (car/ping)) ; => "PONG"
 ```
 
-`wcar` is the main entry-point to Carmine's API. See its [docstring](https://taoensso.github.io/carmine/taoensso.carmine.html#var-wcar) for **lots more info** on connection options!
+`wcar` is the main entry-point to Carmine's API. See its [docstring](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine#wcar) for **lots more info** on connection options!
 
 You can create a `wcar` partial for convenience:
 
@@ -106,7 +106,7 @@ Keywords | Redis strings
 Simple numbers | Redis strings
 Everything else | Auto de/serialized with [Nippy](https://www.taoensso.com/nippy)
 
-You can force automatic de/serialization for an argument of any type by wrapping it with [`car/freeze`](https://taoensso.github.io/carmine/taoensso.carmine.html#var-freeze).
+You can force automatic de/serialization for an argument of any type by wrapping it with [`car/freeze`](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine#freeze).
 
 ## Command coverage
 
@@ -127,7 +127,7 @@ Time complexity: O(N+M*log(M)) where N is the number of elements in the list or
 
 Each Carmine release will always use the latest Redis command spec.
 
-But if a new Redis command hasn't yet made it to Carmine, or if you want to use a Redis command not in the official spec (a [Redis module](https://redis.io/resources/modules/) command for example) - you can always use Carmine's [`redis-call`](https://taoensso.github.io/carmine/taoensso.carmine.html#var-redis-call) function to issue **arbitrary Redis commands**.
+But if a new Redis command hasn't yet made it to Carmine, or if you want to use a Redis command not in the official spec (a [Redis module](https://redis.io/resources/modules/) command for example) - you can always use Carmine's [`redis-call`](https://cljdoc.org/d/com.taoensso/carmine/CURRENT/api/taoensso.carmine#redis-call) function to issue **arbitrary Redis commands**.
 
 So you're **not constrained** by the commands provided by Carmine.