From owner-freebsd-arch@FreeBSD.ORG Tue Nov 11 19:28:58 2014 Return-Path: Delivered-To: freebsd-arch@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 8B511322 for ; Tue, 11 Nov 2014 19:28:58 +0000 (UTC) Received: from bigwig.baldwin.cx (bigwig.baldwin.cx [IPv6:2001:470:1f11:75::1]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 639B0FBD for ; Tue, 11 Nov 2014 19:28:58 +0000 (UTC) Received: from jhbbsd.localnet (unknown [209.249.190.124]) by bigwig.baldwin.cx (Postfix) with ESMTPSA id 39618B9A0; Tue, 11 Nov 2014 14:28:57 -0500 (EST) From: John Baldwin To: Mateusz Guzik Subject: Re: refcount_release_take_##lock Date: Tue, 11 Nov 2014 14:27:15 -0500 User-Agent: KMail/1.13.5 (FreeBSD/8.4-CBSD-20140415; KDE/4.5.5; amd64; ; ) References: <20141025184448.GA19066@dft-labs.eu> <201410281413.58414.jhb@freebsd.org> <20141028193404.GB12014@dft-labs.eu> In-Reply-To: <20141028193404.GB12014@dft-labs.eu> MIME-Version: 1.0 Content-Type: Text/Plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <201411111427.15407.jhb@freebsd.org> X-Greylist: Sender succeeded SMTP AUTH, not delayed by milter-greylist-4.2.7 (bigwig.baldwin.cx); Tue, 11 Nov 2014 14:28:57 -0500 (EST) Cc: John-Mark Gurney , freebsd-arch@freebsd.org X-BeenThere: freebsd-arch@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: Discussion related to FreeBSD architecture List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 11 Nov 2014 19:28:58 -0000 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, 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