Shared subscription

Shared subscription is a subscription method that achieves load balancing among multiple subscribers:

  1.                                                    [subscriber1] got msg1
  2.              msg1, msg2, msg3                    /
  3. [publisher]  ---------------->  "$share/g/topic"  -- [subscriber2] got msg2
  4.                                                  \
  5.                                                    [subscriber3] got msg3

In the above picture, three subscribers subscribe to the same topic $share/g/topic using a shared subscription method, where topic is the real topic name they subscribed to, and $share/g/ is a shared subscription Prefix. EMQX Broker supports shared subscription prefixes in two formats:

ExamplePrefixReal topic name
$queue/t/1$queue/t/1
$share/abc/t/1$share/abct/1

Shared subscription with groups

Shared subscriptions prefixed with $ share/<group-name> are shared subscriptions with groups:

group-name can be any string. Subscribers who belong to the same group will receive messages with load balancing, but EMQX Broker will broadcast messages to different groups.

For example, suppose that subscribers s1, s2, and s3 belong to group g1, and subscribers s4 and s5 belong to group g2. Then when EMQX Broker publishes a message msg1 to this topic:

  • EMQX Broker will send msg1 to both groups g1 and g2
  • Only one of s1, s2, s3 will receive msg1
  • Only one of s4 and s5 will receive msg1
  1.                                        [s1]
  2.            msg1                      /
  3. [emqx]  ------>  "$share/g1/topic"    - [s2] got msg1
  4.          |                           \
  5.          |                             [s3]
  6.          | msg1
  7.           ---->  "$share/g2/topic"   --  [s4]
  8.                                      \
  9.                                       [s5] got msg1

Shared subscription without group

Shared subscriptions prefixed with $queue/ are shared subscriptions without groups. It is a special case of $share subscription, which is quite similar to all subscribers in a subscription group:

  1.                                        [s1] got msg1
  2.         msg1,msg2,msg3               /
  3. [emqx]  --------------->  "$queue/topic" - [s2] got msg2
  4.                                      \
  5.                                        [s3] got msg3

Balancing strategy and distribution of Ack configuration

EMQX Broker’s shared subscription supports balancing strategy and distribution of Ack configuration:

  1. # etc/emqx.conf
  3. # balancing strategy
  4. broker.shared_subscription_strategy = random
  6. # Per-group balancing strategy
  7. broker.$group_name.shared_subscription_strategy = local
  9. # Works for QoS1 QoS2 messages
  10. # If enabled, when a shared subscriber is disconnected (but the session is still stored in the server)
  11. # the follow-up messages is promptly forwarded to other shared subscribers in the group
  12. broker.shared_dispatch_ack_enabled = false
Balancing strategyDescription
hash_clientidAccording to the hash value of the publisher ClientID
hash_topicAccording to the hash value of the message’s topic name
localSelects random subscriber connected to the node which received the message. If no such subscribers present, selects a random cluster-wise
randomSelect randomly among all subscribers
round_robinAccording to the order of subscription
stickyFirst dispatch is random, then stick to it for all subsequent messages until that subscriber goes disconnected or that publisher reconnects

TIP

Whether it is a single client subscription or a shared subscription, pay attention to the client performance and message reception rate, otherwise it will cause errors such as message accumulation and client crash.