[src/trunk]: src Briefly document __predict_true() and __predict_false().

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/f893a60da6ce
branches:  trunk
changeset: 763424:f893a60da6ce
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Sat Mar 19 04:59:43 2011 +0000

description:
Briefly document __predict_true() and __predict_false().

diffstat:

 distrib/sets/lists/comp/mi |   8 +++++++-
 share/man/man3/Makefile    |   6 ++++--
 share/man/man3/attribute.3 |  39 ++++++++++++++++++++++++++++++++++++++-
 3 files changed, 49 insertions(+), 4 deletions(-)

diffs (116 lines):

diff -r 0236af6bd233 -r f893a60da6ce distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Sat Mar 19 04:07:35 2011 +0000
+++ b/distrib/sets/lists/comp/mi        Sat Mar 19 04:59:43 2011 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.1601 2011/03/18 00:57:19 joerg Exp $
+#      $NetBSD: mi,v 1.1602 2011/03/19 04:59:43 jruoho Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -4977,6 +4977,8 @@
 ./usr/share/man/cat3/__insn_barrier.0          comp-c-catman           .cat
 ./usr/share/man/cat3/__noinline.0              comp-c-catman           .cat
 ./usr/share/man/cat3/__packed.0                        comp-c-catman           .cat
+./usr/share/man/cat3/__predict_true.0          comp-c-catman           .cat
+./usr/share/man/cat3/__predict_false.0         comp-c-catman           .cat
 ./usr/share/man/cat3/__pure.0                  comp-c-catman           .cat
 ./usr/share/man/cat3/__read_mostly.0           comp-c-catman           .cat
 ./usr/share/man/cat3/__section.0               comp-c-catman           .cat
@@ -11108,6 +11110,8 @@
 ./usr/share/man/html3/__insn_barrier.html      comp-c-htmlman          html
 ./usr/share/man/html3/__noinline.html          comp-c-htmlman          html
 ./usr/share/man/html3/__packed.html            comp-c-htmlman          html
+./usr/share/man/html3/__predict_true.html      comp-c-htmlman          html
+./usr/share/man/html3/__predict_false.html     comp-c-htmlman          html
 ./usr/share/man/html3/__pure.html              comp-c-htmlman          html
 ./usr/share/man/html3/__read_mostly.html       comp-c-htmlman          html
 ./usr/share/man/html3/__section.html           comp-c-htmlman          html
@@ -17039,6 +17043,8 @@
 ./usr/share/man/man3/__insn_barrier.3          comp-c-man              .man
 ./usr/share/man/man3/__noinline.3              comp-c-man              .man
 ./usr/share/man/man3/__packed.3                        comp-c-man              .man
+./usr/share/man/man3/__predict_true.3          comp-c-man              .man
+./usr/share/man/man3/__predict_false.3         comp-c-man              .man
 ./usr/share/man/man3/__pure.3                  comp-c-man              .man
 ./usr/share/man/man3/__read_mostly.3           comp-c-man              .man
 ./usr/share/man/man3/__section.3               comp-c-man              .man
diff -r 0236af6bd233 -r f893a60da6ce share/man/man3/Makefile
--- a/share/man/man3/Makefile   Sat Mar 19 04:07:35 2011 +0000
+++ b/share/man/man3/Makefile   Sat Mar 19 04:59:43 2011 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.69 2010/12/22 19:35:42 jruoho Exp $
+#      $NetBSD: Makefile,v 1.70 2011/03/19 04:59:44 jruoho Exp $
 #      @(#)Makefile    8.2 (Berkeley) 12/13/93
 
 MAN=   _DIAGASSERT.3 __CONCAT.3 __UNCONST.3 CMSG_DATA.3 \
@@ -29,7 +29,9 @@
        attribute.3 __aligned.3 \
        attribute.3 __section.3 \
        attribute.3 __read_mostly.3 \
-       attribute.3 __cacheline_aligned.3
+       attribute.3 __cacheline_aligned.3 \
+       attribute.3 __predict_true.3 \
+       attribute.3 __predict_false.3
 MLINKS+=bitstring.3 bit_alloc.3 \
        bitstring.3 bit_clear.3 \
        bitstring.3 bit_decl.3 \
diff -r 0236af6bd233 -r f893a60da6ce share/man/man3/attribute.3
--- a/share/man/man3/attribute.3        Sat Mar 19 04:07:35 2011 +0000
+++ b/share/man/man3/attribute.3        Sat Mar 19 04:59:43 2011 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: attribute.3,v 1.9 2010/12/19 08:10:09 jruoho Exp $
+.\" $NetBSD: attribute.3,v 1.10 2011/03/19 04:59:44 jruoho Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -56,6 +56,10 @@
 .Ic __read_mostly
 .Pp
 .Ic __cacheline_aligned
+.Pp
+.Fn __predict_true "exp"
+.Pp
+.Fn __prefict_false "exp"
 .Sh DESCRIPTION
 The
 .Tn GNU
@@ -261,6 +265,39 @@
 and
 .Ic __read_mostly
 are only available for the kernel.
+.It Ic __predict_true
+A branch is generally defined to be a conditional execution of a
+program depending on whether a certain flow control mechanism is altered.
+Typical example would be a
+.Dq if-then-else
+sequence used in high-level languages or
+a jump instruction used in machine-level code.
+A branch prediction would then be defined as an
+attempt to guess whether a conditional branch will be taken.
+.Pp
+The macros
+.Fn __predict_true
+and
+.Fn __predict_false
+annotate the likelihood of whether
+a branch will evaluate to true or false.
+The rationale is to improve instruction pipelining.
+Semantically
+.Ic __predict_true
+expects that the integral expression
+.Fa exp
+equals 1.
+.It Ic __predict_false
+The
+.Ic __predict_false
+expands to an attribute that instructs the compiler
+to predict that a given branch will be likely false.
+As programmers are notoriously bad at predicting
+the likely behavior of their code, profiling and
+empirical evidence should precede the use of
+.Ic __predict_false
+and
+.Ic __predict_true .
 .El
 .Sh SEE ALSO
 .Xr gcc 1 ,