zircon/syscalls/futex.fidl

// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// TODO(fxb/39732): This should be read as "library zx".
library zz;

// TODO(scottmg): This is approximately right, but will need to match the
// current definition of zx_futex_t (atomic_int in some #if branches).
using Futex = int32;

// TODO(scottmg): The futex is unusual in that by virtue of being an int,
// sometimes it's passed by pointer, and sometimes by value.

[Transport = "Syscall"]
protocol futex {
    /// Wait on a futex.
    /// Rights: None.
    [blocking]
    futex_wait(const_futexptr value_ptr, Futex current_value, handle new_futex_owner, time deadline)
        -> (status status);

    /// Wake some number of threads waiting on a futex, optionally transferring ownership to the thread which was woken in the process.
    /// Rights: None.
    futex_wake(const_futexptr value_ptr, uint32 wake_count) -> (status status);

    /// Wake some number of threads waiting on a futex, and move more waiters to another wait queue.
    /// Rights: None.
    futex_requeue(const_futexptr value_ptr,
                  uint32 wake_count,
                  Futex current_value,
                  const_futexptr requeue_ptr,
                  uint32 requeue_count,
                  handle new_requeue_owner)
        -> (status status);

    /// Wake some number of threads waiting on a futex, optionally transferring ownership to the thread which was woken in the process.
    /// Rights: None.
    futex_wake_single_owner(const_futexptr value_ptr) -> (status status);

    /// Wake some number of threads waiting on a futex, and move more waiters to another wait queue.
    /// Rights: None.
    futex_requeue_single_owner(const_futexptr value_ptr,
                               Futex current_value,
                               const_futexptr requeue_ptr,
                               uint32 requeue_count,
                               handle new_requeue_owner)
        -> (status status);

    /// Fetch the koid current owner of a futex, if any.
    /// Rights: None.
    futex_get_owner(const_futexptr value_ptr) -> (status status, optional_koid koid);
};