# zx_futex_requeue_single_owner

## Summary

Wake one thread waiting on a futex, and requeue more waiters to another futex wait queue.

## Declaration

    #include <zircon/syscalls.h>

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

## Description

Wake one thread waiting on *value_ptr* and assign ownership of *value_ptr* to
the thread that was woken. If there are no threads waiting on *value_ptr* then
the ownership of *value_ptr* is set to none.

Then move up to *requeue_count* threads that are still waiting on *value_ptr* from
the *value_ptr* futex to the *requeue_ptr* futex.

`zx_futex_requeue_single_owner` is similar to `zx_futex_requeue` with a
*wake_count* of 1, except that `zx_futex_requeue_single_owner` changes the
ownership of *value_ptr* to the woken thread.
See [`zx_futex_requeue()`](https://fuchsia.dev/reference/syscalls/futex_requeue) for a full description.

## Rights

None.

## Return value

`zx_futex_requeue_single_owner()` returns `ZX_OK` on success.

## Errors

`ZX_ERR_INVALID_ARGS` One of the following is true:

- Either *value_ptr* or *requeue_ptr* is not a valid userspace pointer
- Either *value_ptr* or *requeue_ptr* is not aligned to a `sizeof(zx_futex_t)` boundary.
- *value_ptr* is the same futex as *requeue_ptr*
- *new_requeue_owner* is currently a member of the waiters for either *value_ptr* or *requeue_ptr*

`ZX_ERR_BAD_HANDLE` *new_requeue_owner* is not `ZX_HANDLE_INVALID`, and not a valid handle.

`ZX_ERR_WRONG_TYPE` *new_requeue_owner* is a valid handle, but is not a handle to a thread.

`ZX_ERR_BAD_STATE` *current_value* does not match the value at *value_ptr*.

## See also

- [futex objects](https://fuchsia.dev/docs/reference/kernel_objects/futex)
- [`zx_futex_requeue()`](https://fuchsia.dev/reference/syscalls/futex_requeue)
- [`zx_futex_wait()`](https://fuchsia.dev/reference/syscalls/futex_wait)
- [`zx_futex_wake()`](https://fuchsia.dev/reference/syscalls/futex_wake)