SylixOS 異步工作隊列
1、概述
本篇主要介紹SylixOS中異步工作隊列（JobQueue）的原理及相關函數接口。
2、簡介
異步工作隊列是SylixOS中將工作推後執行的一種機制，該機制將推後的工作交由一個內核工作線程去執行，其特點在於它允許重新調度甚至睡眠。
3、數據結構及相關接口函數
SylixOS中關於異步工作隊列的相關數據結構和接口函數定義位於內核文件"libsylixos/SylixOS/kernel/core/_JobQueue.c"中。
3.1數據結構
SylixOS內核中定義了兩個用於管理工作隊列的數據結構。
1、工作隊列管理的消息
#include <SylixOS.h>
typedef struct {
VOIDFUNCPTR JOBM_pfuncFunc;
PVOID JOBM_pvArg[LW_JOB_ARGS];
} LW_JOB_MSG;JOBM_pfuncFunc：工作消息的回調函數；
JOBM_pvArg[LW_JOB_ARGS]：工作消息的回調函數的參數。
2、工作隊列控制塊
#include <SylixOS.h>
typedef struct {
PLW_JOB_MSG JOBQ_pjobmsgQueue;
UINT JOBQ_uiIn;
UINT JOBQ_uiOut;
UINT JOBQ_uiCnt;
UINT JOBQ_uiSize;
size_t JOBQ_stLost;
LW_OBJECT_HANDLE JOBQ_ulSync;
LW_SPINLOCK_DEFINE (JOBQ_slLock);
} LW_JOB_QUEUE;JOBQ_pjobmsgQueue：工作隊列消息；
JOBQ_uiIn：加入工作隊列的消息數量；
JOBQ_uiOut：移出工作隊列的消息數量；
JOBQ_uiCnt：當前工作隊列中的消息數量；
JOBQ_uiSize：工作隊列總大小；
JOBQ_stLost：工作隊列丟失消息數量；
JOBQ_ulSync：工作隊列同步等待信號；
JOBQ_slLock：鎖定工作隊列自旋鎖。
3.2創建及刪除工作隊列
SylixOS中創建工作隊列就是分配工作隊列資源和初始化工作隊列控制塊中各成員的過程，與之對應，刪除隊列就是釋放工作隊列資源的過程。內核中提供了兩種工作隊列的創建和刪除操作函數：動態/靜態創建和刪除工作隊列。
3.2.1動態創建及刪除
1、動態創建工作隊列
#include <SylixOS.h> PLW_JOB_QUEUE _jobQueueCreate (UINT uiQueueSize, BOOL bNonBlock)；
函數_jobQueueCreate原型分析：
此函數成功返回工作隊列控制塊，失敗返回LW_NULL；
參數uiQueueSize是隊列大小；
參數bNonBlock是判斷執行函數是否為非阻塞方式。
2、刪除一個工作隊列
#include <SylixOS.h> VOID _jobQueueDelete (PLW_JOB_QUEUE pjobq)；
函數_jobQueueDelete原型分析：
此函數無返回值；
參數pjobq是工作隊列控制塊。
3.2.2靜態創建及刪除
1、靜態創建工作隊列
#include <SylixOS.h>
ULONG _jobQueueInit (PLW_JOB_QUEUE pjobq,
PLW_JOB_MSG pjobmsg,
UINT uiQueueSize,
BOOL bNonBlock)；函數_jobQueueInit原型分析：
此函數成功返回ERROR_NONE，輸出工作隊列控制塊，失敗返回錯誤號；
參數pjobq是需要初始化的工作隊列控制塊；
參數pjobmsg是消息緩沖區；
參數uiQueueSize是隊列大小；
參數bNonBlock是判斷執行函數是否為非阻塞方式。
2、靜態銷毀工作隊列
#include <SylixOS.h> VOID _jobQueueFinit (PLW_JOB_QUEUE pjobq)；
函數_ jobQueueFinit原型分析：
此函數無返回值；
參數pjobq是工作隊列控制塊。
3.3清空工作隊列
清空工作隊列的操作就是將指定工作隊列控制塊中的同步等待信號量清除，同時將工作隊列的入隊計數、出隊計數和當前工作隊列中消息數全部清零。
#include <SylixOS.h> VOID _jobQueueFlush (PLW_JOB_QUEUE pjobq)；
函數_ jobQueueFlush原型分析：
此函數無返回值；
參數pjobq是工作隊列控制塊。
3.4添加工作
向一個工作隊列中添加一個工作就是將一個工作消息保存到工作隊列的消息管理成員，同時將該工作需要執行的回調函數及其參數保存到消息控制塊中。
#include <SylixOS.h>
ULONG _jobQueueAdd (PLW_JOB_QUEUE pjobq,
VOIDFUNCPTR pfunc,
PVOID pvArg0,
PVOID pvArg1,
PVOID pvArg2,
PVOID pvArg3,
PVOID pvArg4,
PVOID pvArg5)；函數_ jobQueueAdd原型分析：
此函數成功返回ERROR_NONE，失敗返回錯誤號；
參數pjobq是工作隊列控制塊；
參數pfunc是該工作消息的回調函數；
參數pvArg0 ~ 5是回調函數的參數。
3.5刪除工作
刪除工作隊列中某一工作就是遍歷工作隊列消息列表，根據函數名及其參數個數匹配，將該工作的回調函數置空。
#include <SylixOS.h>
VOID _jobQueueDel (PLW_JOB_QUEUE pjobq,
UINT uiMatchArgNum,
VOIDFUNCPTR pfunc,
PVOID pvArg0,
PVOID pvArg1,
PVOID pvArg2,
PVOID pvArg3,
PVOID pvArg4,
PVOID pvArg5)；函數_ jobQueueDel原型分析：
此函數無返回值；
參數pjobq是工作隊列控制塊；
參數uiMatchArgNum是匹配參數的個數；
參數pfunc是該工作消息的回調函數；
參數pvArg0 ~ 5是回調函數的參數。
3.6獲得丟失消息數量
當工作隊列控制塊中當前消息數量JOBQ_uiCnt等於工作隊列總大小JOBQ_uiSize時，若此時又要向該工作隊列中添加新的工作消息，則該工作消息會丟失並且丟失消息數量JOBQ_stLost將會加1，因此獲取工作隊列控制塊的JOBQ_stLost的值即可獲得當前丟失的消息數量。
#include <SylixOS.h> size_t _jobQueueLost (PLW_JOB_QUEUE pjobq)；
函數_ jobQueueDel原型分析：
此函數返回當前丟失消息數量；
參數pjobq是工作隊列控制塊。
3.7執行工作
調用_jobQueueExec即可執行工作隊列中的工作，其詳細描述如下：
#include <SylixOS.h> ULONG _jobQueueExec (PLW_JOB_QUEUE pjobq, ULONG ulTimeout)；
函數_ jobQueueExec原型分析：
此函數成功返回ERROR_NONE，失敗返回ERROR_THREAD_WAIT_TIMEOUT；
參數pjobq是工作隊列控制塊；
參數ulTimeout是等待超時時間。
執行工作隊列中的工作就是判斷工作隊列中是否存在工作消息，若存在，則依次執行工作消息的回調函數，直至工作隊列中的消息數量減為0。執行工作的具體流程如圖 3.1所示。
圖 3.1 異步工作隊列執行工作流程
SylixOS 異步工作隊列