FreeRTOS API Queue Set

https://www.freertos.org/xQueueCreateSet.html

xQueueCreateSet()
[Queue Set API]

queue.h

QueueSetHandle_t xQueueCreateSet
               (
                   const UBaseType_t uxEventQueueLength
               );

configUSE_QUEUE_SETS ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h สำหรับ the xQueueCreateSet() API function มีให้ใช้เป็นประโยชน์.

Queue sets จัดให้มี a mechanism เพื่อยอมให้ an RTOS task บล็อก (รอดำเนินการ) บน a read operation จากหลาย RTOS queues or semaphores พร้อมกัน. โปรดทราบว่ามีทางเลือกอื่นที่ง่ายกว่าในการใช้ queue sets. ดู the Blocking on Multiple Objects page สำหรับข้อมูลเพิ่มเติม.

A queue set ต้องถูกสร้างอย่างชัดแจ้งโดยใช้การเรียกถึง xQueueCreateSet() ก่อนที่มันสามารถถูกใช้. เมื่อสร้างแล้ว, standard FreeRTOS queues and semaphores สามารถูกเพิ่มไปยัง the set โดยใช้การเรียกถึง xQueueAddToSet(). xQueueSelectFromSet() ดังนั้นถูกใช้เพื่อตัดสินใจว่า, ถ้าใดๆ, ของ the queues or semaphores ที่บรรจุใน the set อยู่ใน a state ที่ a queue read or semaphore take operation จะประสบความสำเร็จ.

Notes:

     •  Queues and semaphores ต้องว่างเปล่าเมื่อพวกมันถูกเพิ่มไปยัง a queue set. ต้องระมัดระวังเป็นพิเศษเมื่อเพิ่ม objects อย่าง
         เช่น binary semaphores ซึ่งถูกสร้างด้วย the semaphore ที่มีให้ใช้ประโยชน์แล้ว [นี้เป็นกรณีที่ถ้า the semaphore ถูกสร้าง
        โดยใช้ the vSemaphoreCreateBinary() macro, แต่ไม่ใช่เป็นกรณีที่ถ้า the semaphore ถูกสร้างโดยใช้ the preferred(ที่
        ชอบมากกว่า) xSemaphoreCreateBinary() function].

     •  การบล็อกบน a queue set ที่บรรจุ a mutex จะไม่เป็นเหตุให้ the mutex holder รับช่วง the priority of the blocked task.

     •  RAM เพิ่มเติมอีก 4 bytes ถูกต้องการสำหรับแต่ละ space ในทุกๆ queue ที่เพิ่มไปยัง a queue set. ดังนั้น a counting
        semaphore ที่มี a high maximum count value ไม่ควรถูกเพิ่มไปยัง a queue set.

     •  A receive (ในกรณีของ a queue) หรือ take (ในกรณีของ a semaphore) operation ต้องไม่ถูกดำเนินการบน a member of
        a queue set เว้นแต่การเรียกไปยัง a call to xQueueSelectFromSet() ส่งคืนกลับแรก a handle ไปยัง set member นั้น.

Parameters:

     uxEventQueueLength   Queue sets เก็บ events ที่เกิดขึ้นบน the queues and semaphores ที่บรรจุใน the set.
                                              uxEventQueueLength ระบุ the maximum number of events ที่สามารถถูกวางคิวได้ในครั้ง
                                              เดียวthat can be queued at once.

                                              เพื่อให้แน่ใจอย่างแน่นอนว่า events จะไม่สูญหาย uxEventQueueLength ต้องถูกเซ็ตเป็นผลรวม
                                              ของความยาวของ the queues ที่เพิ่มไปยัง the set, โดยที่ binary semaphores และ
                                              mutexes มีความยาว 1, และ counting semaphores มีความยาวที่เซ็ตโดย maximum count
                                              value ของพวกมัน. ตัวอย่างเช่น:

                                                 •  ถ้า a queue set ต้องเก็บ a queue ที่มีความยาว 5, queue อีกตัวมีความยาว 12, และ a
                                                     binary semaphore, ดังนั้น uxEventQueueLength ควรถูกเซ็ตเป็น (5 + 12 + 1), หรือ
                                                     18.

                                                 •  ถ้า a queue set ต้องเก็บ three binary semaphores ดังนั้น uxEventQueueLength
                                                     ควรถูกเซ็ตเป็น (1 + 1 + 1 ), หรือ 3.

                                                 •  ถ้า a queue set ต้องเก็บ a counting semaphore ที่มี a maximum count of 5, และ
                                                     a counting semaphore ที่มี a maximum count of 3, ดังนั้น uxEventQueueLength
                                                     ควรถูกเซ็ตเป็น (5 + 3), หรือ 8.

Returns:

     ถ้า the queue set ถูกสร้างสำเร็จดังนั้น a handle to the created queue set จะถูกส่งคืนกลับ. ถ้าเป็นอย่างอื่น NULL จะถูกส่งคืน
     กลับ.

Example usage:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)
https://www.freertos.org/xQueueCreateSet.html

https://www.freertos.org/xQueueAddToSet.html

xQueueAddToSet()
[Queue Set API]

queue.h

BaseType_t xQueueAddToSet
                      (
                          QueueSetMemberHandle_t xQueueOrSemaphore,
                          QueueSetHandle_t xQueueSet
                      );

configUSE_QUEUE_SETS ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h สำหรับ the xQueueAddToSet() API function มีให้ใช้เป็นประโยชน์.

เพิ่ม an RTOS queue or semaphore ไปยัง a queue set ที่ถูกสร้างไว้ก่อนหน้าแล้วโดยการเรียกถึง xQueueCreateSet().

