From owner-svn-src-projects@FreeBSD.ORG Sat Mar 23 07:24:07 2013 Return-Path: Delivered-To: svn-src-projects@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 2F65AF96; Sat, 23 Mar 2013 07:24:07 +0000 (UTC) (envelope-from kib@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id 0A31C909; Sat, 23 Mar 2013 07:24:07 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.6/8.14.6) with ESMTP id r2N7O6FU030552; Sat, 23 Mar 2013 07:24:06 GMT (envelope-from kib@svn.freebsd.org) Received: (from kib@localhost) by svn.freebsd.org (8.14.6/8.14.5/Submit) id r2N7O6Pu030551; Sat, 23 Mar 2013 07:24:06 GMT (envelope-from kib@svn.freebsd.org) Message-Id: <201303230724.r2N7O6Pu030551@svn.freebsd.org> From: Konstantin Belousov Date: Sat, 23 Mar 2013 07:24:06 +0000 (UTC) To: src-committers@freebsd.org, svn-src-projects@freebsd.org Subject: svn commit: r248637 - projects/counters/share/man/man9 X-SVN-Group: projects MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-projects@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the src " projects" tree" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 23 Mar 2013 07:24:07 -0000 Author: kib Date: Sat Mar 23 07:24:06 2013 New Revision: 248637 URL: http://svnweb.freebsd.org/changeset/base/248637 Log: Small updates to the content, making the description more precise. Reviewed by: glebius Modified: projects/counters/share/man/man9/counter.9 Modified: projects/counters/share/man/man9/counter.9 ============================================================================== --- projects/counters/share/man/man9/counter.9 Sat Mar 23 06:49:19 2013 (r248636) +++ projects/counters/share/man/man9/counter.9 Sat Mar 23 07:24:06 2013 (r248637) @@ -30,7 +30,7 @@ .Os .Sh NAME .Nm counter -.Nd "generic kernel counter implementation" +.Nd "SMP-friendly kernel counter implementation" .Sh SYNOPSIS .In sys/types.h .In sys/counter.h @@ -60,16 +60,20 @@ is guaranteed to be lossless when severa updates. However, .Nm -does not imply any -.Xr locking 9 -or +does not block the calling thread, +also no .Xr atomic 9 -operations and is therefore expected to be fast. +operations are used for the update, therefore the counters +can be used in any non-interrupt context. Moreover, .Nm -has special optimisations for SMP environments making +has special optimisations for SMP environments, making +.Nm +update faster than simple arithmetic on the global variable. +Thus .Nm -update faster than simple addition operations. +is considered suitable for accounting in the performance-critical +code pathes. .Bl -tag -width indent .It Fn counter_u64_alloc how Allocate a new 64-bit unsigned counter. @@ -123,9 +127,9 @@ The .Fa ptr argument should be a pointer to allocated .Vt counter_u64_t . -Any read of oid returns value obtained through +A read of the oid returns value obtained through .Fn counter_u64_fetch . -Any write to oid zeroes it. +Any write to the oid zeroes it. .It Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr Create a .Xr sysctl @@ -135,9 +139,9 @@ The .Fa ptr argument should be a pointer to allocated .Vt counter_u64_t . -Any read of oid returns value obtained through +A read of the oid returns value obtained through .Fn counter_u64_fetch . -Any write to oid zeroes it. +Any write to the oid zeroes it. .El .Sh IMPLEMENTATION DETAILS On all architectures @@ -155,9 +159,14 @@ sum of all fields. .Pp On amd64 a .Nm counter -update is implemented as a single instruction without lock semantics. +update is implemented as a single instruction without lock semantics, +operating on the private data for the current CPU, +which is safe against preemption and interrupts. .Pp -On i386 with cmpxchg8 instruction available, this instruction is used. +On i386 architecture, when machine supports the cmpxchg8 instruction, +this instruction is used. +The multi-instruction sequence provides the same guarantees as the +amd64 single-instruction implementation. .Pp On some architectures updating a counter require a .Xr critical 9 @@ -167,7 +176,7 @@ section. .Xr critical 9 , .Xr locking 9 , .Xr malloc 9 , -.Xr sysctl , +.Xr sysctl 9, .Xr uma 9 .Sh HISTORY The