Re: [PATCHv2 05/16] atomics: prepare for atomic64_fetch_add_unless()

From: Mark Rutland
Date: Tue Jun 05 2018 - 07:08:19 EST


On Tue, Jun 05, 2018 at 08:54:03PM +1000, Michael Ellerman wrote:
> Mark Rutland <mark.rutland@xxxxxxx> writes:
> > On Tue, Jun 05, 2018 at 11:26:37AM +0200, Peter Zijlstra wrote:
> >> On Tue, May 29, 2018 at 04:43:35PM +0100, Mark Rutland wrote:
> >> > /**
> >> > + * atomic64_add_unless - add unless the number is already a given value
> >> > + * @v: pointer of type atomic_t
> >> > + * @a: the amount to add to v...
> >> > + * @u: ...unless v is equal to u.
> >> > + *
> >> > + * Atomically adds @a to @v, so long as @v was not already @u.
> >> > + * Returns non-zero if @v was not @u, and zero otherwise.
> >>
> >> I always get confused by that wording; would something like: "Returns
> >> true if the addition was done" not be more clear?
> >
> > Sounds clearer to me; I just stole the wording from the existing
> > atomic_add_unless().
> >
> > I guess you'll want similar for the conditional inc/dec ops, e.g.
> >
> > /**
> > * atomic_inc_not_zero - increment unless the number is zero
> > * @v: pointer of type atomic_t
> > *
> > * Atomically increments @v by 1, so long as @v is non-zero.
> > * Returns non-zero if @v was non-zero, and zero otherwise.
> > */
>
> If we're bike-shedding .. :)
>
> I think "so long as" is overly wordy and not helpful. It'd be clearer
> just as:
>
> * Atomically increments @v by 1, if @v is non-zero.

I agree; done.

Mark.