Merge pull request #428 from sahib/fix/subscribe-docs

Add note about blocking behavior in docs of Subscribe()

client.go

@@ -656,6 +656,11 @@ func (c *client) Publish(topic string, qos byte, retained bool, payload interfac
 
 // Subscribe starts a new subscription. Provide a MessageHandler to be executed when
 // a message is published on the topic provided.
+//
+// Please note: you should try to keep the execution time of the callback to be
+// as low as possible, especially when SetOrderMatters(true) (the default) is in
+// place. Blocking calls in message handlers might otherwise delay delivery to
+// other message handlers.
 func (c *client) Subscribe(topic string, qos byte, callback MessageHandler) Token {
 	token := newToken(packets.Subscribe).(*SubscribeToken)
 	DEBUG.Println(CLI, "enter Subscribe")

options.go

@@ -209,6 +209,7 @@ func (o *ClientOptions) SetCleanSession(clean bool) *ClientOptions {
 // each QoS level. By default, this value is true. If set to false,
 // this flag indicates that messages can be delivered asynchronously
 // from the client to the application and possibly arrive out of order.
+// Specifically, the message handler is called in its own go routine.
 func (o *ClientOptions) SetOrderMatters(order bool) *ClientOptions {
 	o.Order = order
 	return o

router.go

@@ -168,10 +168,8 @@ func (r *router) matchAndDispatch(messages <-chan *packets.PublishPacket, order
 		}
 		r.RUnlock()
 		for _, handler := range handlers {
-			func() {
-				handler(client, m)
-				m.Ack()
-			}()
+			handler(client, m)
+			m.Ack()
 		}
 		// DEBUG.Println(ROU, "matchAndDispatch handled message")
 	}