[wip] Update main macros to use signal toolkit

Author: ptaoussanis

src/taoensso/tufte.cljc

@@ -90,8 +90,11 @@
 
 ;;;; Help
 
-(def help:signal-content       "TODO")
-(def help:environmental-config "TODO")
+(do
+  (impl/defhelp help:profiling-options    :profiling-options)
+  (impl/defhelp help:pstats-content       :pstats-content)
+  (impl/defhelp help:psignal-content      :psignal-content)
+  (impl/defhelp help:environmental-config :environmental-config))
 
 ;;;; Level filtering
 ;; Terminology note: we distinguish between call/form and min levels to ensure
@@ -226,15 +229,12 @@
 
 ;;;; Low-level primitives
 
-#?(:clj (defn- valid-opts!        [caller x] (if (map? x)            x (truss/ex-info! (str caller " opts must be a const (compile-time) map")              (enc/typed-val x)))))
-#?(:clj (defn- valid-opt:dynamic! [caller x] (if (enc/const-form? x) x (truss/ex-info! (str caller " `:dynamic?` opt must be a const (compile-time) value") (enc/typed-val x)))))
-
 (defn profiling? "Returns e/o #{nil :thread :dynamic}."
   [] (if impl/*pdata* :dynamic (when (impl/pdata-local-get) :thread)))
 
 (comment (enc/qb 1e6 (profiling?))) ; 43.91
 
-(def ^:const ^:private default-nmax (long 8e5))
+(def ^:const ^:no-doc default-nmax (long 8e5))
 (defn new-pdata
   "Low-level primitive for advanced users.
   Returns a new pdata object for use with `with-profiling` and/or `capture-time!`.
@@ -275,8 +275,8 @@
      macros.
 
      See `new-pdata` for more info on low-level primitives."
-     [pdata {:keys [dynamic?]} & body]
-     (valid-opt:dynamic! 'tufte/with-profiling dynamic?)
+     [pdata {:as opts, :keys [dynamic?]} & body]
+     (impl/valid-opts! &form &env 'tufte/with-profiling opts body)
      (if dynamic?
        `(binding [impl/*pdata* ~pdata] (do ~@body))
        `(binding [impl/*pdata*    nil] ; Ensure no dynamic parent (=>nesting) steals local captures
@@ -286,10 +286,9 @@
             (finally (impl/pdata-local-pop)))))))
 
 #?(:clj
-   (defmacro ^:private profiled*
+   (defmacro ^:no-doc profiled*
      "Unconditionally returns [<body-result> <pstats>]."
      [caller dynamic? nmax run-form]
-     (valid-opt:dynamic! caller dynamic?)
      (if dynamic?
        `(let [pd# (impl/new-pdata-dynamic (or ~nmax default-nmax))] (binding [impl/*pdata* pd#] [~run-form @pd#]))
        `(let [pd# (impl/new-pdata-local   (or ~nmax default-nmax))]
@@ -344,43 +343,35 @@
 
 #?(:clj
    (defmacro p
-     "Profiling spy.
-
-     Use this to wrap forms that should be timed during profiling:
-       - Always executes body and returns <body-result>.
-       - When profiling is active (via `profiled` or `profile`),
-         records body's execution time.
-
-     Options include:
-      `:id`    - Form id for this body in stats output (e.g. `::my-fn-call`)
-      `:level` - e/o #{0 1 2 3 4 5} ; Default is `5`"
-
-     {:arglists '([id & body] [opts & body])}
+     "Profiling spy, wraps forms that should be timed during profiling."
+     {:doc (impl/docstring :p)
+      :arglists '([id & body] [{:keys [id level]} & body])}
      [s1 & body]
-     (let [ns-str  (str *ns*)
-           opts    (if (map? s1) s1 {:level 5 :id s1})
-           level   (get opts :level)
-           id-form (get opts :id)
-           loc (or (get opts :loc) (dissoc (enc/get-source &form &env) :file))]
-
-       ;; If *any* level is present, it must be a valid compile-time level
+     (let [opts       (if (map? s1) s1 {:id s1})
+           level-form (get opts :level 5)
+           id-form    (get opts :id)
+           location
+           (enc/assoc-some nil
+             (or (get opts :loc) (dissoc (enc/get-source &form &env) :file)))]
+
+       ;; If level is present, it must be a valid compile-time level
        ;; since this macro doesn't offer runtime level checking
-       (when level (valid-call-level level))
+       (when level-form (sigs/valid-level level-form))
 
-       (when (nil? id-form)
-         (truss/ex-info! "`tufte/p` requires an id."
-           {:loc  loc
-            :opts opts
-            :form (cons 'p (cons s1 body))}))
+       (when (or (nil? id-form) (empty? body))
+         (truss/ex-info!
+           (str "`tufte/p` form needs an id at " (impl/location-str location) ": "
+             `(~'p s1 ~@body))))
 
-       (if (-elide? level ns-str)
+       (if-let [elide? (when-let [sf impl/ct-call-filter] (not (sf (:ns location) (enc/const-form id-form) (enc/const-form level-form))))]
          `(do ~@body)
+         ;; Note no `impl/*rt-call-filter*` check
          `(if-let [pd#     (or impl/*pdata* (impl/pdata-local-get))]
             (let  [t0#     (enc/now-nano*)
                    result# (do ~@body)
                    t1#     (enc/now-nano*)]
               ;; Note that capture cost is excluded from p time
-              (pd# ~id-form (- t1# t0#) ~loc)
+              (pd# ~id-form (- t1# t0#) ~location)
               result#)
             (do ~@body))))))
 
@@ -398,206 +389,75 @@
 
 (comment (valid-compile-time-opts 'sym 'sym))
 
+#?(:clj (defn- auto-> [form auto-form] (if (= form :auto) auto-form form)))
 #?(:clj
    (defmacro profiled
-     "Always executes body, and always returns [<body-result> <?pstats>].
-
-     When [ns level] unelided and [ns level `when`] unfiltered, executes body
-     with profiling active.
-
-     Handy if you'd like to consume stats output directly.
-     Otherwise see `profile`.
-
-     `pstats` objects are derefable and mergeable:
-       - @pstats                 => {:clock {:keys [t0 t1 total]}, :stats {<id> {:keys [n sum ...]}}}
-       - @(merge-pstats ps1 ps2) => {:clock {:keys [t0 t1 total]}, :stats {<id> {:keys [n sum ...]}}}
-
-     Full set of keys in above `:stats` maps:
-       :n :min :max :mean :mad :sum :p25 :p50 :p75 :p90 :p95 :p99 :loc :last
-
-       All values are numerical (longs or doubles), except for `:loc` which
-       is a map of `p` callsite location information, or set of such maps, e.g.:
-         {:ns \"my-ns\", :file \"/tmp/my-ns.clj\", :line 122, :column 21}
-
-     Compile-time opts:
-       `:dynamic?` - Use multi-threaded profiling? ; Default is `false`
-       `:nmax` ----- ~Max captures per id before compaction ; Default is 8e5
-
-     Runtime opts:
-       `:level` ---- e/o #{0 1 2 3 4 5} ; Default is `5`
-       `:when` ----- Optional arbitrary conditional form (e.g. boolean expr)
-
-     Laziness in body:
-       Lazy seqs and other forms of laziness (e.g. delays) in body will only
-       contribute to profiling results if/when EVALUATION ACTUALLY OCCURS.
-       This is intentional and a useful property. Compare:
-
-         (profiled {}  (delay (Thread/sleep 2000))) ; Doesn't count sleep
-         (profiled {} @(delay (Thread/sleep 2000))) ; Does    count sleep
-
-     Async code in body:
-       Execution time of any code in body that runs asynchronously on a
-       different thread will generally NOT be automatically captured by default.
-
-       `:dynamic?` can be used to support capture in cases where Clojure's
-       binding conveyance applies (e.g. futures, agents, pmap). Just make sure
-       that all work you want to capture has COMPLETED before the `profiled`
-       form ends- for example, by blocking on pending futures.
-
-       In other advanced cases (notably core.async `go` blocks), please see
-       `with-profiling` and `capture-time!`.
-
-     `core.async` warning:
-        `core.async` code can be difficult to profile correctly without a deep
-        understanding of precisely what it's doing under-the-covers.
-
-        Some general recommendations that can help keep things simple:
-
-          - Try minimize the amount of code + logic in `go` blocks. Use `go`
-            blocks for un/parking to get the data you need, then pass the data
-            to external fns. Profile these fns (or in these fns), not in your
-            `go` blocks.
-
-          - In particular: you MUST NEVER have parking calls inside
-            `(profiled {:dynamic? false} ...)`.
-
-            This can lead to concurrency exceptions.
-
-            If you must profile code within a go block, and you really want to
-            include un/parking times, use `(profiled {:dynamic? true} ...)`
-            instead."
+     {:doc (impl/docstring :profiled)
+      :arglists '([{:keys [id level sample when limit limit-by]} & body])}
 
      [opts & body]
-     (let [ns-str (str *ns*)]
-
-       (when-not (map? opts)
-         (truss/ex-info! "`tufte/profiled` requires a compile-time map as first arg."
-           {:ns-str ns-str :line (:line (meta &form))
-            :form (cons 'profiled (cons opts body))}))
-
-       (let [level-form (get opts :level    5)
-             dynamic?   (get opts :dynamic? false)
-             test-form  (get opts :when     true)
-             nmax       (get opts :nmax     default-nmax)
-
-             _ (valid-compile-time-opts dynamic? nmax)
-             nmax (long nmax)]
-
-         (when (integer? level-form) (valid-call-level level-form))
-
-         (if (-elide? level-form ns-str)
-           `[(do ~@body)]
-           (let [runtime-check
-                 (if (= test-form true) ; Common case
-                        `(may-profile? ~level-form ~ns-str)
-                   `(and (may-profile? ~level-form ~ns-str) ~test-form))]
-
-             (if dynamic?
-               `(if ~runtime-check
-                  (let [pd# (impl/new-pdata-dynamic ~nmax)]
-                    (binding [impl/*pdata* pd#]
-                      [(do ~@body) @pd#]))
-                  [(do ~@body)])
-
-               `(if ~runtime-check
-                  (let [pd# (impl/new-pdata-local ~nmax)]
-                    (binding [impl/*pdata* nil] ; Ensure no dynamic parent (=>nesting) steals local captures
-                      (try
-                        (impl/pdata-local-push pd#)
-                        [(do ~@body) @pd#]
-                        (finally (impl/pdata-local-pop)))))
-                  [(do ~@body)]))))))))
+     (impl/valid-opts! &form &env 'tufte/profiled opts body)
+     (let [opts     (merge {:level 5} opts)
+           ns-form* (get opts :ns :auto)
+           ns-form  (auto-> ns-form* (str *ns*))
+
+           {:keys [elide? allow?]}
+           (sigs/filter-call
+             {:cljs? (boolean (:ns &env))
+              :sf-arity 3
+              :ct-call-filter     impl/ct-call-filter
+              :*rt-call-filter* `impl/*rt-call-filter*}
+             (assoc opts :ns ns-form))
+
+           {:keys [dynamic? nmax]} opts]
+
+       (if elide?
+         `[(do ~@body)]
+         `((fn [] ; iffe-wrap
+             (let [body-fn# (fn [] ~@body)]
+               (enc/if-not ~allow?
+                 [(body-fn#)]
+                 (profiled* 'tufte/profiled ~dynamic? ~nmax (body-fn#))))))))))
 
 (comment
-  (enc/qb 1e6 ; [463.23 560.09]
-    (profiled {})
-    (profiled {} 2 (p :p1)))
+  (enc/qb 1e6   (profiled {:allow? false}) (profiled {})) ; [36.74 259.73]
+  (macroexpand '(profiled {:allow? false}))
 
-  (profiled {} (p :p1))
-  (profiled {} (p {:level 5 :id :p1}))
+  (profiled {} (p :p1 nil))
+  (profiled {} (p {:level 5 :id :p1} nil))
   (profiled {} (p (let [x :foo/id] x) "body"))
   (profiled {:level 2 :when (chance 0.5)} (p :p1 "body"))
-  (profiled {} (p :foo (p :bar))))
+  (profiled {} (p :foo (p :bar nil))))
 
 #?(:clj
    (defmacro profile
-     "Always executes body, and always returns <body-result>.
-
-     When [ns level] unelided and [ns level `when`] unfiltered, executes body
-     with profiling active and dispatches stats to any registered handlers
-     (see `add-handler!`).
-
-     Handy if you'd like to consume/aggregate stats output later/elsewhere.
-     Otherwise see `profiled`.
-
-     Compile-time opts:
-       `:dynamic?` - Use multi-threaded profiling? ; Default is `false`
-       `:nmax` ----- ~Max captures per id before compaction ; Default is 8e5
-
-     Runtime opts:
-       `:level` ---- e/o #{0 1 2 3 4 5} ; Default is `5`
-       `:when` ----- Optional arbitrary conditional form (e.g. boolean expr)
-       `:id` ------- Optional profiling id provided to handlers (e.g. `::my-stats-1`)
-       `:data` ----- Optional arbitrary data provided to handlers
-
-     Laziness in body:
-       Lazy seqs and other forms of laziness (e.g. delays) in body will only
-       contribute to profiling results if/when EVALUATION ACTUALLY OCCURS.
-       This is intentional and a useful property. Compare:
-
-         (profiled {}  (delay (Thread/sleep 2000))) ; Doesn't count sleep
-         (profiled {} @(delay (Thread/sleep 2000))) ; Does    count sleep
-
-     Async code in body:
-       Execution time of any code in body that runs asynchronously on a
-       different thread will generally NOT be automatically captured by default.
-
-       `:dynamic?` can be used to support capture in cases where Clojure's
-       binding conveyance applies (e.g. futures, agents, pmap). Just make sure
-       that all work you want to capture has COMPLETED before the `profiled`
-       form ends- for example, by blocking on pending futures.
-
-       In other advanced cases (notably core.async `go` blocks), please see
-       `with-profiling` and `capture-time!`.
-
-     `core.async` warning:
-        `core.async` code can be difficult to profile correctly without a deep
-        understanding of precisely what it's doing under-the-covers.
-
-        Some general recommendations that can help keep things simple:
-
-          - Try minimize the amount of code + logic in `go` blocks. Use `go`
-            blocks for un/parking to get the data you need, then pass the data
-            to external fns. Profile these fns (or in these fns), not in your
-            `go` blocks.
-
-          - In particular: you MUST NEVER have parking calls inside
-            `(profiled {:dynamic? false} ...)`.
-
-            This can lead to concurrency exceptions.
-
-            If you must profile code within a go block, and you really want to
-            include un/parking times, use `(profiled {:dynamic? true} ...)`
-            instead."
+     {:doc (impl/docstring :profile)
+      :arglists '([{:keys [id level sample when limit limit-by]} & body])}
 
      [opts & body]
-     (let [ns-str (str *ns*)]
-
-       (when-not (map? opts)
-         (truss/ex-info! "`tufte/profile` requires a compile-time map as first arg."
-           {:ns-str ns-str :line (:line (meta &form))
-            :form (cons 'profile (cons opts body))}))
-
-       (let [level-form (get opts :level 5)
+     (impl/valid-opts! &form &env 'tufte/profile opts body)
+     (let [opts     (merge {:level 5} opts)
+           ns-form* (get opts :ns :auto)
+           ns-form  (auto-> ns-form* (str *ns*))
+
+           {:keys [elide? allow?]}
+           (sigs/filter-call
+             {:cljs? (boolean (:ns &env))
+              :sf-arity 3
+              :ct-call-filter     impl/ct-call-filter
+              :*rt-call-filter* `impl/*rt-call-filter*}
+             (assoc opts :ns ns-form))
+
+           {:keys [dynamic? nmax]} opts]
+
+       (let [level-form (get opts :level)
              id-form    (get opts :id)
              data-form  (get opts :data)]
 
-         (when (integer? level-form) (valid-call-level level-form))
-
          `(let [[result# pstats#] (profiled ~opts ~@body)]
-            (when pstats#
+            (when        pstats#
               (impl/handle!
-                (HandlerVal. ~ns-str ~level-form ~id-form ~data-form
+                (HandlerVal. ~ns-form ~level-form ~id-form ~data-form
                   pstats# (delay (format-pstats pstats#))
                   ~*file* ~(:line (meta &form)))))
             result#)))))