README.md in qpid_proton-0.22.0

- old
+ new
@@ -56,21 +56,37 @@
 
  * **on_transport_close** - Fired when the network transport is closed.
 
 ## Now About That Broker example
 
-The **broker.rb** example application is a nice demonstration of doing something more interesting in Ruby with Proton.
+The **broker.rb** example application is a nice demonstration of doing something more interesting in Ruby with Proton, and shows how to use multiple threads.
 
-The way the broker works is to listen to incoming connections, examine the components of the address for that connection, attach that connection to an exchange managing that address and then it sends any messages destined for that address to them.
+The broker listens for incoming connections and sender/receiver links. It uses the source and target address of senders and receivers to identify a queue. Messages from receivers go on the queue, and are sent via senders.
 
 The components of the broker example include:
- * **Broker** - A class that extends the MessagingHandler class. It accepts incoming connections, manages subscribing them to exchanges, and transfers messages between them.
- * **MessageQueue** - Distributes messages to subscriptions.
+ * **Broker** is a Listener::Handler that accepts connections, and manages the set of named queues.
+ * **BrokerHandler** extends MessagingHandler to accept incoming connections, senders and receivers and transfers messages between them and the Broker's queues.
+ * **MessageQueue** - A queue of messages that keeps track of waiting senders.
 
-The Broker manages a map connecting a queue address to the instance of Exchange that holds references to the endpoints of interest.
-
 The broker application demonstrates a new set of events:
 
- * **on_link_open** - Fired when a remote link is opened. From this event the broker grabs the address and subscribes the link to an exchange for that address.
- * **on_link_close** - Fired when a remote link is closed. From this event the broker grabs the address and unsubscribes the link from that exchange.
- * **on_connection_close** - Fired when a remote connection is closed but the local end is still open.
- * **on_transport_close** - Fired when the protocol transport has closed. The broker removes all links for the disconnected connection, avoiding workign with endpoints that are now gone.
+ * **on_sender_open** - Fired when a sender link is opened, the broker gets the address and starts sending messages from the corresponding queue.
+ * **on_sender_close** - Fired when a sender link is closed, remove the sender from the queue so no more messages are sent.
+ * **on_connection_close** - Fired when the remote connection is closes, close all senders.
+ * **on_transport_close** - Fired when the transport (socket) has closed, close all senders.
+
+It also demonstrates aspects of multi-threaded proton:
+
+ * **Thread safe MessageQueue** Uses a Mutex to make actions atomic when called concurrently.
+
+ * **Using WorkQueue** Proton objects like Sender are not thread safe.  They are
+   normally only used in MessagingHandler#on_ callbacks.  To request work from a
+   different thread you can add a code block to a WorkQueue, as shown in
+   MessageQueue#push.
+
+ * **Listener::Handler** The broker creates a new BrokerHandler instance for
+   each accepted connection. The container ensures that calls on each handler instance
+   are serialized even if there are multiple threads in the container.
+
+ * **Calling Container#run in multiple threads** The Container uses threads that call
+   #run as a thread pool to dispatch calls to MessagingHandler instances. Even
+   if there are multiple threads, calls to handler instance are serialized.