Date: Sun, 17 Mar 2013 23:13:11 +0400 From: Gleb Smirnoff <glebius@FreeBSD.org> To: src-committers@freebsd.org, svn-src-projects@freebsd.org Subject: Re: svn commit: r248438 - projects/counters/share/man/man9 Message-ID: <20130317191311.GW48089@FreeBSD.org> In-Reply-To: <201303171912.r2HJC1nF016954@svn.freebsd.org> References: <201303171912.r2HJC1nF016954@svn.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, Mar 17, 2013 at 07:12:01PM +0000, Gleb Smirnoff wrote: T> Author: glebius T> Date: Sun Mar 17 19:12:01 2013 T> New Revision: 248438 T> URL: http://svnweb.freebsd.org/changeset/base/248438 T> T> Log: T> Document counter(9). Native speakers review requested. Feel free to commit any wording fixes without my approvement. T> Added: T> projects/counters/share/man/man9/counter.9 (contents, props changed) T> Modified: T> projects/counters/share/man/man9/Makefile T> T> Modified: projects/counters/share/man/man9/Makefile T> ============================================================================== T> --- projects/counters/share/man/man9/Makefile Sun Mar 17 18:49:11 2013 (r248437) T> +++ projects/counters/share/man/man9/Makefile Sun Mar 17 19:12:01 2013 (r248438) T> @@ -51,6 +51,7 @@ MAN= accept_filter.9 \ T> config_intrhook.9 \ T> contigmalloc.9 \ T> copy.9 \ T> + counter.9 \ T> cr_cansee.9 \ T> critical_enter.9 \ T> cr_seeothergids.9 \ T> @@ -569,6 +570,12 @@ MLINKS+=copy.9 copyin.9 \ T> copy.9 copyout.9 \ T> copy.9 copyout_nofault.9 \ T> copy.9 copystr.9 T> +MLINKS+=counter.9 counter_u64_alloc.9 \ T> + counter.9 counter_u64_free.9 \ T> + counter.9 counter_u64_inc.9 \ T> + counter.9 counter_u64_dec.9 \ T> + counter.9 counter_u64_fetch.9 \ T> + counter.9 counter_u64_zero.9 T> MLINKS+=critical_enter.9 critical.9 \ T> critical_enter.9 critical_exit.9 T> MLINKS+=crypto.9 crypto_dispatch.9 \ T> T> Added: projects/counters/share/man/man9/counter.9 T> ============================================================================== T> --- /dev/null 00:00:00 1970 (empty, because file is newly added) T> +++ projects/counters/share/man/man9/counter.9 Sun Mar 17 19:12:01 2013 (r248438) T> @@ -0,0 +1,179 @@ T> +.\" Copyright (c) 2013 Gleb Smirnoff <glebius@FreeBSD.org> T> +.\" All rights reserved. T> +.\" T> +.\" Redistribution and use in source and binary forms, with or without T> +.\" modification, are permitted provided that the following conditions T> +.\" are met: T> +.\" 1. Redistributions of source code must retain the above copyright T> +.\" notice, this list of conditions and the following disclaimer. T> +.\" 2. Redistributions in binary form must reproduce the above copyright T> +.\" notice, this list of conditions and the following disclaimer in the T> +.\" documentation and/or other materials provided with the distribution. T> +.\" T> +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND T> +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE T> +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE T> +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE T> +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL T> +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS T> +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) T> +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT T> +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY T> +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF T> +.\" SUCH DAMAGE. T> +.\" T> +.\" $FreeBSD$ T> +.\" T> +.Dd March 17, 2013 T> +.Dt COUNTER 9 T> +.Os T> +.Sh NAME T> +.Nm counter T> +.Nd "generic kernel counter implementation" T> +.Sh SYNOPSIS T> +.In sys/types.h T> +.In sys/counter.h T> +.Ft counter_u64_t T> +.Fn counter_u64_alloc "int wait" T> +.Ft void T> +.Fn counter_u64_free "counter_u64_t cnt" T> +.Ft void T> +.Fn counter_u64_inc "counter_u64_t cnt" "uint64_t inc" T> +.Ft void T> +.Fn counter_u64_dec "counter_u64_t cnt "uint64_t dec" T> +.Ft uint64_t T> +.Fn counter_u64_fetch "counter_u64_t cnt" T> +.Ft void T> +.Fn counter_u64_zero "counter_u64_t cnt" T> +.In sys/sysctl.h T> +.Fn SYSCTL_COUNTER_U64 parent nbr name access ptr val descr T> +.Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr T> +.Sh DESCRIPTION T> +The T> +.Nm T> +is a generic facility, which allows to create counters, T> +that can be utilized to collect statistical data or for other purposes. T> +A T> +.Nm T> +is guaranteed to be lossless when several kernel threads do simultaneous T> +update. T> +However, T> +.Nm T> +does not imply any T> +.Xr locking 9 , T> +neither any T> +.Xr atomic 9 T> +operations, thus are expected to be fast. T> +Moreover, T> +.Nm T> +has special optimisations for SMP environment making T> +.Nm T> +update faster than simple "+=" or "++" operation. T> +.Bl -tag -width indent T> +.It Fn counter_u64_alloc how T> +Allocate a new 64-bit unsigned counter. T> +The T> +.Fa wait T> +argument is T> +.Xr malloc 9 T> +wait flag, should be either T> +.Va M_NOWAIT T> +or T> +.Va M_WAITOK . T> +With no-wait semantics operation may fail. T> +.It Fn counter_u64_free cnt T> +Free previously allocated T> +.Nm T> +.Fa cnt . T> +.It Fn counter_u64_inc cnt inc T> +Add value of T> +.Fa inc T> +to T> +.Nm T> +.Fa cnt . T> +.It Fn counter_u64_dec cnt dec T> +Subtract value of T> +.Fa dec T> +from T> +.Nm T> +.Fa cnt . T> +API doesn't guarantee any protection from underflow. T> +See T> +.Sx IMPLEMENTATION DETAILS . T> +.It Fn counter_u64_fetch cnt T> +Obtain current snapshot of the data collected in T> +.Nm T> +.Fa cnt . T> +The data obtained isn't guaranteed to be precise. T> +.It Fn counter_u64_zero cnt T> +Clear data collected in T> +.Nm T> +.Fa cnt T> +and set its value to zero. T> +.It Fn SYSCTL_COUNTER_U64 parent nbr name access ptr val descr T> +Declare a static T> +.Xr sysctl T> +oid that would represent a T> +.Nm . T> +The T> +.Fa ptr T> +argument should be a pointer to allocated T> +.Vt counter_u64_t . T> +Any read of oid returns value obtained through T> +.Fn counter_u64_fetch . T> +Any write to oid zeroes it. T> +.It Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr T> +Create a T> +.Xr sysctl T> +oid that would represent a T> +.Nm . T> +The T> +.Fa ptr T> +argument should be a pointer to allocated T> +.Vt counter_u64_t . T> +Any read of oid returns value obtained through T> +.Fn counter_u64_fetch . T> +Any write to oid zeroes it. T> +.El T> +.Sh IMPLEMENTATION DETAILS T> +On all architectures T> +.Nm T> +is implemented using per-CPU data fields, that are specially aligned in T> +memory, to avoid excessive CPU cache invalidation during updates. T> +These are allocated using T> +.Va UMA_ZONE_PCPU T> +.Xr uma 9 T> +zone. T> +Update operation touches only the field that is private to current CPU. T> +Fetch operation loops through all per-CPU fields and obtains a snapshot T> +sum of all fields. T> +.Pp T> +On amd64 a T> +.Nm counter T> +update is implemented as a single instruction without lock semantics. T> +.Pp T> +On i386 with cmpxchg8 instruction available, this instruction is used. T> +.Pp T> +On some architectures updating a counter require a T> +.Xr critical 9 T> +section. T> +.Sh SEE ALSO T> +.Xr atomic 9 , T> +.Xr critical 9 , T> +.Xr locking 9 , T> +.Xr malloc 9 , T> +.Xr sysctl , T> +.Xr uma 9 T> +.Sh HISTORY T> +The T> +.Nm T> +facility first appeared in T> +.Fx 10.0 . T> +.Sh AUTHORS T> +.An -nosplit T> +The T> +.Nm T> +facility was written by T> +.An Gleb Smirnoff T> +and T> +.An Konstantin Belousov . -- Totus tuus, Glebius.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20130317191311.GW48089>