added taps for debugging

src/main/java/com/github/jlangch/venice/impl/docgen/cheatsheet/DocGenerator.java

@@ -99,6 +99,7 @@
 import com.github.jlangch.venice.impl.docgen.cheatsheet.section.SpecialFormsSection;
 import com.github.jlangch.venice.impl.docgen.cheatsheet.section.SystemSection;
 import com.github.jlangch.venice.impl.docgen.cheatsheet.section.SystemVarSection;
+import com.github.jlangch.venice.impl.docgen.cheatsheet.section.TapSection;
 import com.github.jlangch.venice.impl.docgen.cheatsheet.section.TimeSection;
 import com.github.jlangch.venice.impl.docgen.cheatsheet.section.TransducersSection;
 import com.github.jlangch.venice.impl.docgen.cheatsheet.section.TypesSection;
@@ -309,6 +310,7 @@ private List<DocSection> getTOC() {
         system.addSection(new DocSection("REPL", "repl"));
         system.addSection(new DocSection("Sandbox", "sandbox"));
         system.addSection(new DocSection("Load\u00A0Paths", "loadpaths"));
+        system.addSection(new DocSection("Tap", "tap"));
         content.add(system);
 
         final DocSection util = new DocSection("Util", "util");
@@ -442,6 +444,7 @@ private List<DocSection> getRightSections() {
                 new ConcurrencySection(diBuilder).section(),
                 new SystemSection(diBuilder).section(),
                 new SystemVarSection(diBuilder).section(),
+                new TapSection(diBuilder).section(),
                 new TimeSection(diBuilder).section(),
                 new IoSection(diBuilder).section(),
                 new IoFileSection(diBuilder).section(),

src/main/java/com/github/jlangch/venice/impl/docgen/cheatsheet/section/TapSection.java

@@ -0,0 +1,63 @@
+/*   __    __         _
+ *   \ \  / /__ _ __ (_) ___ ___
+ *    \ \/ / _ \ '_ \| |/ __/ _ \
+ *     \  /  __/ | | | | (_|  __/
+ *      \/ \___|_| |_|_|\___\___|
+ *
+ *
+ * Copyright 2017-2024 Venice
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.github.jlangch.venice.impl.docgen.cheatsheet.section;
+
+import com.github.jlangch.venice.impl.docgen.cheatsheet.DocItemBuilder;
+import com.github.jlangch.venice.impl.docgen.cheatsheet.DocSection;
+import com.github.jlangch.venice.impl.docgen.cheatsheet.ISectionBuilder;
+
+
+public class TapSection implements ISectionBuilder {
+
+    public TapSection(final DocItemBuilder diBuilder) {
+        this.diBuilder = diBuilder;
+    }
+
+    @Override
+    public DocSection section() {
+        final DocSection section = new DocSection("Tap", "tap");
+
+        final DocSection all = new DocSection("", id());
+        section.addSection(all);
+
+        final DocSection use = new DocSection("Use", "tap.use");
+        all.addSection(use);
+        use.addItem(diBuilder.getDocItem("tap>"));
+
+        final DocSection add = new DocSection("Add", "tap.add");
+        all.addSection(add);
+        add.addItem(diBuilder.getDocItem("add-tap"));
+
+        final DocSection remove = new DocSection("Remove", "tap.remove");
+        all.addSection(remove);
+        remove.addItem(diBuilder.getDocItem("remove-tap"));
+        remove.addItem(diBuilder.getDocItem("clear-taps"));
+
+        return section;
+    }
+
+    private String id() {
+        return diBuilder.id();
+    }
+
+    private final DocItemBuilder diBuilder;
+}

src/main/resources/com/github/jlangch/venice/core.venice

@@ -1990,9 +1990,119 @@
 
 
 
-  ;; ---------------------------------------------------------------------------
-  ;; registered service  (service registry)
-  ;; ---------------------------------------------------------------------------
+;; ---------------------------------------------------------------------------
+;; taps
+;; ---------------------------------------------------------------------------
+
+(defonce ^:private tapset (atom #{}))
+(defonce ^:private tapq (queue 1024))
+
+(defonce ^:private tap-loop
+  (delay (thread
+            #(let [t    (take! tapq)
+                   taps @tapset]
+              (doseq [tap taps]
+                (try
+                  (tap t)
+                  (catch Throwable ex)))
+              (recur))
+            "venice-tap-loop")))
+
+(defn 
+  ^{ :arglists '("(add-tap f)")
+     :doc """
+          adds f, a fn of one argument, to the tap set. This function will be 
+          called with anything sent via `tap>`.
+
+          This function may (briefly) block, and will never impede calls to 
+          `tap>`, but blocking indefinitely may cause tap values to be dropped.
+
+          Remember f in order to `remove-tap`
+          """
+     :examples '(
+          """
+          (add-tap println)
+          """)
+     :see-also '(
+          "remove-tap"
+          "clear-taps"
+          "tap>") }
+
+  add-tap [f]
+    (assert (fn? f))
+    (force tap-loop)
+    (swap! tapset conj f)
+    nil)
+
+
+(defn 
+  ^{ :arglists '("(remove-tap f)")
+     :doc """
+          Remove f from the tap set.
+          """
+     :examples '(
+          """
+          (do
+            (add-tap prn)
+            (remove-tap prn))
+          """)
+     :see-also '(
+          "add-tap" 
+          "tap>") }
+
+ remove-tap [f]
+   (assert (fn? f))
+   (swap! tapset disj f)
+   nil)
+
+
+(defn 
+  ^{ :arglists '("(clear-taps)")
+     :doc """
+          Removes all tap sets.
+          """
+     :examples '(
+          """
+          (do
+            (add-tap prn)
+            (clear-taps))
+          """)
+     :see-also '(
+          "remove-tap"
+          "add-tap" 
+          "tap>") }
+
+ clear-taps []
+   (reset! tapset #{})
+   nil)
+
+
+(defn 
+  ^{ :arglists '("(tap> x)")
+     :doc """
+          Sends x to any taps. Will not block. Returns true if there was room 
+          in the queue, false if not (x is dropped).
+          """
+     :examples '(
+          """
+          (do
+            (add-tap prn)
+            (tap> {:foo "hello" :bar 34.5}))
+          """)
+     :see-also '(
+          "add-tap", 
+          "remove-tap", 
+          "clear-taps") }
+
+  tap> [x]
+    (force tap-loop)
+    (offer! tapq x))
+
+
+
+;; ---------------------------------------------------------------------------
+;; registered service  (service registry)
+;; ---------------------------------------------------------------------------
 
 (defn
   ^{ :arglists '(