---
# System prepended metadata

title: ThreadX_2.2

---



## 訊息佇列 (Message Queues)
訊息佇列是 ThreadX 中用於執行緒間通訊的重要工具。它允許執行緒以先進先出的方式傳遞訊息。透過訊息佇列，可以有效管理執行緒間的資料共享與同步，實現高效的通訊模式。
#### 建立訊息佇列 (Creating Message Queues)

使用 tx_queue_create 建立訊息佇列，數量無限制。
每個佇列需指定訊息大小（最大64-Byte）。
若訊息超過64-Byte，應使用指標傳遞完整訊息(使用一個32-bit word來存放指標)。

相關 API:
```c=
// 建立佇列
tx_queue_create(TX_QUEUE *queue_ptr, CHAR *name_ptr,
                UINT message_size, VOID *queue_start, ULONG queue_size);
```

#### 佇列容量 (Queue Capacity)

佇列容量由訊息大小及提供的記憶體大小決定。
計算公式: 總記憶體字節數 ÷ 每條訊息的字節數。
例如:訊息大小為 4-byte，記憶體大小為 100-byte，則容量為 25 條訊息。

#### 執行緒掛起 (Thread Suspension)

掛起條件:

接收空佇列的訊息
傳送訊息至已滿佇列
執行緒會進入掛起狀態，並按 FIFO 順序 恢復。
使用 tx_queue_prioritize 可改變順序，將最高優先級執行緒移至最前。
支援超時: 設定執行緒的最大掛起時間，超時後返回錯誤代碼。

相關 API:

```c=
// 從佇列接收訊息
tx_queue_receive(TX_QUEUE *queue_ptr, VOID *destination_ptr, ULONG wait_option);
// 傳送訊息至佇列
tx_queue_send(TX_QUEUE *queue_ptr, VOID *source_ptr, ULONG wait_option);
// 調整佇列中訊息的優先順序
tx_queue_prioritize(TX_QUEUE *queue_ptr);
```
#### 佇列傳送通知 (Queue Send Notification)

註冊應用程式通知函數，當有訊息傳送至佇列時觸發通知。
通知函數內可處理新增的訊息，或恢復相應執行緒。

相關 API:

```c=
// 設定佇列傳送通知回呼
tx_queue_send_notify(TX_QUEUE *queue_ptr, VOID (*queue_send_notify)(TX_QUEUE *));
```
#### 其他功能

清空佇列: 使用 tx_queue_flush 清空所有訊息。
獲取資訊: 使用 tx_queue_info_get 查詢佇列當前狀態（名稱、訊息數量等）。
效能分析: 使用 tx_queue_performance_info_get 或 tx_queue_performance_system_info_get 獲取效能數據。

相關 API:

```c=
// 清空佇列
tx_queue_flush(TX_QUEUE *queue_ptr);
// 獲取佇列資訊
tx_queue_info_get(TX_QUEUE *queue_ptr, CHAR **name, ULONG *enqueued,
                  ULONG *available_storage, TX_THREAD **first_suspended,
                  ULONG *suspended_count, TX_QUEUE **next_queue);
// 獲取佇列效能資訊
tx_queue_performance_info_get(TX_QUEUE *queue_ptr, ULONG *messages_sent,
                              ULONG *messages_received, ULONG *empty_suspensions,
                              ULONG *full_suspensions, ULONG *full_errors,
                              ULONG *timeouts);
// 獲取全域佇列效能資訊
tx_queue_performance_system_info_get(ULONG *messages_sent, ULONG *messages_received,
                                     ULONG *empty_suspensions, ULONG *full_suspensions,
                                     ULONG *full_errors, ULONG *timeouts);
```

## 信號燈 (Semaphores)
信號燈是 ThreadX 提供的一種用於執行緒同步與資源管理的核心工具。它通過計數機制實現執行緒間的協作，常被用於事件通知與互斥操作。
#### 計數信號燈 (Counting Semaphores)

