diff --git a/docs/source/design.rst b/docs/source/design.rst index 04f6715b2..660b9f39c 100644 --- a/docs/source/design.rst +++ b/docs/source/design.rst @@ -45,7 +45,7 @@ System Layers 4. Routing(Distributed) Layer - Route MQTT messages between clustered nodes. + Route MQTT messages among clustered nodes. ---------------- Connection Layer @@ -63,11 +63,11 @@ This layer is built on the `eSockd`_ library which is a general Non-blocking TCP This layer is also responsible for encoding/decoding MQTT frames: -1. Parse MQTT frame received from client -2. Serialize MQTT frame sent to client +1. Parse MQTT frames received from client +2. Serialize MQTT frames sent to client 3. MQTT Connection Keepalive -Main modules of this layer: +Main erlang modules of this layer: +------------------+--------------------------+ | Module | Description | @@ -87,7 +87,7 @@ Main modules of this layer: Session Layer ------------- -The session layer processes MQTT packets received from client, and deliver PUBLISH packets to client. +The session layer processes MQTT packets received from client and delivers PUBLISH packets to client. A MQTT session will store the subscriptions and inflight messages in memory: @@ -100,7 +100,7 @@ A MQTT session will store the subscriptions and inflight messages in memory: messages which have been received from the Client, but have not been completely acknowledged. -4. All qos1, qos2 messages published to when client has been disconnected. +4. All qos1, qos2 messages published to when client is disconnected. MQueue and Inflight Window -------------------------- @@ -113,18 +113,18 @@ Concept of Message Queue and Inflight Window:: ----------------------------------------------- |<--- Win Size --->| -1. Inflight Window to store the messages delivered and awaiting for PUBACK. +1. Inflight Window to store the messages delivered and await for PUBACK. 2. Enqueue messages when the inflight window is full. -3. If the queue is full, dropped qos0 messages if store_qos0 is true, otherwise dropped the oldest one. +3. If the queue is full, drop qos0 messages if store_qos0 is true, otherwise drop the oldest one. -The larger the inflight window size, the higher the throughput. The smaller the window size, the more strict the message order. +The larger the inflight window size is, the higher the throughput is. The smaller the window size is, the more strict the message order is. PacketId and MessageId ---------------------- -The 16bits PacketId is defined by MQTT Protocol Specification, used by client/server to PUBLISH/PUBACK packets. A GUID(128bits globally unique Id) will be generated by the broker and assigned to a MQTT message. +The 16-bit PacketId is defined by MQTT Protocol Specification, used by client/server to PUBLISH/PUBACK packets. A GUID(128-bit globally unique Id) will be generated by the broker and assigned to a MQTT message. Format of the globally unique message id:: @@ -146,17 +146,17 @@ The PacketId and MessageId in a End-to-End Message PubSub Sequence:: PubSub Layer ------------ -The PubSub layer maintains a subscription table and responsible to dispatch MQTT messages to subscribers. +The PubSub layer maintains a subscription table and is responsible to dispatch MQTT messages to subscribers. .. image:: _static/images/dispatch.png -MQTT messages will be dispatched to the subscriber's session, which finally delivers the message to client. +MQTT messages will be dispatched to the subscriber's session, which finally delivers the messages to client. ------------- Routing Layer ------------- -The routing(distributed) layer maintains and replicates the global Topic Trie and Routing Table. The topic tire is composed of wildcard topics created by subscribers, and the Routing Table map a topic to nodes in the cluster. +The routing(distributed) layer maintains and replicates the global Topic Trie and Routing Table. The topic tire is composed of wildcard topics created by subscribers. The Routing Table maps a topic to nodes in the cluster. For example, if node1 subscribed 't/+/x' and 't/+/y', node2 subscribed 't/#' and node3 subscribed 't/a', there will be a topic trie and route table:: @@ -173,11 +173,11 @@ For example, if node1 subscribed 't/+/x' and 't/+/y', node2 subscribed 't/#' and | t/a -> node3 | ------------------------- -The routing layer would route MQTT messages between clustered nodes by topic trie match and routing table lookup: +The routing layer would route MQTT messages among clustered nodes by topic trie match and routing table lookup: .. image:: _static/images/route.png -The routing design follows the two rules: +The routing design follows two rules: 1. A message only gets forwarded to other cluster nodes if a cluster node is interested in it. This reduces the network traffic tremendously, because it prevents nodes from forwarding unnecessary messages. @@ -307,7 +307,7 @@ emqttd_acl_internal implements the default ACL based on etc/acl.config file:: Hooks Design ------------ -The emqttd broker implements a simple but powerful hooks mechanism to help users develop plugin. The broker would run the hooks when a client is connected/disconnected, a topic is subscribed/unsubscribed or a MQTT message is published/delivered/acked: +The emqttd broker implements a simple but powerful hooks mechanism to help users develop plugin. The broker would run the hooks when a client is connected/disconnected, a topic is subscribed/unsubscribed or a MQTT message is published/delivered/acked. Hooks defined by the emqttd 1.0 broker: @@ -331,7 +331,7 @@ Hooks defined by the emqttd 1.0 broker: | client.disconnected | Run when client disconnected from broker | +------------------------+------------------------------------------------------+ -The emqttd broker uses the `Chain-of-responsibility_pattern`_ to implement hook mechanism. The callback functions registered to hook will be executed one bye one:: +The emqttd broker uses the `Chain-of-responsibility_pattern`_ to implement hook mechanism. The callback functions registered to hook will be executed one by one:: -------- ok | {ok, NewAcc} -------- ok | {ok, NewAcc} -------- (Args, Acc) --> | Fun1 | -------------------> | Fun2 | -------------------> | Fun3 | --> {ok, Acc} | {stop, Acc} @@ -339,7 +339,7 @@ The emqttd broker uses the `Chain-of-responsibility_pattern`_ to implement hook | | | stop | {stop, NewAcc} stop | {stop, NewAcc} stop | {stop, NewAcc} -The callback function for hook should return: +The callback function for a hook should return: +-----------------+------------------------+ | Return | Description | @@ -353,7 +353,7 @@ The callback function for hook should return: | {stop, NewAcc} | Return Acc and Break | +-----------------+------------------------+ -The input arguments for a callback function is different depending on the type of hook. Clone the `emqttd_plugin_template`_ to check how to use hooks. +The input arguments for a callback function are depending on the types of hook. Clone the `emqttd_plugin_template`_ project to check the argument in detail. Hook Implementation ------------------- @@ -396,7 +396,7 @@ And implemented in emqttd_hook module: Hook Usage ---------- -`emqttd_plugin_template`_ provides the examples for hook usage: +The `emqttd_plugin_template`_ project provides the examples for hook usage: .. code:: erlang @@ -434,7 +434,7 @@ Hook Usage Plugin Design ------------- -Plugin is a normal erlang application that could be started/stopped dynamically by a running emqttd broker. +Plugin is a normal erlang application that can be started/stopped dynamically by a running emqttd broker. emqttd_plugins Module ---------------------