svn commit: r350243 - head/share/man/man9

[Konstantin Belousov]

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 at FreeBSD.org>
 .\" All rights reserved.
 .\"
+.\" Copyright (c) 2019 The FreeBSD Foundation, Inc.
+.\"
+.\" Parts of this documentation was written by
+.\" Konstantin Belousov <kib at 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