docs: update YJSInDepth.rst

update docs of event mechanism

.gitignore

@@ -22,3 +22,4 @@
 
 # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
 hs_err_pid*
+/.idea

source/YJSInDepth.rst

@@ -128,40 +128,91 @@ YJS中的变量类似于JavaScript（ES6）中的变量，分为\ **全局变量
 事件
 ^^^^
 
-YJS中的事件类似于Solidity中的事件。
+YJS中包含两种事件，全局（Global）事件和本地（Local）事件：
+
+* 全局事件类似于一般事件中间件中的事件，发布的事件由事件主题进行标识，订阅者通过订阅事件主题获取相应的事件。
+* 本地事件类似于以太坊Solidity中的事件，由智能合约定义并发布，订阅者需要使用合约名/合约ID和事件名来订阅特定合约的相应事件。
 
 **发布者**\ 定义一个包含事件发布函数的事件，然后通过调用事件发布函数发布事件。
+定义的事件默认为本地事件，可使用global或local关键词来标识事件的类型。
 
 **订阅者**\ 订阅并处理事件。
 
 事件示例如下：
 
-EventPuber.yjs
+EventLocalPuber.yjs
 
 ::
 
-   contract EventPuber{
-       event abcEvent;
-       export function pub(arg){
-           abcEvent(arg);
-           return "done!";
-       }
-   }
+    contract EventLocalPuber {
+        event abcEvent;
+        // 等价于
+        // event local abcEvent
+        export function pub(arg){
+            abcEvent(arg);
+            return "done!";
+        }
+    }
 
-EventSuber.yjs
+EventLocalSuber.yjs
 
 ::
 
-   contract EventSuber{
-       export function init(arg){
-           YancloudUtil.subscribe("EventPuber","abcEvent",handler);
-           print("Handler:"+handler);
-       }
-       function handler(e){
-           var ret = "ReceiveEvent:"+(e.type)+" "+(e.content);
-           print(ret);
-       }
-   }
+    contract EventLocalSuber {
+        function onCreate() {
+            Global.topic2event = {};
+        }
+        export function init(arg) {
+            var topic = YancloudUtil.subscribe("EventPuber", "abcEvent", handler);
+            Global.topic2event[topic] = "abcEvent";
+            print("Handler:" + handler);
+        }
+        function handler(e) {
+            var ret = "ReceiveEvent: " + (Global.topic2event[e.topic]) + " " + (e.content);
+            print(ret);
+        }
+    }
+
+EventGlobalPuber.yjs
+
+::
+
+    contract EventGlobalPuber {
+        event global globalEvent;
+        export function pub(arg){
+            globalEvent(arg);
+            return "done!";
+        }
+    }
+
+EventGlobalSuber.yjs
+
+::
+
+    contract EventGlobalSuber {
+        export function init(arg) {
+            var topic = YancloudUtil.subscribe("globalEvent", handler);
+            print("Handler:" + handler);
+        }
+        function handler(e) {
+            var ret = "ReceiveEvent: " + (e.topic) + " " + (e.content);
+            print(ret);
+        }
+    }
+
+YJS的两种事件都支持事件语义：
+
+* 至少一次（AT_LEAST_ONCE）：事件至少被处理一次，该事件将被发送给所有订阅者。
+* 至多一次（AT_MOST_ONCE）：事件至多被处理一次，该事件只会被发送给一个随机的订阅者。
+* 只有一次（ONLY_ONCE）：该事件被且仅被一个合约订阅者处理一次。
+
+默认的事件语义为至少一次，其他事件语义需要在事件声明中指定，例如：
+
+::
+
+    event local alo(AT_LEAST_ONCE);
+    event global amo(AT_MOST_ONCE);
+    event global oo(ONLY_ONCE);
 
 --------------
 

source/conf.py

@@ -23,7 +23,6 @@ author = 'Peking University'
 # The full version, including alpha/beta/rc tags
 release = 'V1.0'
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -31,9 +30,9 @@ release = 'V1.0'
 # ones.
 
 html_theme = "sphinx_rtd_theme"
-html_logo="_static/imgs/logo.png"
+html_logo = "_static/imgs/logo.png"
 html_theme_options = {
-'logo_only': True
+    'logo_only': True
 }
 
 source_parsers = {
@@ -49,9 +48,9 @@ source_suffix = ['.rst', '.md']
 # }
 
 extensions = [
-	'recommonmark',
-	'sphinx_rtd_theme',
-	'sphinx_markdown_tables'
+    'recommonmark',
+    'sphinx_rtd_theme',
+    'sphinx_markdown_tables'
 ]
 
 html_favicon = "_static/imgs/favicon.ico"
@@ -70,13 +69,12 @@ language = 'zh_CN'
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-#html_theme = 'alabaster'
+# html_theme = 'alabaster'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,