Pulling in opts assoc from previous patch.

Author: fogus

README.md

@@ -64,10 +64,9 @@ Copyright © Rich Hickey and contributors
 
 ## Changelog
 
-* next
+* Release 1.9.847-alpha3 on 2026-03-11
   * [ASYNC-262](https://clojure.atlassian.net/browse/ASYNC-262) (CLJ) REVERTED from 1.9.829-alpha2
   * [ASYNC-272](https://clojure.atlassian.net/browse/ASYNC-272) (CLJ) Use JVM virtual threads in io-thread
-  * [ASYNC-271](https://clojure.atlassian.net/browse/ASYNC-271) (CLJ) futurize with no :exec arg throws 
   * [ASYNC-269](https://clojure.atlassian.net/browse/ASYNC-269) (CLJ) Noop callbacks dispatch on caller thread
 * Release 1.9.829-alpha2 on 2025-10-01
   * [ASYNC-262](https://clojure.atlassian.net/browse/ASYNC-262) (CLJ) Use virtual threads when available for go and io-thread

docs/clojure.core.async.flow.html

@@ -25,6 +25,17 @@
 details. The flow configuration provides a centralized place for
 policy decisions regarding process settings, threading, buffering etc.
 
+Flow also provides a subsystem for broadcast communication of
+out-of-band messages without explicit connections or
+declarations. This could for example be used to communicate the
+passage of (real or virtual) time. Broadcast messages are associated
+with (otherwise undeclared) signal-ids, and will be received by
+processes selecting those ids. Broadcasts messages will arrive along
+with messages from process inputs, so signal-ids must not conflict
+with any process input-id. Thus namespaced keywords, UUIDs etc or
+tuples thereof are recommended as signal-ids. See process
+describe/transform and inject below for details.
+
 It is expected that applications will rarely define instances of the
 process protocol but instead use the API function 'process' that
 implements the process protocol in terms of calls to ordinary
@@ -54,18 +65,24 @@
 
 :proc - a function that starts a process
 :args - a map of param->val which will be passed to the process ctor
-:chan-opts - a map of in-or-out-id->{:keys [buf-or-n xform]}, where buf-or-n
+:chan-opts - a map of io-id->{:keys [buf-or-n xform]},
+             where io-id is an input/output name, and buf-or-n
              and xform have their meanings per core.async/chan
-             the default is {:buf-or-n 10}
+             the default for inputs and outputs is {:buf-or-n 10}
 
 :conns - a collection of [[from-pid outid] [to-pid inid]] tuples.
 
 Inputs and outputs support multiple connections. When an output is
-connected multiple times every connection will get every message,
-as per a core.async/mult.
+connected multiple times every connection will get every message, as
+per a core.async/mult. Note that non-multed outputs do not have
+corresponding channels and thus any chan-opts will be ignored.
+
+Broadcast signals are conveyed to a process via a channel with an
+async/sliding-buffer of size 100, thus signals not handled in a
+timely manner will be dropped in favor of later arriving signals.
 
-:mixed-exec/:io-exec/:compute-exec -> ExecutorService
-These can be used to specify the ExecutorService to use for the
+:mixed-exec/:io-exec/:compute-exec -> Executor
+These can be used to specify the Executor to use for the
 corresonding workload, in lieu of the lib defaults.
 
 N.B. The flow is not started. See 'start'</pre></div></div><div class="public anchor" id="var-futurize"><h3>futurize</h3><div class="usage"><code>(futurize f &amp; {:keys [exec], :or {exec :mixed}, :as opts})</code></div><div class="doc"><pre class="plaintext">Takes a fn f and returns a fn that takes the same arguments as f
@@ -75,10 +92,12 @@
 
 futurize accepts kwarg options:
 :exec - one of the workloads :mixed, :io, :compute
-        or a j.u.c.ExecutorService object,
-        default :mixed</pre></div></div><div class="public anchor" id="var-inject"><h3>inject</h3><div class="usage"><code>(inject g [pid io-id :as coord] msgs)</code></div><div class="doc"><pre class="plaintext">asynchronously puts the messages on the channel corresponding to the
-input or output of the process, returning a future that will
-complete when done.</pre></div></div><div class="public anchor" id="var-lift*-.3Estep"><h3>lift*-&gt;step</h3><div class="usage"><code>(lift*-&gt;step f)</code></div><div class="doc"><pre class="plaintext">given a fn f taking one arg and returning a collection of non-nil
+        or a j.u.c.Executor object,
+        default :mixed</pre></div></div><div class="public anchor" id="var-inject"><h3>inject</h3><div class="usage"><code>(inject g [pid io-id :as coord] msgs)</code></div><div class="doc"><pre class="plaintext">asynchronously puts the messages on the channel corresponding to
+the input or output of the process, returning a future that will
+complete when done. You can broadcast messages on a signal using the
+special coord [::flow/cast a-signal-id]. Note that signals cannot be
+sent to a particular process.</pre></div></div><div class="public anchor" id="var-lift*-.3Estep"><h3>lift*-&gt;step</h3><div class="usage"><code>(lift*-&gt;step f)</code></div><div class="doc"><pre class="plaintext">given a fn f taking one arg and returning a collection of non-nil
 values, creates a step fn as needed by process, with one input
 and one output (named :in and :out), and no state.</pre></div></div><div class="public anchor" id="var-lift1-.3Estep"><h3>lift1-&gt;step</h3><div class="usage"><code>(lift1-&gt;step f)</code></div><div class="doc"><pre class="plaintext">like lift*-&gt;step except taking a fn returning one value, which when
 nil will yield no output.</pre></div></div><div class="public anchor" id="var-map-.3Estep"><h3>map-&gt;step</h3><div class="usage"><code>(map-&gt;step {:keys [describe init transition transform]})</code></div><div class="doc"><pre class="plaintext">given a map of functions corresponding to step fn arities (see
@@ -113,20 +132,25 @@
 datafy.
 
 arity 0 - 'describe', () -&gt; description
-where description is a map with keys :params :ins and :outs, each of which
-in turn is a map of keyword to doc string, and :workload with
-possible values of :mixed :io :compute. All entries in the describe
-return map are optional.
+where description is a map with possible keys:
+:params :ins and :outs, each of which in turn is a map of keyword to doc string
+:signal-select - a predicate of a signal-id. Messages on approved
+                 signals will appear in the transform arity (see below)
+                 For the simple case of enumerated signal-ids, use a set,
+                 e.g. #{:this/signal :that/signal}
+                 If no :signal-select is provided, no signals will be received
+:workload with possible values of :mixed :io :compute.
+All entries in the describe return map are optional.
 
 :params describes the initial arguments to setup the state for the function.
-:ins enumerates the input[s], for which the flow will create channels
-:outs enumerates the output[s], for which the flow may create channels.
+:ins enumerates the process input[s], for which the flow will create channels
+:outs enumerates the process output[s], for which the flow _may_ create channels.
 :workload - describes the nature of the workload, one of :mixed :io or :compute
         an :io workload should not do extended computation
         a :compute workload should never block
 
-No key may be present in both :ins and :outs, allowing for a uniform
-channel coordinate system of [:process-id :channel-id]. The
+No io-id key may be present in both :ins and :outs, allowing for a
+uniform channel coordinate system of [:process-id :channel-id]. The
 ins/outs/params returned will be the ins/outs/params of the
 process. describe may be called by users to understand how to use
 the proc. It will also be called by the impl in order to discover
@@ -166,16 +190,23 @@
 process will no longer be used following that. See the SPI for
 details. state' will be the state supplied to subsequent calls.
 
-arity 3 - 'transform', (state in-name msg) -&gt; [state' output]
+arity 3 - 'transform', (state in-or-signal-id msg) -&gt; [state' output]
 where output is a map of outid-&gt;[msgs*]
 
-The transform arity will be called every time a message arrives at any
-of the inputs. Output can be sent to none, any or all of the :outs
-enumerated, and/or an input named by a [pid inid] tuple (e.g. for
-reply-to), and/or to the ::flow/report output. A step need not
-output at all (output or msgs can be empyt/nil), however an output _message_
-may never be nil (per core.async channels). state' will be the state
-supplied to subsequent calls.
+The transform arity will be called every time a message arrives at
+any of the inputs or signals (selected via :signal-select in
+describe), identified by the id. Output can be sent to none, any or
+all of the :outs enumerated, and/or an input named by a [pid in-id]
+coord tuple (e.g. for reply-to), and/or to the ::flow/report
+output.
+
+You can broadcast output to all processes selecting a signal via
+the special coord [::flow/cast a-signal-id] Note that signals cannot
+be sent to a particular process.
+
+A step need not output at all (output or msgs can be empty/nil),
+however an output _message_ may never be nil (per core.async
+channels). state' will be the state supplied to subsequent calls.
 
 process also accepts an option map with keys:
 :workload - one of :mixed, :io or :compute

docs/clojure.core.async.flow.spi.html

@@ -67,8 +67,8 @@
         N.B. outputs may be nil if not connected
 :resolver - an impl of spi/Resolver, which can be used to find
             channels given their logical [pid cid] coordinates, as well as to
-            obtain ExecutorServices corresponding to the
-            logical :mixed/:io/:compute contexts</pre></div></div></div></div></div><div class="public anchor" id="var-Resolver"><h3>Resolver</h3><h4 class="type">protocol</h4><div class="usage"></div><div class="doc"><pre class="plaintext"></pre></div><div class="members"><h4>members</h4><div class="inner"><div class="public anchor" id="var-get-exec"><h3>get-exec</h3><div class="usage"><code>(get-exec _ context)</code></div><div class="doc"><pre class="plaintext">returns the ExecutorService for the given context, one
+            obtain Executors corresponding to the
+            logical :mixed/:io/:compute contexts</pre></div></div></div></div></div><div class="public anchor" id="var-Resolver"><h3>Resolver</h3><h4 class="type">protocol</h4><div class="usage"></div><div class="doc"><pre class="plaintext"></pre></div><div class="members"><h4>members</h4><div class="inner"><div class="public anchor" id="var-get-exec"><h3>get-exec</h3><div class="usage"><code>(get-exec _ context)</code></div><div class="doc"><pre class="plaintext">returns the Executor for the given context, one
 of :mixed, :io, :compute</pre></div></div><div class="public anchor" id="var-get-write-chan"><h3>get-write-chan</h3><div class="usage"><code>(get-write-chan _ coord)</code></div><div class="doc"><pre class="plaintext">Given a tuple of [pid cid], returns a core.async chan to
 write to or nil (in which case the output should be dropped,
 e.g. nothing is connected).</pre></div></div></div></div></div></div></body></html>