[mq] [mod] Deprecate clear-queues, rename -> queues-clear!!

New name better matches the rest of the API

src/taoensso/carmine/message_queue.clj

@@ -80,8 +80,11 @@
 
 (comment (queue-names {}))
 
-(defn clear-queues
-  "Deletes ALL content for the Carmine message queues with given names."
+(defn queues-clear!!
+  "Permanently deletes ALL content for the Carmine message queues with
+  given names.
+
+  Returns nil, or a non-empty vector of the queue names that were cleared."
   {:arglists '([conn-opts qnames])}
   [conn-opts & more]
   (let [qnames ; Back compatibility
@@ -112,15 +115,16 @@
                   (qk :ndry-runs)
                   (qk :isleep-a)
                   (qk :isleep-b)))))
-          qnames)))))
+          qnames))
+      qnames)))
 
-(defn clear-all-queues
-  "Deletes ALL content for ALL Carmine message queues and returns a
-  non-empty vector of the queue names that were cleared, or nil."
+(defn queues-clear-all!!!
+  "**DANGER**!
+  Permanently deletes ALL content for *ALL* Carmine message queues.
+  Returns nil, or a non-empty vector of the queue names that were cleared."
   [conn-opts]
   (when-let [qnames (queue-names conn-opts "*")]
-    (clear-queues conn-opts qnames)
-    (do                     qnames)))
+    (queues-clear!! conn-opts qnames)))
 
 (defn- kvs->map [kvs]
   (if (empty? kvs)
@@ -427,7 +431,7 @@
        :eoq-bo5          bo5})))
 
 (comment
-  (clear-queues {} :q1)
+  (queues-clear!! {} :q1)
   (wcar {} (enqueue :q1 :msg1 :mid1))
   (wcar {} (message-status :q1 :mid1))
   (wcar {} (dequeue :q1 {})))
@@ -613,12 +617,20 @@
   clojure.lang.IFn
   (invoke [this cmd]
     (case cmd
-      :queue-size    (queue-size    conn-opts qname)
-      :queue-status  (queue-status  conn-opts qname)
-      :queue-content (queue-content conn-opts qname)
-      :queue-mids    (queue-mids    conn-opts qname) ; Undocumented
       :start         (start this)
       :stop          (stop  this)
+      :queue-size    (queue-size    conn-opts  qname)
+      :queue-status  (queue-status  conn-opts  qname)
+      :queue-content (queue-content conn-opts  qname)
+      :queue-mids    (queue-mids    conn-opts  qname) ; Undocumented
+      :queue-clear!!                                  ; Undocumented
+      (do
+        (queues-clear!! conn-opts [qname])
+        (tukey/summary-stats-clear! ssb-queue-size)
+        (tukey/summary-stats-clear! ssb-msg-age-ms)
+        (tukey/summary-stats-clear! ssb-handling-time-ns)
+        nil)
+
       (throw
         (ex-info "[Carmine/mq] Unexpected queue worker command"
           {:command {:value cmd :type (type cmd)}}))))
@@ -850,6 +862,8 @@
 ;;;; Deprecated
 
 (enc/deprecated
+  (enc/defalias clear-queues queues-clear!! {:deprecated "v3.3.0 (2022-12-21)"})
+
   (defn ^:deprecated make-dequeue-worker
     "DEPRECATED: Use `worker` instead."
     [pool spec & {:keys [handler-fn handler-ttl-msecs backoff-msecs throttle-msecs

test/taoensso/carmine/tests/message_queue.clj

@@ -30,7 +30,7 @@
 (defmacro wcar* [& body] `(car/wcar conn-opts ~@body))
 
 (def tq :carmine-test-queue)
-(defn clear-tq! [] (mq/clear-queues conn-opts [tq]))
+(defn clear-tq! [] (mq/queues-clear!! conn-opts [tq]))
 
 (defn test-fixture [f] (f) (clear-tq!))
 (test/use-fixtures :once test-fixture) ; Just for final teardown