chore(docs): update docs for span module

docs/Melon Developer Guide.txt

@@ -3141,6 +3141,28 @@ Their definitions can be found in melon/include/mln_types.h.
          `args` is a argument list (without data type) divided by comma and quoted by parenthese.
          `func_body` is the function body.
 
+   47) Span
+       This module is used to test function performance, especially time consumption.
+       This module should be used with `Function` module.
+
+      a) mln_span_start();
+         Start to collect functions' time consumption.
+
+      b) mln_span_stop();
+         Stop to collect functions' information.
+
+      c) mln_span_release();
+         Release span memory.
+
+      d) mln_span_move();
+         Get span object and reset global variable in span module used by `mln_span_start`.
+
+      e) mln_span_dump();
+         Dump all information of spans indicated by the global variable in span module.
+
+      f) void mln_span_free(mln_span_t *span);
+         Free the give span object memory.
+
 5. Framework Usage
    It is very easy to use this framework. Before we use it, we have to initialize it.
    1) include header file.

docs/book/README.md

@@ -37,6 +37,7 @@ Melon currently provides the following components:
   - Cron Format Parser
   - Spin Lock
   - Prime Generator
+  - Span
 - Data Structures
   - Doubly Linked List
   - Fibonacci Heap

docs/book/SUMMARY.md

@@ -29,6 +29,7 @@
      - [Cron Format Parser](en/cron.md)
      - [Spin Lock](en/spinlock.md)
      - [Prime Generator](en/prime.md)
+     - [Span](en/span.md)
    - [Data Structures](en/datastruct.md)
      - [Doubly Linked List](en/double_linked_list.md)
      - [Fibonacci Heap](en/fheap.md)
@@ -82,6 +83,7 @@
      - [Cron格式解析器](cn/cron.md)
      - [自旋锁](cn/spinlock.md)
      - [素数生成器](cn/prime.md)
+     - [资源开销](cn/span.md)
    - [数据结构](cn/datastruct.md)
      - [双向链表](cn/double_linked_list.md)
      - [斐波那契堆](cn/fheap.md)

docs/book/cn/components.md

@@ -28,4 +28,5 @@ Melon库中实现了很多的常用组件，如下所示：
 - 里德所罗门编码
 - Cron格式解析器
 - 自旋锁
-- 素数生成器
+- 素数生成器
+- 资源开销

docs/book/cn/index.md

@@ -38,6 +38,7 @@ Melon当前提供了如下功能：
   - Cron格式解析器
   - 自旋锁
   - 素数生成器
+  - 资源开销
 - 数据结构
   - 双向链表
   - 斐波那契堆

docs/book/cn/span.md

