From owner-svn-src-head@freebsd.org Tue Jul 23 16:11:39 2019 Return-Path: Delivered-To: svn-src-head@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 5F0B8AD3A6; Tue, 23 Jul 2019 16:11:39 +0000 (UTC) (envelope-from kib@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 3FACF977E4; Tue, 23 Jul 2019 16:11:39 +0000 (UTC) (envelope-from kib@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 14A723D0; Tue, 23 Jul 2019 16:11:39 +0000 (UTC) (envelope-from kib@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id x6NGBc9J034131; Tue, 23 Jul 2019 16:11:38 GMT (envelope-from kib@FreeBSD.org) Received: (from kib@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id x6NGBcqU034130; Tue, 23 Jul 2019 16:11:38 GMT (envelope-from kib@FreeBSD.org) Message-Id: <201907231611.x6NGBcqU034130@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: kib set sender to kib@FreeBSD.org using -f From: Konstantin Belousov Date: Tue, 23 Jul 2019 16:11:38 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r350243 - head/share/man/man9 X-SVN-Group: head X-SVN-Commit-Author: kib X-SVN-Commit-Paths: head/share/man/man9 X-SVN-Commit-Revision: 350243 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: 3FACF977E4 X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org X-Spamd-Result: default: False [-2.96 / 15.00]; local_wl_from(0.00)[FreeBSD.org]; NEURAL_HAM_MEDIUM(-1.00)[-0.999,0]; NEURAL_HAM_SHORT(-0.96)[-0.962,0]; ASN(0.00)[asn:11403, ipnet:2610:1c1:1::/48, country:US]; NEURAL_HAM_LONG(-1.00)[-1.000,0] X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 23 Jul 2019 16:11:39 -0000 Author: kib Date: Tue Jul 23 16:11:38 2019 New Revision: 350243 URL: https://svnweb.freebsd.org/changeset/base/350243 Log: Update refcount(9). Describe missed functions. Give some hint about refcount_release(9) memory ordering guarantees. Reviewed by: markj Sponsored by: The FreeBSD Foundation MFC after: 1 week Differential revision: https://reviews.freebsd.org/D21020 Modified: head/share/man/man9/refcount.9 Modified: head/share/man/man9/refcount.9 ============================================================================== --- head/share/man/man9/refcount.9 Tue Jul 23 14:52:46 2019 (r350242) +++ head/share/man/man9/refcount.9 Tue Jul 23 16:11:38 2019 (r350243) @@ -3,6 +3,12 @@ .\" Written by: John H. Baldwin .\" All rights reserved. .\" +.\" Copyright (c) 2019 The FreeBSD Foundation, Inc. +.\" +.\" Parts of this documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: @@ -26,7 +32,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 21, 2019 +.Dd July 23, 2019 .Dt REFCOUNT 9 .Os .Sh NAME @@ -43,7 +49,13 @@ .Ft void .Fn refcount_acquire "volatile u_int *count" .Ft bool +.Fn refcount_acquire_checked "volatile u_int *count" +.Ft bool +.Fn refcount_acquire_if_not_zero "volatile u_int *count" +.Ft bool .Fn refcount_release "volatile u_int *count" +.Ft bool +.Fn refcount_release_if_not_last "volatile u_int *count" .Sh DESCRIPTION The .Nm @@ -54,6 +66,8 @@ A pointer to this integer is passed via Usually the counter is used to manage the lifetime of an object and is stored as a member of the object. .Pp +Currently all functions are implemented as static inline. +.Pp The .Fn refcount_init function is used to set the initial value of the counter to @@ -71,21 +85,75 @@ object, then holding a lock that protects the list pro protection for acquiring a new reference. .Pp The +.Fn refcount_acquire_checked +variant performs the same operation as +.Fn refcount_acquire , +but additionally checks that the +.Fa count +value does not overflow as result of the operation. +It returns +.Dv true +if the reference was sucessfully obtained, and +.Dv false +if it was not, due to the overflow. +.Pp +The +.Fn refcount_acquire_if_not_zero +function is yet another variant of +.Fn refcount_acquire , +which only obtains the reference when some reference already exists. +In other words, +.Fa *count +must be already greater than zero for the function to succeed, in which +case the return value is +.Dv true , +otherwise +.Dv false +is returned. +.Pp +The .Fn refcount_release function is used to release an existing reference. The function returns true if the reference being released was the last reference; otherwise, it returns false. .Pp -Note that these routines do not provide any inter-CPU synchronization, -data protection, -or memory ordering guarantees except for managing the counter. +The +.Fn refcount_release_if_not_last +is a variant of +.Fn refcount_release +which only drops the reference when it is not the last reference. +In other words, the function returns +.Dv true +when +.Fa *count +is greater than one, in which case +.Fa *count is decremented. +Otherwise, if +.Fa *count +is equal to one, the reference is not released and the function returns +.Dv false . +.Pp +Note that these routines do not provide any inter-CPU synchronization or +data protection for managing the counter. The caller is responsible for any additional synchronization needed by consumers of any containing objects. In addition, the caller is also responsible for managing the life cycle of any containing objects including explicitly releasing any resources when the last reference is released. +.Pp +The +.Fn refcount_release +unconditionally executes a release fence (see +.Xr atomic 9 ) before releasing the reference, which +synchronizes with an acquire fence executed right before +returning the +.Dv true +value. +This ensures that the destructor, supposedly executed by the caller after +the last reference was dropped, sees all updates done during the lifetime +of the object. .Sh RETURN VALUES The .Nm refcount_release