refcount_release_take_##lock
John Baldwin
jhb at freebsd.org
Tue Nov 11 19:28:58 UTC 2014
On Tuesday, October 28, 2014 3:34:04 pm Mateusz Guzik wrote:
> On Tue, Oct 28, 2014 at 02:13:58PM -0400, John Baldwin wrote:
> > On Tuesday, October 28, 2014 1:44:28 pm Mateusz Guzik wrote:
> > > diff --git a/sys/kern/kern_jail.c b/sys/kern/kern_jail.c
> > > index f8ae0e6..e94ccde 100644
> > > --- a/sys/kern/kern_jail.c
> > > +++ b/sys/kern/kern_jail.c
> >
> > The diff looks good to me. Just need to update refcount.9 as well.
> >
>
> diff --git a/share/man/man9/refcount.9 b/share/man/man9/refcount.9
> index e7702a2..61b9b51 100644
FYI, it's often easier to review manpage changes if a rendered version is
included.
> --- a/share/man/man9/refcount.9
> +++ b/share/man/man9/refcount.9
> @@ -26,7 +26,7 @@
> .\"
> .\" $FreeBSD$
> .\"
> -.Dd January 20, 2009
> +.Dd October 28, 2014
> .Dt REFCOUNT 9
> .Os
> .Sh NAME
Need to add the new functions to the .Nm list
> @@ -44,6 +44,15 @@
> .Fn refcount_acquire "volatile u_int *count"
> .Ft int
> .Fn refcount_release "volatile u_int *count"
> +.In sys/mutex.h
> +.Fn refcount_release_lock_mtx "volatile u_int *count, struct mtx *lock"
> +.In sys/rmlock.h
> +.Fn refcount_release_lock_rmlock "volatile u_int *count, struct rmlock *lock"
> +.In sys/rwlock.h
> +.Fn refcount_release_lock_rwlock "volatile u_int *count, struct rwlock *lock"
> +.In sys/lock.h
> +.In sys/sx.h
> +.Fn refcount_release_lock_sx "volatile u_int *count, struct sx *lock"
Hmm, <sys/lock.h> should also be required for the other three and not just sx?
> .Sh DESCRIPTION
> The
> .Nm
> @@ -77,6 +86,13 @@ The function returns a non-zero value if the reference being released was
> the last reference;
> otherwise, it returns zero.
> .Pp
> +.Fn refcount_release_lock_*
Even though it is tedious, most manpages tend to spell out the list of functions
(e.g. I did so in callout recently with all the callout_init_*() variants, etc.).
I believe I broke this rule in atomic(9), but I think if the list of functions
isn't too unreasonable, it's better to explicitly list them (and I think 4 functions
isn't unreasonable).
> +functions release an existing reference holding the lock if it is the last
Perhaps:
functions release an existing reference similar to
.Fn refcount_release .
If the reference being released is the last reference,
the
.Fa lock
is exclusively acquired before the reference is dropped and remains held when
the function returns.
These functions return a non-zero value if the reference being released was the
last reference;
otherwise,
they return zero.
> @@ -91,6 +107,18 @@ The
> .Nm refcount_release
> function returns non-zero when releasing the last reference and zero when
> releasing any other reference.
> +.Pp
> +.Nm refcount_release_lock_*
> +functions return with the lock held and non-zero value when releasing the last
> +reference, zero without the lock held when releasing any other reference.
This this is just about return values, I would instead just update the previous
sentence to add the additional functions. I.e.:
The
.Fn refcount_release , # this is probably my fault, should be Fn
.Fn refcount_release_lock_mtx ,
...
and
.Fn refcount_release_lock sx
functions return non-zero ...
> .Sh HISTORY
> -These functions were introduced in
The
.Fn refcount_init ,
...
> +.Fn refcount_init ,
> +.Fn refcount_acquire
> +and
> +.Fn refcount_release
> +functions were introduced in
> .Fx 6.0 .
> +.Pp
> +.Fn refcount_release_lock_*
> +functions were introduced in
> +.Fx 10.2 .
.Pp
The
.Fn refcount_release_lock_mtx ,
.Fn refcount_release_lock_rmlock ,
...
--
John Baldwin
More information about the freebsd-arch
mailing list