__predict_true man page on NetBSD

Man page or keyword search:  
man Server   9087 pages
apropos Keyword Search (all sections)
Output format
NetBSD logo
[printable version]

ATTRIBUTE(3)		 BSD Library Functions Manual		  ATTRIBUTE(3)

NAME
     attribute — non-standard GCC attribute extensions

SYNOPSIS
     #include <sys/cdefs.h>

     __dead

     __pure

     __constfunc

     __noinline

     __unused

     __used

     __packed

     __aligned(x);

     __section(section);

     __read_mostly

     __cacheline_aligned

     __predict_true(exp);

     __predict_false(exp);

DESCRIPTION
     The GNU Compiler Collection (GCC) provides many extensions to the stan‐
     dard C language.  Among these are the so-called attributes.  In NetBSD
     all attributes are provided in a restricted namespace.  The described
     macros should be preferred instead of using the GCC's __attribute__
     extension directly.

ATTRIBUTES
     __dead
	  The gcc(1) compiler knows that certain functions such as abort(3)
	  and exit(3) can never return any value.  When such a function is
	  equipped with __dead, certain optimizations are possible.  Obviously
	  a __dead function can never have return type other than void.

     __pure
	  A __pure function is defined to be one that has no effects except
	  the return value, which is assumed to depend only on the function
	  parameters and/or global variables.  Any access to parameters and/or
	  global variables must also be read-only.  A function that depends on
	  volatile memory, or other comparable system resource that can change
	  between two consecutive calls, can never be __pure.  Many math(3)
	  functions satisfy the definition of a __pure function, at least in
	  theory.  Other examples include strlen(3) and strcmp(3).

     __constfunc
	  A “const function” is a stricter variant of “pure functions”.	 In
	  addition to the restrictions of pure functions, a function declared
	  with __constfunc can never access global variables nor take pointers
	  as parameters.  The return value of these functions must depend only
	  on the passed-by-value parameters.  Note also that a function that
	  calls non-const functions can not be __constfunc.  The canonical
	  example of a const function would be abs(3).	As with pure func‐
	  tions, certain micro-optimizations are possible for functions
	  declared with __constfunc.

     __noinline
	  GCC is known for aggressive function inlining.  Sometimes it is
	  known that inlining is undesirable or that a function will perform
	  incorrectly when inlined.  The __noinline macro expands to a func‐
	  tion attribute that prevents GCC for inlining the function, irre‐
	  spective whether the function was declared with the inline keyword.
	  The attribute takes precedence over all other compiler options
	  related to inlining.

     __unused
	  In most GCC versions the common -Wall flag enables warnings produced
	  by functions that are defined but unused.  Marking an unused func‐
	  tion with the __unused macro inhibits these warnings.

     __used
	  The __used macro expands to an attribute that informs GCC that a
	  static variable or function is to be always retained in the object
	  file even if it is unreferenced.

     __packed
	  The __packed macro expands to an attribute that forces a variable or
	  structure field to have the smallest possible alignment, potentially
	  disregarding architecture specific alignment requirements.  The
	  smallest possible alignment is effectively one byte for variables
	  and one bit for fields.  If specified on a struct or union, all
	  variables therein are also packed.  The __packed macro is often use‐
	  ful when dealing with data that is in a particular static format on
	  the disk, wire, or memory.

     __aligned(x)
	  The __aligned() macro expands to an attribute that specifies the
	  minimum alignment in bytes for a variable, structure field, or func‐
	  tion.	 In other words, the specified object should have an alignment
	  of at least x bytes, as opposed to the minimum alignment require‐
	  ments dictated by the architecture and the ABI.  Possible use cases
	  include:

		·   Mixing assembly and C code.

		·   Dealing with hardware that may impose alignment require‐
		    ments greater than the architecture itself.

		·   Using instructions that may impose special alignment
		    requirements.  Typical example would be alignment of fre‐
		    quently used objects along processor cache lines.

	  Note that when used with functions, structures, or structure mem‐
	  bers, __aligned() can only be used to increase the alignment.	 If
	  the macro is however used as part of a typedef, the alignment can
	  both increase and decrease.  Otherwise it is only possible to
	  decrease the alignment for variables and fields by using the
	  __packed macro.  The effectiveness of __aligned() is largely depen‐
	  dent on the linker.  The __alignof__(3) operator can be used to
	  examine the alignment.

     __section(section)
	  The __section() macro expands to an attribute that specifies a par‐
	  ticular section to which a variable or function should be placed.
	  Normally the compiler places the generated objects to sections such
	  as “data” or “text”.	By using __section(), it is possible to over‐
	  ride this behavior, perhaps in order to place some variables into
	  particular sections specific to unique hardware.

     __read_mostly
	  The __read_mostly macro uses __section() to place a variable or
	  function into the “.data.read_mostly” section of the (kernel)
	  elf(5).  The use of __read_mostly allows infrequently modified data
	  to be grouped together; it is expected that the cachelines of rarely
	  and frequently modified data structures are this way separated.
	  Candidates for __read_mostly include variables that are initialized
	  once, read very often, and seldom written to.

     __cacheline_aligned
	  The __cacheline_aligned macro behaves like __read_mostly, but the
	  used section is “.data.cacheline_aligned” instead.  It also uses
	  __aligned() to set the minimum alignment into a predefined coherency
	  unit.	 This should ensure that frequently used data structures are
	  aligned on cacheline boundaries.  Both __cacheline_aligned and
	  __read_mostly are only available for the kernel.

     __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 “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.

	  The macros __predict_true() and __predict_false() annotate the like‐
	  lihood of whether a branch will evaluate to true or false.  The
	  rationale is to improve instruction pipelining.  Semantically
	  __predict_true expects that the integral expression exp equals 1.

     __predict_false
	  The __predict_false expands to an attribute that instructs the com‐
	  piler to predict that a given branch will be likely false.  As pro‐
	  grammers are notoriously bad at predicting the likely behavior of
	  their code, profiling and empirical evidence should precede the use
	  of __predict_false and __predict_true.

SEE ALSO
     gcc(1), __builtin_object_size(3), cdefs(3), c(7)

CAVEATS
     It goes without saying that portable applications should steer clear from
     non-standard extensions specific to any given compiler.  Even when porta‐
     bility is not a concern, use these macros sparsely and wisely.

BSD			       December 19, 2010			   BSD
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server NetBSD

List of man pages available for NetBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net