Peter M. Groen / TrueMQTT-cpp

Commit ace91efdb5ebc0099c3ede3d7acf011f80afbd30

Authored by Patric Stout
1 parent 510ac007

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.
Inline Side-by-side
Showing 2 changed files with 17 additions and 5 deletions
example/pubsub/main.cpp
  View file @ace91ef
... ... @@ -30,6 +30,10 @@ int main()
30 30 {
31 31 std::cout << "Received message on exact topic " << topic << ": " << payload << std::endl;
32 32 stop++; });
  33 + client.subscribe("test/test/test", [&stop](const std::string topic, const std::string payload)
  34 + {
  35 + std::cout << "Received message on exact topic " << topic << ": " << payload << std::endl;
  36 + stop++; });
33 37 client.subscribe("test/+/test", [&stop](const std::string topic, const std::string payload)
34 38 {
35 39 std::cout << "Received message on single wildcard topic " << topic << ": " << payload << std::endl;
... ... @@ -48,7 +52,7 @@ int main()
48 52 client.publish("test/test/test", "Hello World!", false);
49 53  
50 54 // Wait till we receive the message back on our subscription.
51   - while (stop != 3)
  55 + while (stop < 4)
52 56 {
53 57 std::this_thread::sleep_for(std::chrono::milliseconds(10));
54 58 }
... ...
include/TrueMQTT.h
  View file @ace91ef
... ... @@ -233,10 +233,18 @@ namespace TrueMQTT
233 233 * @param topic The topic to subscribe to.
234 234 * @param callback The callback to call when a message arrives on this topic.
235 235 *
236   - * @note Subscription can overlap, but you cannot subscribe on the exact same topic twice.
237   - * If you do, the callback of the first subscription will be overwritten.
238   - * In other words, "a/+" and "a/b" is fine, and callbacks for both subscribes will be
239   - * called when something is published on "a/b".
  236 + * @note Subscription can overlap, even on the exact same topic. All callbacks that
  237 + * match the topic will be called.
  238 + * @note Depending on the broker, overlapping subscriptions can trigger one or more
  239 + * calls to the same callback with the same message. This is because some brokers
  240 + * send the message to all matching subscriptions, and some only send it to one.
  241 + * To prevent some callbacks not being called for brokers that do the latter, this
  242 + * library will call all matching callbacks every time.
  243 + * Example: If you subscribe to "a/b" and "a/+", and a message arrives on "a/b",
  244 + * both callbacks will be called. Some brokers will send a single message when
  245 + * someone publishes to "a/b", and some will send for every subscription matching
  246 + * (so twice in this case). In the latter case, the callback of both "a/b" and "a/+"
  247 + * are called twice with the same "a/b" message.
240 248 * @note You cannot subscribe a topic if you are disconnected from the broker. Call
241 249 * \ref connect first.
242 250 * @note This function can stall for a short moment if you publish just at the
... ...