Re: [PATCH v2 16/22] futex: Implement sys_futex_waitv()

["Zack Weinberg" <zack@owlfolio.org>]

On Wed, Oct 6, 2021, at 7:50 AM, Peter Zijlstra wrote:
> On Thu, Sep 23, 2021 at 02:11:05PM -0300, André Almeida wrote:
>> Returns the array index of one of the awakened futexes. There’s no given
>> information of how many were awakened, or any particular attribute of it
>> (if it’s the first awakened, if it is of the smaller index...).
>
> As per some native speakers on IRC, awaken isn't the right word. I've
> changed it like the below.

"woken" and "awoken" are also not the right word (my brain flags both as spelling errors).  Suggestions below:

> - * Returns the array index of one of the awaken futexes. There's no given
> - * information of how many were awakened, or any particular attribute of it (if
> - * it's the first awakened, if it is of the smaller index...).
> + * Returns the array index of one of the woken futexes. There's no given
> + * information of how many were woken, or any particular attribute of it (if
> + * it's the first woken, if it is of the smaller index...).

"awakened" was the correct word in all three places here.  The sentences are awkward, I might suggest

# Returns the array index of one of the awakened futexes.
# No further information is provided: any number of other
# futexes may also have been awakened by the same event, and
# if more than one futex was awakened, the returned index may
# refer to any one of them.  (It is not necessarily the futex
# with the smallest index, nor the one most recently awakened,
# nor ...)

> - * @awaken:	Index of the last awoken futex, if any. Used to notify the
> + * @woken:	Index of the last woken futex, if any. Used to notify the
>   *		caller that it can return this index to userspace (return parameter)

'awakened' in both places here; also suggest changing 'last' to 'most recently'

> - *  -  1 - One of the futexes was awaken by another thread
> + *  -  1 - One of the futexes was woken by another thread

'awakened' again (you *could* say 'was woke' here but it sounds slangy).

> -static int futex_wait_multiple_setup(struct futex_vector *vs, int count, int *awaken)
> +static int futex_wait_multiple_setup(struct futex_vector *vs, int count, int *woken)

and again

> -	 * absorb any awake events, which cannot be done before the
> +	 * loose any wake events, which cannot be done before the

'wake events' is correct here, but you introduced an unrelated error: 'loose' is the opposite of 'tight', you want 'lose' with only one O.

> -		 * was awaken, we don't return error and return this index to
> +		 * was woken, we don't return error and return this index to
>  		 * userspace
>  		 */
> -		*awaken = unqueue_multiple(vs, i);
> -		if (*awaken >= 0)
> +		*woken = unqueue_multiple(vs, i);
> +		if (*woken >= 0)

'awakened' in all locations

> - * been awaken.
> + * been woken.

same here

> -				/* A futex was awaken during setup */
> +				/* A futex was woken during setup */

and here

zw