@@ -0,0 +1,262 @@
+## 资源开销
+
+
+
+Melon中的资源开销（span）组件是用来测量C语言函数开销的，这个模块需要配合`函数模板`模块一同使用，因此也需要定义`MLN_FUNC_FLAG`才会使得函数模板功能启用，进而实现函数开销的跟踪。
+
+目前支持的开销如下：
+
+- 时间开销
+
+
+
+### 头文件
+
+```c
+#include "mln_span.h"
+```
+
+
+
+### 模块名
+
+`span`
+
+
+
+### 函数/宏
+
+
+
+#### mln_span_start
+
+```c
+mln_span_start();
+```
+
+描述：开始进行测量。这个宏函数中会对模块使用的全局变量进行设置，并且在测量过程中会仅跟踪调用该函数的线程所调用的函数。
+
+**注意：**这个宏函数需要与`mln_span_stop`宏函数在统一作用域内调用，或者`mln_span_stop`调用点的调用栈深度应大于`mln_span_start`调用点的调用栈深度。举例：
+
+> 如果有如下三个函数：`main`，`foo`，`bar`。他们之间的调用关系如下：
+>
+> ```c
+> void bar(void)
+> {
+> }
+> void foo(void)
+> {
+>   bar();
+> }
+> int main(void)
+> {
+>   foo();
+>   return 0;
+> }
+> ```
+>
+> 那么假设`mln_span_start`在`foo`的`bar`调用前被调用，那么`mln_span_stop`应该在`foo`的`mln_span_start`之后或者在`bar`函数中调用，但不能在`main`中调用。
+
+如果不遵守上述规则，则可能出现内存泄漏的情况。
+
+返回值：无
+
+
+
+#### mln_span_stop
+
+```c
+mln_span_stop();
+```
+
+描述：停止进行测量。这个宏函数会销毁部分模块内的全局变量内容，但会保留此次测量中包含测量值的结构。这个宏函数的调用时机参考`mln_span_start`中的描述。
+
+返回值：无
+
+
+
+#### mln_span_release
+
+```c
+mln_span_release();
+```
+
+描述：释放本次测量的测量值结构。**注意：**这个宏函数应在`mln_span_stop`之后被调用，否则将可能出现内存访问异常。
+
+返回值：无
+
+
+
+#### mln_span_move
+
+```c
+mln_span_move();
+```
+
+描述：获取本次测量的测量值结构，并将指向该结构的全局指针置`NULL`。**注意：**这个宏函数应在`mln_span_stop`之后被调用，否则将出现不可预知的错误。
+
+返回值：`mln_span_t`指针
+
+
+
+#### mln_span_dump
+
+```c
+mln_span_dump();
+```
+
+描述：输出当前测量的数据。
+
+返回值：无
+
+
+
+#### mln_span_free
+
+```c
+void mln_span_free(mln_span_t *s);
+```
+
+描述：释放`mln_span_t`结构内存。
+
+返回值：无
+
+
+
+### 示例
+
+这是一个多线程的示例，用来展示`mln_span`接口的使用以及在多线程环境下的效果。
+
+```c
+//a.c
+
+#include <pthread.h>
+#include "mln_span.h"
+#include "mln_func.h"
+
+MLN_FUNC(int, abc, (int a, int b), (a, b), {
+    return a + b;
+})
+
+MLN_FUNC(static int, bcd, (int a, int b), (a, b), {
+    return abc(a, b) + abc(a, b);
+})
+
+MLN_FUNC(static int, cde, (int a, int b), (a, b), {
+    return bcd(a, b) + bcd(a, b);
+})
+
+void *pentry(void *args)
+{
+    int i;
+    mln_span_start();
+    for (i = 0; i < 10; ++i) {
+        cde(i, i + 1);
+    }
+
+    mln_span_stop();
+    mln_span_dump();
+    mln_span_release();
+    return NULL;
+}
+
+int main(void)
+{
+    int i;
+    pthread_t pth;
+
+
+    pthread_create(&pth, NULL, pentry, NULL);
+
+    for (i = 0; i < 10; ++i) {
+        bcd(i, i + 1);
+    }
+
+    pthread_join(pth, NULL);
+
+    return 0;
+}
+```
+
+编译程序：
+
+```bash
+cc -o a a.c -I /usr/local/melon/include/ -L /usr/local/melon/lib/ -lmelon -DMLN_FUNC_FLAG -lpthread
+```
+
+执行后可以看到如下输出：
+
+```
+| pentry at a.c:20 takes 92 (us)
+  | cde at a.c:13 takes 4 (us)
+    | bcd at a.c:9 takes 1 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+    | bcd at a.c:9 takes 1 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+  | cde at a.c:13 takes 5 (us)
+    | bcd at a.c:9 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+    | bcd at a.c:9 takes 2 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+  | cde at a.c:13 takes 24 (us)
+    | bcd at a.c:9 takes 1 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+    | bcd at a.c:9 takes 21 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+  | cde at a.c:13 takes 5 (us)
+    | bcd at a.c:9 takes 1 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+    | bcd at a.c:9 takes 1 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+  | cde at a.c:13 takes 3 (us)
+    | bcd at a.c:9 takes 2 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+    | bcd at a.c:9 takes 1 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+  | cde at a.c:13 takes 30 (us)
+    | bcd at a.c:9 takes 24 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 1 (us)
+    | bcd at a.c:9 takes 6 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+  | cde at a.c:13 takes 3 (us)
+    | bcd at a.c:9 takes 2 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+    | bcd at a.c:9 takes 1 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+  | cde at a.c:13 takes 3 (us)
+    | bcd at a.c:9 takes 2 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 1 (us)
+    | bcd at a.c:9 takes 1 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+  | cde at a.c:13 takes 7 (us)
+    | bcd at a.c:9 takes 1 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+    | bcd at a.c:9 takes 2 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 1 (us)
+  | cde at a.c:13 takes 3 (us)
+    | bcd at a.c:9 takes 2 (us)
+      | abc at a.c:5 takes 1 (us)
+      | abc at a.c:5 takes 0 (us)
+    | bcd at a.c:9 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+      | abc at a.c:5 takes 0 (us)
+```
+

docs/book/en/components.md

@@ -29,3 +29,4 @@ There are many components provided by Melon Library.
 - Cron Format Parser
 - Spin Lock
 - Prime Generator
+- Span