Docs: improve Broker coverage.

Author: peterhinch

v3/docs/DRIVERS.md

@@ -1136,8 +1136,6 @@ finally:
 
 # 9. Message Broker
 
-This is under development: please check for updates.
-
 ```python
 from primitives import Broker  # broker.py
 ```
@@ -1148,7 +1146,7 @@ message. This enables one to one, one to many, many to one or many to many
 messaging.
 
 A task subscribes to a topic with an `agent`. This is stored by the broker. When
-the broker publishes a message, the `agent` of each task subscribed to its topic
+the broker publishes a message, every `agent` subscribed to the message topic
 will be triggered. In the simplest case the `agent` is a `Queue` instance: the
 broker puts the topic and message onto the subscriber's queue for retrieval.
 
@@ -1173,18 +1171,20 @@ The `topic` arg is typically a string but may be any hashable object. A
 
 #### Agent types
 
-An `agent` may be an instance of any of the following:
+An `agent` may be an instance of any of the following types. Args refers to any
+arguments passed to the `agent`'s' subscription.
 
-* `RingbufQueue` Received messages are queued as a 2-tuple `(topic, message)`.
+* `RingbufQueue` Received messages are queued as a 2-tuple `(topic, message)`
+assuming no args.
 * `Queue` Received messages are queued as a 2-tuple `(topic, message)`.
-* `function` Called when a message is received. Args: topic, message plus any
-further args.
-* `bound method` Called when a message is received. Args: topic, message plus any
+* `function` Called when a message is received. Args: `topic`, `message` plus any
 further args.
-* `coroutine` Converted to a `task` when a message is received. Args: topic,
-message plus any further args.
-* `bound coroutine`  Converted to a `task` when a message is received. Args: topic,
-message plus any further args.
+* `bound method` Called when a message is received. Args: `topic`, `message`
+plus any further args.
+* `coroutine` Converted to a `task` when a message is received. Args: `topic`,
+`message` plus any further args.
+* `bound coroutine`  Converted to a `task` when a message is received. Args: `topic`,
+`message` plus any further args.
 * `user_agent` Instance of a user class. See user agents below.
 * `Event` Set when a message is received.
 
@@ -1232,7 +1232,8 @@ async def messages(client):
         broker.publish(topic.decode(), msg.decode())
 ```
 Assuming the MQTT client is subscribed to multiple topics, message strings are
-directed to individual tasks each supporting one topic.
+directed to agents, each dedicated to handling a topic. An `agent` might operate
+an interface or queue the message for a running task.
 
 The following illustrates a use case for passing args to an `agent` (pin nos.
 are for Pyoard 1.1).
@@ -1322,14 +1323,15 @@ applications this behaviour is preferable. In general `RingbufQueue` is
 preferred as it is optimised for microcontroller use and supports retrieval by
 an asynchronous iterator.
 
-If either queue type is subscribed with args, publications will queued as a
-3-tuple `(topic, message, (args...))`. There is no obvious use case for this.
+If either queue type is subscribed with args, a publication will create a queue
+entry that is a 3-tuple `(topic, message, (args...))`. There is no obvious use
+case for this.
 
 #### exceptions
 
-An instance of an `agent` objects is owned by a subscribing tasks but is
-executed by a publishing task. If a function used as an `agent` throws an
-exception, the traceback will point to a `Broker.publish` call.
+An `agent` instance is owned by a subscribing tasks but is executed by a
+publishing task. If a function used as an `agent` throws an exception, the
+traceback will point to a `Broker.publish` call.
 
 The `Broker` class throws a `ValueError` if `.subscribe` is called with an
 invalid `agent` type. There are a number of non-fatal conditions which can occur

v3/docs/TUTORIAL.md

@@ -45,7 +45,8 @@ import uasyncio as asyncio
   3.7 [Barrier](./TUTORIAL.md#37-barrier)  
   3.8 [Delay_ms](./TUTORIAL.md#38-delay_ms-class) Software retriggerable delay.  
   3.9 [Message](./TUTORIAL.md#39-message)  
-  3.10 [Synchronising to hardware](./TUTORIAL.md#310-synchronising-to-hardware)
+  3.10 [Message broker](./TUTORIAL.md#310-message-broker) A publish-subscribe model of messaging and control.  
+  3.11 [Synchronising to hardware](./TUTORIAL.md#311-synchronising-to-hardware)
   Debouncing switches, pushbuttons, ESP32 touchpads and encoder knobs. Taming ADC's.  
  4. [Designing classes for asyncio](./TUTORIAL.md#4-designing-classes-for-asyncio)  
   4.1 [Awaitable classes](./TUTORIAL.md#41-awaitable-classes)  
@@ -589,6 +590,8 @@ following classes which are non-standard, are also in that directory:
  in a similar (but not identical) way to `gather`.
  * `Delay_ms` A useful software-retriggerable monostable, akin to a watchdog.
  Calls a user callback if not cancelled or regularly retriggered.
+ * `RingbufQueue` a MicroPython-optimised queue.
+ * `Broker` a means of messaging and control based on a publish/subscribe model.
 
 A further set of primitives for synchronising hardware are detailed in
 [section 3.9](./TUTORIAL.md#39-synchronising-to-hardware).
@@ -1280,7 +1283,26 @@ provide an object similar to `Event` with the following differences:
 It may be found in the `threadsafe` directory and is documented
 [here](./THREADING.md#32-message).
 
-## 3.10 Synchronising to hardware
+## 3.10 Message broker
+
+A `Broker` is a means of communicating data and/or control within or between
+modules. It is typically a single global object, and uses a publish-subscribe
+model. A publication comprises a `topic` and a `message`; the latter may be any
+Python object. Tasks subscribe to a `topic` via an `agent` object. Whenever a
+publication, occurs all `agent` instances currently subscribed to that topic are
+triggered.
+
+An `agent` may be an instance of various types including a function, a coroutine
+or a queue.
+
+A benefit of this approach is that the design of publishing tasks can proceed
+independently from that of the subscribers; `agent` instances can be subscribed
+and unsubscribed at run time with no effect on the publisher. The publisher
+neither knows or cares about the type or number of subscribing `agent`s.
+
+This is [documented here](https://github.com/peterhinch/micropython-async/blob/master/v3/docs/DRIVERS.md#9-message-broker).
+
+## 3.11 Synchronising to hardware
 
 The following hardware-related classes are documented [here](./DRIVERS.md):
  * `ESwitch` A debounced switch with an `Event` interface.