功能: 使用 32 位計數器來追蹤資源的可用性或事件的觸發狀態。
範圍: 計數值範圍為 0 至 4,294,967,295。
操作:
tx_semaphore_get: 減少計數，當計數為 0 時執行緒進入掛起狀態。
tx_semaphore_put: 增加計數，並恢復掛起的執行緒（若有）。
![image](https://hackmd.io/_uploads/S1KW_aUSJg.png)



相關 API:
```c=
// 取得信號量
tx_semaphore_get(TX_SEMAPHORE *semaphore_ptr, ULONG wait_option);
// 釋放信號量
tx_semaphore_put(TX_SEMAPHORE *semaphore_ptr);
```
#### 建立與刪除信號燈

建立: 使用 tx_semaphore_create 定義信號燈名稱及初始計數值。
刪除: 使用 tx_semaphore_delete 清除信號燈，釋放相關資源。

相關 API:
```c=
// 建立信號量
tx_semaphore_create(TX_SEMAPHORE *semaphore_ptr, CHAR *name_ptr,
                    ULONG initial_count);
// 刪除信號量
tx_semaphore_delete(TX_SEMAPHORE *semaphore_ptr);
```
#### 互相排斥 (Mutual Exclusion)

用途: 控制執行緒對共享資源的訪問，通常信號燈初始值設為 1（即二進制信號燈）。
注意事項: 避免執行緒多次取得同一信號燈，否則可能導致無限期掛起。
#### 事件通知 (Event Notification)

模式: 生產者-消費者模式。
生產者: 使用 tx_semaphore_put 增加信號燈計數。
消費者: 使用 tx_semaphore_get 等待信號燈變為可用。
工具: 可使用 tx_semaphore_ceiling_put 設置計數上限，避免計數器溢出。
相關 API:
```c=
// 設定信號量上限
tx_semaphore_ceiling_put(TX_SEMAPHORE *semaphore_ptr, ULONG ceiling);
```
#### 執行緒掛起 (Thread Suspension)

觸發條件: 當信號燈計數為 0 時，執行緒會掛起等待。
恢復順序: 按 FIFO 恢復掛起執行緒，可使用 tx_semaphore_prioritize 調整優先順序。

相關 API:
```c=
// 調整信號量中執行緒的優先順序
tx_semaphore_prioritize(TX_SEMAPHORE *semaphore_ptr);
```
#### 信號燈放置通知 (Semaphore Put Notification)

功能: 使用 tx_semaphore_put_notify 註冊通知函數，在信號燈被放置時執行自定義邏輯。

相關 API:
```c=
// 設定信號量釋放通知回呼
tx_semaphore_put_notify(TX_SEMAPHORE *semaphore_ptr,
                        VOID (*semaphore_put_notify)(TX_SEMAPHORE *));
```
#### 效能與資訊查詢

獲取信號燈狀態及效能數據，包含當前計數值、掛起執行緒數量等資訊。

相關 API:
```c=
// 獲取信號量資訊
tx_semaphore_info_get(TX_SEMAPHORE *semaphore_ptr, CHAR **name,
                      ULONG *current_value, TX_THREAD **first_suspended,
                      ULONG *suspended_count, TX_SEMAPHORE **next_semaphore);
// 獲取信號量效能資訊
tx_semaphore_performance_info_get(TX_SEMAPHORE *semaphore_ptr,
                                  ULONG *puts, ULONG *gets, ULONG *suspensions,
                                  ULONG *timeouts);
// 獲取全域信號量效能資訊
tx_semaphore_performance_system_info_get(ULONG *puts, ULONG *gets,
                                         ULONG *suspensions, ULONG *timeouts);
```
#### 抱死 (Deadly Embrace)
![image](https://hackmd.io/_uploads/S1AkloUHkg.png)
P1、P2兩個執行緒都需要資源才能繼續執行。P1擁有資源R2、還需要額外資源R1才能執行；P2擁有資源R1、還需要額外資源R2才能執行，兩邊都在互相等待而沒有任何一個可執行。

定義: 當多個執行緒相互等待對方釋放信號燈時，可能導致死鎖。
避免方法:
每次僅擁有一個信號燈。
按固定順序獲取信號燈。
使用超時機制避免無限期掛起。

優先級反轉

## 互斥鎖 (Mutexes)

互斥鎖是一種特殊的二進制信號燈，專門用於實現互斥功能。
每次僅允許一個執行緒持有互斥鎖，並且允許同一執行緒多次獲取同一互斥鎖（最多 4,294,967,295 次）。
#### Mutex特點與注意事項

優先級繼承: 防止優先級反轉，持有互斥鎖的執行緒可以暫時提升到與最高優先級掛起執行緒相同的優先級。
互斥鎖僅用於實現互斥功能，不能用作事件通知工具。
每次釋放互斥鎖的次數必須與之前的獲取次數相等，否則可能導致應用錯誤。
#### 基本操作:
tx_mutex_get: 獲取互斥鎖，當互斥鎖被其他執行緒持有時，當前執行緒將進入掛起狀態。
tx_mutex_put: 釋放互斥鎖，釋放次數需與獲取次數相等。

相關 API:
```c=
// 獲取互斥鎖
tx_mutex_get(TX_MUTEX *mutex_ptr, ULONG wait_option);
// 釋放互斥鎖
tx_mutex_put(TX_MUTEX *mutex_ptr);
```
#### 互相排斥 (Mutual Exclusion)

互斥鎖用於控制執行緒對關鍵區域或共享資源的訪問。
互斥鎖的所有權計數：
初始值為 0。
每次獲取成功，計數增加 1；每次釋放成功，計數減少 1。
#### 創建與刪除互斥鎖 (Creating and Deleting Mutexes)

創建: 使用 tx_mutex_create 創建互斥鎖，可選擇是否啟用優先級繼承功能。
刪除: 使用 tx_mutex_delete 刪除互斥鎖，釋放相關資源。
```c=
// 建立互斥鎖
tx_mutex_create(TX_MUTEX *mutex_ptr, CHAR *name_ptr, UINT inherit);
// 刪除互斥鎖
tx_mutex_delete(TX_MUTEX *mutex_ptr);
```
#### 執行緒掛起 (Thread Suspension)

當執行緒嘗試獲取已被其他執行緒持有的互斥鎖時，將進入掛起狀態。
持有互斥鎖的執行緒釋放後，掛起的執行緒將按 FIFO 順序依次恢復。
若啟用了 優先級繼承 或調用了 tx_mutex_prioritize，系統將優先恢復優先級最高的執行緒。
相關 API:
```c=
// 調整互斥鎖的優先順序
tx_mutex_prioritize(TX_MUTEX *mutex_ptr);
```