A receive (ในกรณีของ a queue) หรือ take (ในกรณีของ a semaphore) operation ต้องไม่ถูกดำเนินการบน a member of a queue set เว้นแต่การเรียกไปยัง xQueueSelectFromSet() ส่งคืนกลับแรก a handle to set member นั้น.

Parameters:

     xQueueOrSemaphore     The handle of the queue or semaphore ที่กำลังถูกเพิ่มไปยัง the queue set (cast to an
                                                 QueueSetMemberHandle_t type).

     xQueueSet                         The handle of the queue set ซึ่ง the queue or semaphore ที่กำลังถูกเพิ่มถึง.

Returns:

     ถ้า the queue or semaphore ถูกเพิ่มไปยัง the queue set สำเร็จแล้วดังนั้น pdPASS จะถูกส่งคืนกลับ. ถ้า the queue ไม่
     สามารถถูกเพิ่มไปยัง the queue set สำเร็จเนื่องจากมันเป็นสมาชิกของ queue set อื่นแล้วดังนั้น pdFAIL จะถูกส่งคืนกลับ.

Example usage:

ดูตัวอย่างบน the xQueueCreateSet() documentation page.

https://www.freertos.org/xQueueRemoveFromSet.html

xQueueRemoveFromSet()
[Queue Set API]

queue.h

BaseType_t xQueueRemoveFromSet
                      (
                          QueueSetMemberHandle_t xQueueOrSemaphore,
                          QueueSetHandle_t xQueueSet
                      );

configUSE_QUEUE_SETS ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h สำหรับ the xQueueRemoveFromSet() API function มีให้ใช้เป็นประโยชน์.

เอา an RTOS queue or semaphore ออกจาก a queue set.

An RTOS queue or semaphore สามารถถูกเอาออกจาก a queue set ได้เฉพาะถ้า the queue or semaphore ว่างเปล่า.

Parameters:

     xQueueOrSemaphore   The handle of the queue or semaphore ที่กำลังถูกเอาออกจาก the queue set (cast to an
                                         QueueSetMemberHandle_t type).

     xQueueSet                    The handle of the queue set ซึ่ง the queue or semaphore ถูกรวมใน.

Returns:

     ถ้า the queue or semaphore ถูกเอาออกจาก the queue set สำเร็จแล้วดังนั้น pdPASS จะถูกส่งคืนกลับ. ถ้า the queue ไม่ได้
     อยู่ใน the queue set, หรือ the queue (or semaphore) ไม่ว่างเปล่าอยู่, ดังนั้น pdFAIL จะถูกส่งคืนกลับ.

Example usage:

ตัวอย่างนี้ทึกทักเอาว่า xQueueSet เป็น a queue set ที่ถูกสร้างขึ้นแล้ว, และ xQueue เป็น a queue ที่ถูกสร้างขึ้นแล้วและถูกเพิ่มไปยัง xQueueSet.

https://www.freertos.org/xQueueSelectFromSet.html

xQueueSelectFromSet()
[Queue Set API]

queue.h

 QueueSetMemberHandle_t xQueueSelectFromSet
                       (
                             QueueSetHandle_t xQueueSet,
                             const TickType_t xTicksToWait
                        );

configUSE_QUEUE_SETS ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h สำหรับ the xQueueSelectFromSet() API function มีให้ใช้เป็นประโยชน์.

xQueueSelectFromSet() เลือกจาก the members of a queue set a queue or semaphore ที่อย่างใดอย่างหนึ่ง บรรจุ data (ในกรณีของ a queue) หรือมีให้ใช้ประโยชน์เพื่อ take (ในกรณีของ a semaphore). xQueueSelectFromSet() ยอมให้ a task บล็อก (รอดำเนินการ)  อย่างมีประสิทธิภาพบน a read operation บน the queues and semaphores ทั้งหมดใน a queue set พร้อมกัน.

Notes:

     •  โปรดทราบว่ามีทางเลือกอื่นที่ง่ายกว่าในการใช้ queue sets. ดู the Blocking on Multiple Objects page สำหรับข้อมูลเพิ่มเติม.

     •  การบล็อกบน a queue set ที่บรรจุ a mutex จะไม่เป็นเหตุให้ the mutex holder รับช่วง the priority of the blocked task.

     •  A receive (ในกรณีของ a queue) หรือ take (ในกรณีของ a semaphore) operation ต้องไม่ถูกดำเนินการบน a member of
        a queue set เว้นแต่การเรียกไปยัง a call to xQueueSelectFromSet() ส่งคืนกลับครั้งแรก a handle ไปยัง set member นั้น.

Parameters:

     xQueueSet          The queue set ซึ่ง the task จะ (มีศักยภาพ) บล็อก.

     xTicksToWait      The maximum time, เป็น ticks, ที่ the calling task จะยังคงอยู่ใน the Blocked state (โดยมี tasks อื่น
                                  กำลังปฏิบัติ) เพื่อรอสำหรับ a member of the queue set พร้อมสำหรับ a successful queue read or
                                  semaphore take operation.

Returns:

     xQueueSelectFromSet() จะส่งคืนกลับ the handle of a queue (cast to a QueueSetMemberHandle_t type) ที่บรรจุใน
     the queue set ที่บรรจุ data, หรือ the handle of a semaphore (cast to a QueueSetMemberHandle_t type) ที่บรรจุใน
     the queue set ที่มีให้ใช้ประโยชน์, หรือ NULL ถ้าไม่มี queue or semaphore ดังกล่าวมีอยู่ก่อนที่ the specified block time
     หมดเวลาลง.

Example usage:

ดูตัวอย่างบน the xQueueCreateSet() documentation page.