From owner-svn-src-head@freebsd.org Mon Oct 23 16:14:56 2017 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 5EB94E4F20C; Mon, 23 Oct 2017 16:14:56 +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 mx1.freebsd.org (Postfix) with ESMTPS id 36C3375C71; Mon, 23 Oct 2017 16:14:56 +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 v9NGEtxb036361; Mon, 23 Oct 2017 16:14:55 GMT (envelope-from kib@FreeBSD.org) Received: (from kib@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v9NGEtuP036360; Mon, 23 Oct 2017 16:14:55 GMT (envelope-from kib@FreeBSD.org) Message-Id: <201710231614.v9NGEtuP036360@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: kib set sender to kib@FreeBSD.org using -f From: Konstantin Belousov Date: Mon, 23 Oct 2017 16:14:55 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r324926 - 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: 324926 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.23 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: Mon, 23 Oct 2017 16:14:56 -0000 Author: kib Date: Mon Oct 23 16:14:55 2017 New Revision: 324926 URL: https://svnweb.freebsd.org/changeset/base/324926 Log: Expand explanation of atomicity. Mention per-location total order, out of thin air, and torn writes guarantees. Mention C11 standard' memory model and one most important FreeBSD additional requirement, that is aligned ordinary loads and stores are atomic on processors. The text is introductional and informal. Reference the C11 and C++1{1,4,7} standards for authorative description. In collaboration with: alc Sponsored by: The FreeBSD Foundation (kib) MFC after: 1 week Modified: head/share/man/man9/atomic.9 Modified: head/share/man/man9/atomic.9 ============================================================================== --- head/share/man/man9/atomic.9 Mon Oct 23 16:10:17 2017 (r324925) +++ head/share/man/man9/atomic.9 Mon Oct 23 16:14:55 2017 (r324926) @@ -23,7 +23,7 @@ .\" .\" $FreeBSD$ .\" -.Dd March 22, 2017 +.Dd March 23, 2017 .Dt ATOMIC 9 .Os .Sh NAME @@ -76,10 +76,41 @@ .Ft int .Fn atomic_testandset_ "volatile *p" "u_int v" .Sh DESCRIPTION -Each of the atomic operations is guaranteed to be atomic across multiple -threads and in the presence of interrupts. -They can be used to implement reference counts or as building blocks for more -advanced synchronization primitives such as mutexes. +All of these operations are performed atomically across multiple +threads and in the presence of interrupts, meaning that they are +performed in an indivisible manner from the perspective of concurrently +running threads and interrupt handlers. +.Pp +When atomic operations are performed on cache-coherent memory, all +operations on the same location are totally ordered. +.Pp +When an atomic load is performed on a location in cache-coherent memory, +it reads the entire value that was defined by the last atomic store to +each byte of the location. +An atomic load will never return a value out of thin air. +When an atomic store is performed on a location, no other thread or +interrupt handler will observe a +.Em torn write , +or partial modification of the location. +.Pp +On all architectures supported by +.Fx , +ordinary loads and stores of naturally aligned integer types +are atomic, as executed by the processor. +.Pp +Atomic operations can be used to implement reference counts or as +building blocks for synchronization primitives such as mutexes. +.Pp +The semantics of +.Fx Ns 's +atomic operations are almost identical to those of the similarly named +C11 operations. +The one important difference is that the C11 standard does not +require ordinary loads and stores to ever be atomic. +This is is why the +.Fn atomic_load_explicit memory_order_relaxed +operation exists in the C11 standard, but is not provided by +.In machine/atomic.h . .Ss Types Each atomic operation operates on a specific .Fa type .