zx_futex_requeue

摘要

喚醒一些等待程序的執行緒，並將更多等候程序移至另一個等候佇列。

宣告

#include <zircon/syscalls.h>

zx_status_t zx_futex_requeue(const zx_futex_t* value_ptr,
                             uint32_t wake_count,
                             zx_futex_t current_value,
                             const zx_futex_t* requeue_ptr,
                             uint32_t requeue_count,
                             zx_handle_t new_requeue_owner);

說明

重排是關於醒來的整體現象。首先，核心會驗證 current_value 中的值是否與 value_ptr 的 futex 值相符，如未回報 ZX_ERR_BAD_STATE。喚醒 wake_count 執行緒後，系統會將 requeue_count 執行緒從原始 futex 的等待佇列移至對應至 requeue_ptr 的等待佇列，以及另一個錯誤。

此重新排入佇列行為可能會用來避免在醒來時擲回隱藏。

擁有權

重新佇列作業會指定兩個 futex、wake futex 和 requeue futex。我們會分別討論這兩項工具的擁有權影響。 一般來說，如果呼叫因任何原因失敗，則不會變更任何未來項目的擁有權。

詳情請參閱「futex」中的擁有權和優先順序繼承。

對「wake futex」目標的影響

成功呼叫 zx_futex_requeue() 後，無論喚醒計數為何，futex 擁有者都將設為不顯示任何內容。如要轉移 futex 的擁有權，請改用 zx_futex_requeue_single_owner() 變化版本。zx_futex_requeue_single_owner() 會嘗試從未來等候佇列中喚醒一個執行緒。如果至少有一個執行緒可喚醒，系統會將 futex 的擁有者設定為喚醒的執行緒。否則該函式不會有擁有者。

對重新佇列 futex 目標的影響

如果呼叫 zx_futex_requeue() 或 zx_futex_requeue_single_owner() 成功， futex 擁有者就會設為 new_requeue_owner 控制代碼所參照的執行緒，如果 new_requeue_owner 是 ZX_HANDLE_INVALID，就完全不會設定 futex 擁有者。

權限

無。

傳回值

zx_futex_requeue() 會在成功時傳回 ZX_OK。

錯誤

ZX_ERR_INVALID_ARGS 符合下列其中一項條件：

  • value_ptr 或 requeue_ptr 不是有效的使用者空間指標
  • value_ptr 或 requeue_ptr 不能與 sizeof(zx_futex_t) 邊界對齊。
  • value_ptr 與 requeue_ptr 相同
  • new_requeue_owner 目前是 value_ptr 或 requeue_ptr 的等候者
  • new_requeue_owner 尚未開始。

ZX_ERR_BAD_HANDLE new_requeue_owner 不是 ZX_HANDLE_INVALID，而是有效的控制代碼，而且 current_value 會與 value_ptr 的值相符

ZX_ERR_WRONG_TYPE new_requeue_owner 是有效的控制代碼，但不是執行緒的控制代碼。

ZX_ERR_BAD_STATE current_value與 current_value 的值不相符。

另請參閱