数据队列 Queue 的使用 （转）

数据队列

数据队列一般用于数据缓存，可以用来平衡速率不同的两个部件，使快速部件无需等待慢速部件。

数据队列一般是先入先出的，但本数据队列可以配置成后入先出。本数据队列是可配置可裁剪的模块，并且不依赖于操作系统，可以在前后台系统中使用。数据队列使用的空间由用户分配且由这个空间的地址唯一识别一个数据队列。

API函数

数据队列软件模块包括的API函数如下所示：

API函数名                                     功能简介

QueueCreate                                  建立数据队列

QueueRead                                    获取队列中的数据

QueueWrite                                   先进先出方式发送数据

QueueWriteFront                           后进先出方式发送数据

QueueFlush                                    清空队列

QueueNData                                  取得队列中已存储数据的数据

QueueSize                                       取得队列中总共可以存储的数据数目

/******************************************************************************************
** 文件名: queue.c
** 描 述: 数据队列的中间件
********************************************************************************************************/
#include "app_cfg.h"
#define IN_QUEUE

#define QUEUE_OK 1
#define NOT_OK 0
#define QUEUE_EMPTY 2
#define QUEUE_FULL 3
#define Q_WRITE_MODE 4
#define Q_WRITE_FRONT_MODE 5

#define QUEUE_DATA_TYPE INT8U

typedef struct {
    QUEUE_DATA_TYPE     *pOut;           /* 指向数据输出位置         */
    QUEUE_DATA_TYPE     *pIn;            /* 指向数据输入位置         */
    QUEUE_DATA_TYPE     *pEnd;           /* 指向Buf的结束位置        */
    uint16               nBytesPerRec;   /* 队列中每个记录包含数据个数           */
    uint16               nMaxRecNum;     /* 队列可以存储的记录数目 */
    uint16               nRecNum;        /* 队列中数据个数 */
    uint8               (* ReadEmpty)(); /* 读空处理函数*/            
    uint8               (* WriteFull)(); /* 写满处理函数             */
    QUEUE_DATA_TYPE     Buf[1];          /* 存储数据的空间           */
} DataQueue;


//SizeOfBuf是Buf的字节长度。
//QUEUE_DATA_TYPE是指可定义的数据类型可以Uint8,Uint32,等。
//Queue是DataQueue型结构体。

/*********************************************************************************************************
** 函数名称: QueueCreate
** 功能描述: 初始化数据队列
** 输 入: Buf ：为队列分配的存储空间地址
** SizeOfBuf：为队列分配的存储空间大小（字节）
** BytesPerRec: 队列每个记录占用字节数
** ReadEmpty：为队列读空时处理程序
** WriteFull：为队列写满时处理程序
** 输 出: NOT_OK:参数错误
** QUEUE_OK:成功
** 全局变量: 无
** 调用模块: OS_ENTER_CRITICAL,OS_EXIT_CRITICAL
********************************************************************************************************/
uint8 QueueCreate( void *Buf, uint32 SizeOfBuf, uint16 BytesPerRec,
uint8 (* ReadEmpty)(), uint8 (* WriteFull)() )
{
DataQueue *Queue;

if (Buf != NULL && SizeOfBuf >= (sizeof(DataQueue))) /* 判断参数是否有效 */
{
Queue = (DataQueue *)Buf;

/* 初始化结构体数据 */
OS_ENTER_CRITICAL();

Queue->nMaxRecNum = (SizeOfBuf - (uint32)(((DataQueue *)0)->Buf)) /
BytesPerRec; /* 计算队列可以存储的记录数目 */
Queue->pEnd = Queue->Buf + Queue->nMaxRecNum * BytesPerRec; /* 计算数据缓冲的结束地址 */
Queue->pOut = Queue->Buf;
Queue->pIn = Queue->Buf;
Queue->nRecNum = 0;
Queue->nBytesPerRec = BytesPerRec;
Queue->ReadEmpty = ReadEmpty;
Queue->WriteFull = WriteFull;

OS_EXIT_CRITICAL();

return QUEUE_OK;
}
else
{
return NOT_OK;
}
}


/*********************************************************************************************************
** 函数名称: QueueRead
** 功能描述: 获取队列中的数据
** 输 入: pRet:存储返回的记录数据的地址
** Buf:指向队列的指针
** 输 出: NOT_OK ：参数错误
** QUEUE_OK ：收到消息
** QUEUE_EMPTY：无消息
** 全局变量: 无
** 调用模块: OS_ENTER_CRITICAL,OS_EXIT_CRITICAL
********************************************************************************************************/
uint8 QueueRead(uint8 *pRet, void *Buf)
{
uint8 err;
uint16 i;
DataQueue *Queue;

err = NOT_OK;
if (Buf != NULL) /* 队列是否有效 */
{ /* 有效 */
Queue = (DataQueue *)Buf;

OS_ENTER_CRITICAL();

if (Queue->nRecNum > 0) /* 队列是否为空 */
{ /* 不空 */
for( i = 0; i < Queue->nBytesPerRec; i++ )
*pRet++ = *Queue->pOut++; /* 数据出队 */
/* 调整出队指针 */
if (Queue->pOut >= Queue->pEnd)
{
Queue->pOut = Queue->Buf;
}
Queue->nRecNum--; /* 数据减少*/
err = QUEUE_OK;
}
else
{ /* 空 */
err = QUEUE_EMPTY;
if (Queue->ReadEmpty != NULL) /* 调用用户处理函数 */
{
err = Queue->ReadEmpty(pRet, Queue);
}
}

OS_EXIT_CRITICAL();
}
return err;
}

