yuanbiao
/
emqx
1
0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc review

This commit is contained in:
Feng 2016-04-03 20:56:34 +08:00
parent 2d1b6775a8
commit 68ea42d911
1 changed files with 21 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/source/design.rst
View File

@ -45,7 +45,7 @@ System Layers
4. Routing(Distributed) Layer 4. Routing(Distributed) Layer
Route MQTT messages between clustered nodes. Route MQTT messages among clustered nodes.
---------------- ----------------
Connection Layer 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: This layer is also responsible for encoding/decoding MQTT frames:
1. Parse MQTT frame received from client 1. Parse MQTT frames received from client
2. Serialize MQTT frame sent to client 2. Serialize MQTT frames sent to client
3. MQTT Connection Keepalive 3. MQTT Connection Keepalive
Main modules of this layer: Main erlang modules of this layer:
+------------------+--------------------------+ +------------------+--------------------------+
| Module | Description | | Module | Description |
@ -87,7 +87,7 @@ Main modules of this layer:
Session 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: 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 messages which have been received from the Client, but have not been
completely acknowledged. 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 MQueue and Inflight Window
-------------------------- --------------------------
@ -113,18 +113,18 @@ Concept of Message Queue and Inflight Window::
----------------------------------------------- -----------------------------------------------
|<--- Win Size --->| |<--- 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. 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 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:: 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 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 .. 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 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:: 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 | | 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 .. 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. 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 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: 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 | | 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} -------- -------- ok | {ok, NewAcc} -------- ok | {ok, NewAcc} --------
(Args, Acc) --> | Fun1 | -------------------> | Fun2 | -------------------> | Fun3 | --> {ok, Acc} | {stop, Acc} (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} 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 | | Return | Description |
@ -353,7 +353,7 @@ The callback function for hook should return:
| {stop, NewAcc} | Return Acc and Break | | {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 Hook Implementation
------------------- -------------------
@ -396,7 +396,7 @@ And implemented in emqttd_hook module:
Hook Usage Hook Usage
---------- ----------
`emqttd_plugin_template`_ provides the examples for hook usage: The `emqttd_plugin_template`_ project provides the examples for hook usage:
.. code:: erlang .. code:: erlang
@ -434,7 +434,7 @@ Hook Usage
Plugin Design 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 emqttd_plugins Module
--------------------- ---------------------