chore(interface): document behaviour of overlapping subscriptions

The specifications say that the broker MAY deduplicate messages on overlapping subscriptions. In result, some do, and some don't. It is now, by documentation, left to the user of this library to handle overlapping subscriptions properly, and depending on their broker, they may receive one or more times the same message when the subscriptions overlap.

chore(interface): document behaviour of overlapping subscriptions
The specifications say that the broker MAY deduplicate messages on overlapping subscriptions. In result, some do, and some don't. It is now, by documentation, left to the user of this library to handle overlapping subscriptions properly, and depending on their broker, they may receive one or more times the same message when the subscriptions overlap.
Patric Stout
1 parent 510ac007
Showing 2 changed files with 17 additions and 5 deletions
example/pubsub/main.cpp
include/TrueMQTT.h
@@ -30,6 +30,10 @@ int main()
                      {
         std::cout << "Received message on exact topic " << topic << ": " << payload << std::endl;
         stop++; });
+    client.subscribe("test/test/test", [&stop](const std::string topic, const std::string payload)
+                     {
+        std::cout << "Received message on exact topic " << topic << ": " << payload << std::endl;
+        stop++; });
     client.subscribe("test/+/test", [&stop](const std::string topic, const std::string payload)
                      {
         std::cout << "Received message on single wildcard topic " << topic << ": " << payload << std::endl;
@@ -48,7 +52,7 @@ int main()
     client.publish("test/test/test", "Hello World!", false);
     // Wait till we receive the message back on our subscription.
-    while (stop != 3)
+    while (stop < 4)
     {
         std::this_thread::sleep_for(std::chrono::milliseconds(10));
     }
@@ -233,10 +233,18 @@ namespace TrueMQTT
          * @param topic The topic to subscribe to.
          * @param callback The callback to call when a message arrives on this topic.
          *
-         * @note Subscription can overlap, but you cannot subscribe on the exact same topic twice.
-         * If you do, the callback of the first subscription will be overwritten.
-         * In other words, "a/+" and "a/b" is fine, and callbacks for both subscribes will be
-         * called when something is published on "a/b".
+         * @note Subscription can overlap, even on the exact same topic. All callbacks that
+         * match the topic will be called.
+         * @note Depending on the broker, overlapping subscriptions can trigger one or more
+         * calls to the same callback with the same message. This is because some brokers
+         * send the message to all matching subscriptions, and some only send it to one.
+         * To prevent some callbacks not being called for brokers that do the latter, this
+         * library will call all matching callbacks every time.
+         * Example: If you subscribe to "a/b" and "a/+", and a message arrives on "a/b",
+         * both callbacks will be called. Some brokers will send a single message when
+         * someone publishes to "a/b", and some will send for every subscription matching
+         * (so twice in this case). In the latter case, the callback of both "a/b" and "a/+"
+         * are called twice with the same "a/b" message.
          * @note You cannot subscribe a topic if you are disconnected from the broker. Call
          * \ref connect first.
          * @note This function can stall for a short moment if you publish just at the