/*********************************************************************************************************
** 函数名称: QueueWrite
** 功能描述: FIFO方式发送数据
** 输 入: Buf :指向队列的指针
** pRec:写入记录的首地址
** 输 出: NOT_OK :参数错误
** QUEUE_FULL:队列满
** QUEUE_OK :发送成功
** 全局变量: 无
** 调用模块: OS_ENTER_CRITICAL,OS_EXIT_CRITICAL
********************************************************************************************************/
uint8 QueueWrite(void *Buf, uint8* pRec)
{
uint8 err;
uint16 i;
DataQueue *Queue;

err = NOT_OK;
if (Buf != NULL) /* 队列是否有效 */
{
Queue = (DataQueue *)Buf;

OS_ENTER_CRITICAL();

if (Queue->nRecNum < Queue->nMaxRecNum) /* 队列是否满 */
{ /* 不满 */
for( i = 0; i < Queue->nBytesPerRec; i++ )
*Queue->pIn++ = *pRec++; /* 数据入队 */
/* 调整入队指针 */
if (Queue->pIn >= Queue->pEnd)
{
Queue->pIn = Queue->Buf;
}
Queue->nRecNum++; /* 数据增加 */
err = QUEUE_OK;
}
else
{ /* 满 */
err = QUEUE_FULL;
if (Queue->WriteFull != NULL) /* 调用用户处理函数 */
{
err = Queue->WriteFull(Queue, *pRec, Q_WRITE_MODE);
}
}
OS_EXIT_CRITICAL();
}
return err;
}

/*********************************************************************************************************
** 函数名称: QueueWriteFront
** 功能描述: LIFO方式发送数据
** 输 入: Buf:指向队列的指针
** pRec:写入记录的首地址
** 输 出: QUEUE_FULL:队列满
** QUEUE_OK:发送成功
** 全局变量: 无
** 调用模块: OS_ENTER_CRITICAL,OS_EXIT_CRITICAL
********************************************************************************************************/

uint8 QueueWriteFront(void *Buf, uint8 *pRec)
{
uint8 err;
uint16 i;
DataQueue *Queue;

err = NOT_OK;
if (Buf != NULL) /* 队列是否有效 */
{
Queue = (DataQueue *)Buf;

OS_ENTER_CRITICAL();

if (Queue->nRecNum < Queue->nMaxRecNum) /* 队列是否满 */
{ /* 不满 */
Queue->pOut--; /* 调整出队指针 */
if (Queue->pOut < Queue->Buf)
{
Queue->pOut = Queue->pEnd - 1;
}

for( i = 0; i < Queue->nBytesPerRec; i++ ) /* 不满 */
*Queue->pOut-- = *( pRec + Queue->nBytesPerRec - 1 - i ); /* 数据入队 */
Queue->pOut++;
Queue->nRecNum++; /* 数据数目增加 */
err = QUEUE_OK;
}
else
{ /* 满 */
err = QUEUE_FULL;
if (Queue->WriteFull != NULL) /* 调用用户处理函数 */
{
err = Queue->WriteFull(Queue, *pRec, Q_WRITE_FRONT_MODE);
}
}

OS_EXIT_CRITICAL();
}
return err;
}


/*********************************************************************************************************
** 函数名称: QueueRecNum
** 功能描述: 取得队列中记录数
** 输 入: Buf:指向队列的指针
** 输 出: 消息数
** 全局变量: 无
** 调用模块: OS_ENTER_CRITICAL,OS_EXIT_CRITICAL
********************************************************************************************************/
uint16 QueueRecNum(void *Buf)
{
uint16 temp;

temp = 0; /* 队列无效返回0 */
if (Buf != NULL)
{
OS_ENTER_CRITICAL();
temp = ((DataQueue *)Buf)->nRecNum;
OS_EXIT_CRITICAL();
}
return temp;
}

/*********************************************************************************************************
** 函数名称: QueueMaxRecNum
** 功能描述: 取得队列记录总容量
** 输 入: Buf:指向队列的指针
** 输 出: 队列记录总容量
** 全局变量: 无
** 调用模块: OS_ENTER_CRITICAL,OS_EXIT_CRITICAL
********************************************************************************************************/
uint16 QueueMaxRecNum(void *Buf)
{
uint16 temp;

temp = 0; /* 队列无效返回0 */
if (Buf != NULL)
{
OS_ENTER_CRITICAL();
temp = ((DataQueue *)Buf)->nMaxRecNum;
OS_EXIT_CRITICAL();
}
return temp;
}

/*********************************************************************************************************
** 函数名称: OSQFlush
** 功能描述: 清空队列
** 输 入: Buf:指向队列的指针
** 输 出: 无
** 全局变量: 无
** 调用模块: OS_ENTER_CRITICAL,OS_EXIT_CRITICAL
********************************************************************************************************/
void QueueFlush(void *Buf)
{
DataQueue *Queue;

if (Buf != NULL) /* 队列是否有效 */
{ /* 有效*/
Queue = (DataQueue *)Buf;
OS_ENTER_CRITICAL();
Queue->pOut = Queue->Buf;
Queue->pIn = Queue->Buf;
Queue->nRecNum = 0; /* 数据数目为0 */
OS_EXIT_CRITICAL();
}
}