Date: Tue, 23 Jul 2019 16:11:38 +0000 (UTC) From: Konstantin Belousov <kib@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r350243 - head/share/man/man9 Message-ID: <201907231611.x6NGBcqU034130@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 <jhb@FreeBSD.org> .\" All rights reserved. .\" +.\" Copyright (c) 2019 The FreeBSD Foundation, Inc. +.\" +.\" Parts of this documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201907231611.x6NGBcqU034130>