文档队列

已更新 2025年6月

xQueuePeek

[队列管理 ]

queue.h

1 BaseType_t xQueuePeek(
2 QueueHandle_t xQueue,
3 void *pvBuffer,
4 TickType_t xTicksToWait
5 );

Copy

这是一个调用 xQueueGenericReceive() 函数的宏。

从队列中接收项目，而无须从队列中删除该项目。 项目由副本接收，因此必须提供适当大小的缓冲区 。队列创建时，复制到缓冲区中的字节数已定义 。

成功接收的项目仍在队列中，因此将由下一次调用再次返回 或 xQueueReceive () 调用。

中断服务例程中不得使用此宏。

参数：

• xQueue

  要从中接收项目的队列的句柄。

• pvBuffer

  指向缓冲区的指针，接收到的项目将被复制到这个缓冲区。它必须至少足够大， 才能容纳创建队列时定义的队列项的大小。

• xTicksToWait

  如果在调用时队列为空， 则任务应阻塞等待项目接收的最长时间。时间是以滴答周期为单位定义的，因此如果需要，应使用常量 portTICK_PERIOD_MS 转换为实时。
  如果 INCLUDE_vTaskSuspend 设置为 “1”，则将阻塞时间指定为 portMAX_DELAY 会导致任务 无限期地阻塞（没有超时）。

返回：

如果从队列中成功接收（窥视）项目，则返回 pdTRUE，否则返回 pdFALSE。

用法示例：

1struct AMessage
2{
3    char ucMessageID;
4    char ucData[ 20 ];
5} xMessage;
6
7QueueHandle_t xQueue;
8
9// Task to create a queue and post a value.
10void vATask( void *pvParameters )
11{
12struct AMessage *pxMessage;
13
14    // Create a queue capable of containing 10 pointers to AMessage structures.
15    // These should be passed by pointer as they contain a lot of data.
16    xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
17    if( xQueue == 0 )
18    {
19        // Failed to create the queue.
20    }
21
22    // ...
23
24    // Send a pointer to a struct AMessage object.  Don't block if the
25    // queue is already full.
26    pxMessage = & xMessage;
27    xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );
28
29    // ... Rest of task code.
30}
31
32// Task to peek the data from the queue.
33void vADifferentTask( void *pvParameters )
34{
35struct AMessage *pxRxedMessage;
36
37    if( xQueue != 0 )
38    {
39        // Peek a message on the created queue.  Block for 10 ticks if a
40        // message is not immediately available.
41        if( xQueuePeek( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )
42        {
43            // pcRxedMessage now points to the struct AMessage variable posted
44            // by vATask, but the item still remains on the queue.
45        }
46    }
47
48    // ... Rest of task code.
49}

Copy