分享一個基于事件驅動的有限狀態機

一、介紹

EFSM(event finite state machine，事件驅動型有限狀態機)，是一個基于事件驅動的有限狀態機，主要應用于嵌入式設備的軟件系統中。

EFSM的設計原則是：簡單！EFSM的使用者只需要關心：

1. 當事件到來時，通過EFSM取得對應事件的處理方法；
2. 當特定事件到來，或者條件滿足時，調用狀態切換方法進行狀態切換。

由于EFSM的巧妙設計，避免了命名沖突的問題，你可以在一個程序中定義多個狀態機；要是能對不同狀態進行組織，還可以做出層次狀態機的結構。

EFSM總共分為兩個部分：

• EFSM核心：由uthash.h、efsm.h和efsm_conf.h三個文件組成；他們構成了事件驅動型狀態機的核心；使用的時候只需要包含efsm.h即可；
• EFSM擴展：在EFSM核心的基礎上，增加efsmt.h和efsmt.c兩個文件，這兩個文件會根據具體的狀態機創建狀態機線程，用于驅動狀態機運轉；使用的時候只需要包含efsmt.h即可；

二、接口總覽

EFSM總共提供了兩套接口，你只需要選擇其中套用法即可。全部接口概述如下：

2.1 使用狀態機工具集（EFSM核心）

若你想自己把控狀態機的整個運轉過程，可以直接使用EFSM核心，詳細接口如下。

1. 狀態操作接口

2. 狀態指針操作接口

3. 狀態切換接口

4. 獲取處理函數接口

2.2 使用狀態機

若你不關心狀態機的內部細節實現，需要一個可直接運轉的狀態機，那么請使用efsmt.h頭文件，并將efsmt.c編譯進你的源碼。詳細接口如下。

1. 狀態操作接口

2. 狀態機操作接口

3. 狀態切換接口

4. 觸發事件接口

2.3 總結

從接口可以看出，創建處理集與狀態集，和狀態切換方法是完全一樣的；兩種方法的唯一差異就是：當事件來了之后，事件對應的處理是由你來控制，還是由狀態機內部進行控制。

三、使用說明

要使用EFSM，非常簡單，只需要如下三步：定義事件集、定義狀態集、使用狀態集。

3.1 定義事件集

在我們設計業務/功能時，首先對需要使用到的事件進行定義。具體實現方法是在efsm_event.h文件中，使用EFSM_EVENT()宏定義需要的事件。如果你需要定義多個狀態機，那請將不同狀態機的事件分塊保存，建議使用enum進行管理。比如：

enum {
  EVENT_PLAY  = EFSM_EVENT(1),
  EVENT_STOP  = EFSM_EVENT(2),
  EVENT_NEXT  = EFSM_EVENT(3),
  EVENT_PREV  = EFSM_EVENT(4),
  EVENT_START = EFSM_EVENT(7),    //not require continuous
 };

3.2 定義狀態集

1. 定義狀態：使用EFSM_CREATE(state)創建一個狀態state；在其它使用到它的地方用EFSM_DECLEAR(state)宏進行聲明；
2. 定義處理集：使用EFSM_SETS state_sets定義一個狀態集合state_sets，其中每個事件可以對應一個處理函數，也可以對應多個函數，當然也可以為NULL；處理函數需滿足如下格式：

typedef void (*EFSM_EVENT_HANDLER)(EFSM_EVENT_TYPE event, void *arg);

3. 綁定狀態與處理集：在模塊初始化函數中調用EFSM_BIND(state, sets)宏將狀態state與處理集sets進行綁定；

3.3 使用狀態集

當為模塊/產品實現了所有的狀態，那么編寫業務應用程序來實現調度，讓所有的狀態機完美的運作起來。具體使用方法如下：

1. 定義狀態指針：使用EFSM_PTR_CREATE(name)定義一個狀態指針name；當然你也可以定義多個狀態指針，每個指針對應一個狀態機。在其它使用到該狀態指針的地方使用EFSM_PTR_DECLEAR(name)宏進行聲明；
2. 綁定初始狀態：在整個狀態機運作之前，需要使用EFSM_PTR_BIND(name, state)宏將狀態指針name與狀態state進行綁定；
3. 獲取處理函數指針：當接收到某個事件時，可以通過EFSM_HANDLER(name,event)宏從狀態指針name中獲取對該事件的處理方法，第一個參數是狀態指針，第二個參數為事件；
4. 狀態切換：當遇到某個事件，或者在事件處理函數中條件滿足，需要進行狀態切換時，使用下面流程進行切換：

    EFSM_TRANSFER_ENABLE(name);
    EFSM_TRANSFER(name, state);
    EFSM_TRANSFER_DISABLE(name);

• EFSM_TRANSFER_ENABLE(name)宏使能狀態指針name的切換能力；
• EFSM_TRANSFER_DISABLE(name)宏除能狀態指針name的切換能力；
• EFSM_TRANSFER(name, state)宏執行狀態指針name切換到state；

注意：做狀態切換時，必須滿足ENABLE()->TRANSFER()->DISABLE()的流程。這么做的目的，是為了讓編程者思考：狀態設計與狀態的跳轉是否必要與合理。

四、常見問題

1. 使用過程中若遇到如下錯誤，是因為在正式使用前，沒有把狀態指針綁定到具體的狀態：

EFSM: cur-state-ptr have't bind a state: %xxx!!!

2. 使用過程中若遇到如下錯誤，是因為狀態切換動作不滿足ENABLE()->TRANSFER()->DISABLE()的流程：

EFSM: 'xxx' switch to 'xxx' failed!!!

3. 使用過程中，若遇到了死鎖或卡死，是因為狀態切換動作不滿足ENABLE()->TRANSFER()->DISABLE()的流程：
4. 命名定義了處理函數，為什么每次EFSM_HANDLER()得到的都是NULL？答：因為你沒有將狀態與事件集進行綁定。
5. 對于某個狀態沒有使用到的事件，我是否可以不對其定義？答：完全可以，這樣還可以加快EFSM的處理速度。不過不建議直接刪除，而采用注釋的形式，比如：

EFSM_SETS online[] = { {EVENT_PLAY, online_play},
                        /*{EVENT_STOP, NULL}, */
                        {EVENT_NEXT, online_next},
                        /*{EVENT_PREV, NULL}, */
                        {EVENT_START, online_start},
                      };