libecb/ecb.pod

=head1 LIBECB - e-C-Builtins

=head2 ABOUT LIBECB

Libecb is currently a simple header file that doesn't require any
configuration to use or include in your project.

It's part of the e-suite of libraries, other members of which include
libev and libeio.

Its homepage can be found here:

    http://software.schmorp.de/pkg/libecb

It mainly provides a number of wrappers around GCC built-ins, together
with replacement functions for other compilers. In addition to this,
it provides a number of other lowlevel C utilities, such as endianness
detection, byte swapping or bit rotations.

Or in other words, things that should be built into any standard C system,
but aren't, implemented as efficient as possible with GCC, and still
correct with other compilers.

More might come.

=head2 ABOUT THE HEADER

At the moment, all you have to do is copy F<ecb.h> somewhere where your
compiler can find it and include it:

   #include <ecb.h>

The header should work fine for both C and C++ compilation, and gives you
all of F<inttypes.h> in addition to the ECB symbols.

There are currently no object files to link to - future versions might
come with an (optional) object code library to link against, to reduce
code size or gain access to additional features.

It also currently includes everything from F<inttypes.h>.

=head2 ABOUT THIS MANUAL / CONVENTIONS

This manual mainly describes each (public) function available after
including the F<ecb.h> header. The header might define other symbols than
these, but these are not part of the public API, and not supported in any
way.

When the manual mentions a "function" then this could be defined either as
as inline function, a macro, or an external symbol.

When functions use a concrete standard type, such as C<int> or
C<uint32_t>, then the corresponding function works only with that type. If
only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
the corresponding function relies on C to implement the correct types, and
is usually implemented as a macro. Specifically, a "bool" in this manual
refers to any kind of boolean value, not a specific type.

=head2 GCC ATTRIBUTES

A major part of libecb deals with GCC attributes. These are additional
attributes that you can assign to functions, variables and sometimes even
types - much like C<const> or C<volatile> in C.

While GCC allows declarations to show up in many surprising places,
but not in many expected places, the safest way is to put attribute
declarations before the whole declaration:

   ecb_const int mysqrt (int a);
   ecb_unused int i;

For variables, it is often nicer to put the attribute after the name, and
avoid multiple declarations using commas:

   int i ecb_unused;

=over 4

=item ecb_attribute ((attrs...))

A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
nothing on other compilers, so the effect is that only GCC sees these.

Example: use the C<deprecated> attribute on a function.

  ecb_attribute((__deprecated__)) void
  do_not_use_me_anymore (void);

=item ecb_unused

Marks a function or a variable as "unused", which simply suppresses a
warning by GCC when it detects it as unused. This is useful when you e.g.
declare a variable but do not always use it:

  {
    int var ecb_unused;

    #ifdef SOMECONDITION
       var = ...;
       return var;
    #else
       return 0;
    #endif
  }

=item ECB_INLINE

This is not actually an attribute, but you use it like one. It expands
either to C<static inline> or to just C<static>, if inline isn't
supported. It should be used to declare functions that should be inlined,
for code size or speed reasons.

Example: inline this function, it surely will reduce codesize.

   ECB_INLINE int
   negmul (int a, int b)
   {
     return - (a * b);
   }

=item ecb_noinline

Prevent a function from being inlined - it might be optimised away, but
not inlined into other functions. This is useful if you know your function
is rarely called and large enough for inlining not to be helpful.

=item ecb_noreturn

Marks a function as "not returning, ever". Some typical functions that
don't return are C<exit> or C<abort> (which really works hard to not
return), and now you can make your own:

   ecb_noreturn void
   my_abort (const char *errline)
   {
     puts (errline);
     abort ();
   }

In this case, the compiler would probably be smart enough to deduce it on
its own, so this is mainly useful for declarations.

=item ecb_const

Declares that the function only depends on the values of its arguments,
much like a mathematical function. It specifically does not read or write
any memory any arguments might point to, global variables, or call any
non-const functions. It also must not have any side effects.

Such a function can be optimised much more aggressively by the compiler -
for example, multiple calls with the same arguments can be optimised into
a single call, which wouldn't be possible if the compiler would have to
expect any side effects.

It is best suited for functions in the sense of mathematical functions,
such as a function returning the square root of its input argument.

Not suited would be a function that calculates the hash of some memory
area you pass in, prints some messages or looks at a global variable to
decide on rounding.

See C<ecb_pure> for a slightly less restrictive class of functions.

=item ecb_pure

Similar to C<ecb_const>, declares a function that has no side
effects. Unlike C<ecb_const>, the function is allowed to examine global
variables and any other memory areas (such as the ones passed to it via
pointers).

While these functions cannot be optimised as aggressively as C<ecb_const>
functions, they can still be optimised away in many occasions, and the
compiler has more freedom in moving calls to them around.

Typical examples for such functions would be C<strlen> or C<memcmp>. A
function that calculates the MD5 sum of some input and updates some MD5
state passed as argument would I<NOT> be pure, however, as it would modify
some memory area that is not the return value.

=item ecb_hot

This declares a function as "hot" with regards to the cache - the function
is used so often, that it is very beneficial to keep it in the cache if
possible.

The compiler reacts by trying to place hot functions near to each other in
memory.

Whether a function is hot or not often depends on the whole program,
and less on the function itself. C<ecb_cold> is likely more useful in
practise.

=item ecb_cold

The opposite of C<ecb_hot> - declares a function as "cold" with regards to
the cache, or in other words, this function is not called often, or not at
speed-critical times, and keeping it in the cache might be a waste of said
cache.

In addition to placing cold functions together (or at least away from hot
functions), this knowledge can be used in other ways, for example, the
function will be optimised for size, as opposed to speed, and codepaths
leading to calls to those functions can automatically be marked as if
C<ecb_expect_false> had been used to reach them.

Good examples for such functions would be error reporting functions, or
functions only called in exceptional or rare cases.

=item ecb_artificial

Declares the function as "artificial", in this case meaning that this
function is not really mean to be a function, but more like an accessor
- many methods in C++ classes are mere accessor functions, and having a
crash reported in such a method, or single-stepping through them, is not
usually so helpful, especially when it's inlined to just a few instructions.

Marking them as artificial will instruct the debugger about just this,
leading to happier debugging and thus happier lives.

Example: in some kind of smart-pointer class, mark the pointer accessor as
artificial, so that the whole class acts more like a pointer and less like
some C++ abstraction monster.

  template<typename T>
  struct my_smart_ptr
  {
    T *value;

    ecb_artificial
    operator T *()
    {
      return value;
    }
  };

=back

=head2 OPTIMISATION HINTS

=over 4

=item bool ecb_is_constant(expr)

Returns true iff the expression can be deduced to be a compile-time
constant, and false otherwise.

For example, when you have a C<rndm16> function that returns a 16 bit
random number, and you have a function that maps this to a range from
0..n-1, then you could use this inline function in a header file:

  ecb_inline uint32_t
  rndm (uint32_t n)
  {
    return (n * (uint32_t)rndm16 ()) >> 16;
  }

However, for powers of two, you could use a normal mask, but that is only
worth it if, at compile time, you can detect this case. This is the case
when the passed number is a constant and also a power of two (C<n & (n -
1) == 0>):

  ecb_inline uint32_t
  rndm (uint32_t n)
  {
    return is_constant (n) && !(n & (n - 1))
      ? rndm16 () & (num - 1)
      : (n * (uint32_t)rndm16 ()) >> 16;
  }

=item bool ecb_expect (expr, value)

Evaluates C<expr> and returns it. In addition, it tells the compiler that
the C<expr> evaluates to C<value> a lot, which can be used for static
branch optimisations.

Usually, you want to use the more intuitive C<ecb_expect_true> and
C<ecb_expect_false> functions instead.

=item bool ecb_expect_true (cond)

=item bool ecb_expect_false (cond)

These two functions expect a expression that is true or false and return
C<1> or C<0>, respectively, so when used in the condition of an C<if> or
other conditional statement, it will not change the program:

  /* these two do the same thing */
  if (some_condition) ...;
  if (ecb_expect_true (some_condition)) ...;

However, by using C<ecb_expect_true>, you tell the compiler that the
condition is likely to be true (and for C<ecb_expect_false>, that it is
unlikely to be true).

For example, when you check for a null pointer and expect this to be a
rare, exceptional, case, then use C<ecb_expect_false>:

  void my_free (void *ptr)
  {
    if (ecb_expect_false (ptr == 0))
      return;
  }

Consequent use of these functions to mark away exceptional cases or to
tell the compiler what the hot path through a function is can increase
performance considerably.

You might know these functions under the name C<likely> and C<unlikely>
- while these are common aliases, we find that the expect name is easier
to understand when quickly skimming code. If you wish, you can use
C<ecb_likely> instead of C<ecb_expect_true> and C<ecb_unlikely> instead of
C<ecb_expect_false> - these are simply aliases.

A very good example is in a function that reserves more space for some
memory block (for example, inside an implementation of a string stream) -
each time something is added, you have to check for a buffer overrun, but
you expect that most checks will turn out to be false:

  /* make sure we have "size" extra room in our buffer */
  ecb_inline void
  reserve (int size)
  {
    if (ecb_expect_false (current + size > end))
      real_reserve_method (size); /* presumably noinline */
  }

=item bool ecb_assume (cond)

Try to tell the compiler that some condition is true, even if it's not
obvious.

This can be used to teach the compiler about invariants or other
conditions that might improve code generation, but which are impossible to
deduce form the code itself.

For example, the example reservation function from the C<ecb_expect_false>
description could be written thus (only C<ecb_assume> was added):

  ecb_inline void
  reserve (int size)
  {
    if (ecb_expect_false (current + size > end))
      real_reserve_method (size); /* presumably noinline */

    ecb_assume (current + size <= end);
  }

If you then call this function twice, like this:

  reserve (10);
  reserve (1);

Then the compiler I<might> be able to optimise out the second call
completely, as it knows that C<< current + 1 > end >> is false and the
call will never be executed.

=item bool ecb_unreachable ()

This function does nothing itself, except tell the compiler that it will
never be executed. Apart from suppressing a warning in some cases, this
function can be used to implement C<ecb_assume> or similar functions.

=item bool ecb_prefetch (addr, rw, locality)

Tells the compiler to try to prefetch memory at the given C<addr>ess
for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
C<0> means that there will only be one access later, C<3> means that
the data will likely be accessed very often, and values in between mean
something... in between. The memory pointed to by the address does not
need to be accessible (it could be a null pointer for example), but C<rw>
and C<locality> must be compile-time constants.

An obvious way to use this is to prefetch some data far away, in a big
array you loop over. This prefetches memory some 128 array elements later,
in the hope that it will be ready when the CPU arrives at that location.

  int sum = 0;

  for (i = 0; i < N; ++i)
    {
      sum += arr [i]
      ecb_prefetch (arr + i + 128, 0, 0);
    }

It's hard to predict how far to prefetch, and most CPUs that can prefetch
are often good enough to predict this kind of behaviour themselves. It
gets more interesting with linked lists, especially when you do some fair
processing on each list element:

  for (node *n = start; n; n = n->next)
    {
      ecb_prefetch (n->next, 0, 0);
      ... do medium amount of work with *n
    }

After processing the node, (part of) the next node might already be in
cache.

=back

=head2 BIT FIDDLING / BITSTUFFS

=over 4

=item bool ecb_big_endian ()

=item bool ecb_little_endian ()

These two functions return true if the byte order is big endian
(most-significant byte first) or little endian (least-significant byte
first) respectively.

On systems that are neither, their return values are unspecified.

=item int ecb_ctz32 (uint32_t x)

Returns the index of the least significant bit set in C<x> (or
equivalently the number of bits set to 0 before the least significant bit
set), starting from 0. If C<x> is 0 the result is undefined. A common use
case is to compute the integer binary logarithm, i.e.,  C<floor (log2
(n))>. For example:

  ecb_ctz32 (3) = 0
  ecb_ctz32 (6) = 1

=item int ecb_popcount32 (uint32_t x)

Returns the number of bits set to 1 in C<x>. For example:

  ecb_popcount32 (7) = 3
  ecb_popcount32 (255) = 8

=item uint32_t ecb_bswap16 (uint32_t x)

=item uint32_t ecb_bswap32 (uint32_t x)

These two functions return the value of the 16-bit (32-bit) value C<x>
after reversing the order of bytes (0x11223344 becomes 0x44332211).

=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)

=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)

These two functions return the value of C<x> after rotating all the bits
by C<count> positions to the right or left respectively.

Current GCC versions understand these functions and usually compile them
to "optimal" code (e.g. a single C<roll> on x86).

=back

=head2 ARITHMETIC

=over 4

=item x = ecb_mod (m, n)

Returns C<m> modulo C<n>, which is the same as the positive remainder
of the division operation between C<m> and C<n>, using floored
division. Unlike the C remainder operator C<%>, this function ensures that
the return value is always positive and that the two numbers I<m> and
I<m' = m + i * n> result in the same value modulo I<n> - in other words,
C<ecb_mod> implements the mathematical modulo operation, which is missing
in the language.

C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
negatable, that is, both C<m> and C<-m> must be representable in its
type (this typically excludes the minimum signed integer value, the same
limitation as for C</> and C<%> in C).

Current GCC versions compile this into an efficient branchless sequence on
almost all CPUs.

For example, when you want to rotate forward through the members of an
array for increasing C<m> (which might be negative), then you should use
C<ecb_mod>, as the C<%> operator might give either negative results, or
change direction for negative values:

   for (m = -100; m <= 100; ++m)
     int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];

=back

=head2 UTILITY

=over 4

=item element_count = ecb_array_length (name)

Returns the number of elements in the array C<name>. For example:

  int primes[] = { 2, 3, 5, 7, 11 };
  int sum = 0;

  for (i = 0; i < ecb_array_length (primes); i++)
    sum += primes [i];

=back


Revision:	1.30
Committed:	Sat Jun 11 17:30:32 2011 UTC (12 years, 11 months ago) by root
Branch:	MAIN
Changes since 1.29:	+1 -1 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.14	=head1 LIBECB - e-C-Builtins
2	root	1.3
3	root	1.14	=head2 ABOUT LIBECB
4
5			Libecb is currently a simple header file that doesn't require any
6			configuration to use or include in your project.
7
8	sf-exg	1.16	It's part of the e-suite of libraries, other members of which include
9	root	1.14	libev and libeio.
10
11			Its homepage can be found here:
12
13			http://software.schmorp.de/pkg/libecb
14
15			It mainly provides a number of wrappers around GCC built-ins, together
16			with replacement functions for other compilers. In addition to this,
17	sf-exg	1.16	it provides a number of other lowlevel C utilities, such as endianness
18	root	1.14	detection, byte swapping or bit rotations.
19
20	root	1.24	Or in other words, things that should be built into any standard C system,
21			but aren't, implemented as efficient as possible with GCC, and still
22			correct with other compilers.
23	root	1.17
24	root	1.14	More might come.
25	root	1.3
26			=head2 ABOUT THE HEADER
27
28	root	1.14	At the moment, all you have to do is copy F<ecb.h> somewhere where your
29			compiler can find it and include it:
30
31			#include <ecb.h>
32
33			The header should work fine for both C and C++ compilation, and gives you
34			all of F<inttypes.h> in addition to the ECB symbols.
35
36	sf-exg	1.16	There are currently no object files to link to - future versions might
37	root	1.14	come with an (optional) object code library to link against, to reduce
38			code size or gain access to additional features.
39
40			It also currently includes everything from F<inttypes.h>.
41
42			=head2 ABOUT THIS MANUAL / CONVENTIONS
43
44			This manual mainly describes each (public) function available after
45			including the F<ecb.h> header. The header might define other symbols than
46			these, but these are not part of the public API, and not supported in any
47			way.
48
49			When the manual mentions a "function" then this could be defined either as
50			as inline function, a macro, or an external symbol.
51
52			When functions use a concrete standard type, such as C<int> or
53			C<uint32_t>, then the corresponding function works only with that type. If
54			only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
55			the corresponding function relies on C to implement the correct types, and
56			is usually implemented as a macro. Specifically, a "bool" in this manual
57			refers to any kind of boolean value, not a specific type.
58	root	1.1
59			=head2 GCC ATTRIBUTES
60
61	root	1.20	A major part of libecb deals with GCC attributes. These are additional
62	sf-exg	1.26	attributes that you can assign to functions, variables and sometimes even
63	root	1.20	types - much like C<const> or C<volatile> in C.
64
65			While GCC allows declarations to show up in many surprising places,
66	sf-exg	1.26	but not in many expected places, the safest way is to put attribute
67	root	1.20	declarations before the whole declaration:
68
69			ecb_const int mysqrt (int a);
70			ecb_unused int i;
71
72			For variables, it is often nicer to put the attribute after the name, and
73			avoid multiple declarations using commas:
74
75			int i ecb_unused;
76	root	1.3
77	root	1.1	=over 4
78
79	root	1.2	=item ecb_attribute ((attrs...))
80	root	1.1
81	root	1.15	A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
82			nothing on other compilers, so the effect is that only GCC sees these.
83
84			Example: use the C<deprecated> attribute on a function.
85
86			ecb_attribute((__deprecated__)) void
87			do_not_use_me_anymore (void);
88	root	1.2
89	root	1.3	=item ecb_unused
90
91			Marks a function or a variable as "unused", which simply suppresses a
92			warning by GCC when it detects it as unused. This is useful when you e.g.
93			declare a variable but do not always use it:
94
95	root	1.15	{
96			int var ecb_unused;
97	root	1.3
98	root	1.15	#ifdef SOMECONDITION
99			var = ...;
100			return var;
101			#else
102			return 0;
103			#endif
104			}
105	root	1.3
106	root	1.29	=item ECB_INLINE
107
108			This is not actually an attribute, but you use it like one. It expands
109			either to C<static inline> or to just C<static>, if inline isn't
110			supported. It should be used to declare functions that should be inlined,
111			for code size or speed reasons.
112
113			Example: inline this function, it surely will reduce codesize.
114
115			ECB_INLINE int
116			negmul (int a, int b)
117			{
118			return - (a * b);
119			}
120
121	root	1.2	=item ecb_noinline
122
123	root	1.9	Prevent a function from being inlined - it might be optimised away, but
124	root	1.3	not inlined into other functions. This is useful if you know your function
125			is rarely called and large enough for inlining not to be helpful.
126
127	root	1.2	=item ecb_noreturn
128
129	root	1.17	Marks a function as "not returning, ever". Some typical functions that
130			don't return are C<exit> or C<abort> (which really works hard to not
131			return), and now you can make your own:
132
133			ecb_noreturn void
134			my_abort (const char *errline)
135			{
136			puts (errline);
137			abort ();
138			}
139
140	sf-exg	1.19	In this case, the compiler would probably be smart enough to deduce it on
141			its own, so this is mainly useful for declarations.
142	root	1.17
143	root	1.2	=item ecb_const
144
145	sf-exg	1.19	Declares that the function only depends on the values of its arguments,
146	root	1.17	much like a mathematical function. It specifically does not read or write
147			any memory any arguments might point to, global variables, or call any
148			non-const functions. It also must not have any side effects.
149
150			Such a function can be optimised much more aggressively by the compiler -
151			for example, multiple calls with the same arguments can be optimised into
152			a single call, which wouldn't be possible if the compiler would have to
153			expect any side effects.
154
155			It is best suited for functions in the sense of mathematical functions,
156	sf-exg	1.19	such as a function returning the square root of its input argument.
157	root	1.17
158			Not suited would be a function that calculates the hash of some memory
159			area you pass in, prints some messages or looks at a global variable to
160			decide on rounding.
161
162			See C<ecb_pure> for a slightly less restrictive class of functions.
163
164	root	1.2	=item ecb_pure
165
166	root	1.17	Similar to C<ecb_const>, declares a function that has no side
167			effects. Unlike C<ecb_const>, the function is allowed to examine global
168			variables and any other memory areas (such as the ones passed to it via
169			pointers).
170
171			While these functions cannot be optimised as aggressively as C<ecb_const>
172			functions, they can still be optimised away in many occasions, and the
173			compiler has more freedom in moving calls to them around.
174
175			Typical examples for such functions would be C<strlen> or C<memcmp>. A
176			function that calculates the MD5 sum of some input and updates some MD5
177			state passed as argument would I<NOT> be pure, however, as it would modify
178			some memory area that is not the return value.
179
180	root	1.2	=item ecb_hot
181
182	root	1.17	This declares a function as "hot" with regards to the cache - the function
183			is used so often, that it is very beneficial to keep it in the cache if
184			possible.
185
186			The compiler reacts by trying to place hot functions near to each other in
187			memory.
188
189	sf-exg	1.19	Whether a function is hot or not often depends on the whole program,
190	root	1.17	and less on the function itself. C<ecb_cold> is likely more useful in
191			practise.
192
193	root	1.2	=item ecb_cold
194
195	root	1.17	The opposite of C<ecb_hot> - declares a function as "cold" with regards to
196			the cache, or in other words, this function is not called often, or not at
197			speed-critical times, and keeping it in the cache might be a waste of said
198			cache.
199
200			In addition to placing cold functions together (or at least away from hot
201			functions), this knowledge can be used in other ways, for example, the
202			function will be optimised for size, as opposed to speed, and codepaths
203			leading to calls to those functions can automatically be marked as if
204	root	1.27	C<ecb_expect_false> had been used to reach them.
205	root	1.17
206			Good examples for such functions would be error reporting functions, or
207			functions only called in exceptional or rare cases.
208
209	root	1.2	=item ecb_artificial
210
211	root	1.17	Declares the function as "artificial", in this case meaning that this
212			function is not really mean to be a function, but more like an accessor
213			- many methods in C++ classes are mere accessor functions, and having a
214			crash reported in such a method, or single-stepping through them, is not
215			usually so helpful, especially when it's inlined to just a few instructions.
216
217			Marking them as artificial will instruct the debugger about just this,
218			leading to happier debugging and thus happier lives.
219
220			Example: in some kind of smart-pointer class, mark the pointer accessor as
221			artificial, so that the whole class acts more like a pointer and less like
222			some C++ abstraction monster.
223
224			template<typename T>
225			struct my_smart_ptr
226			{
227			T *value;
228
229			ecb_artificial
230			operator T *()
231			{
232			return value;
233			}
234			};
235
236	root	1.2	=back
237	root	1.1
238			=head2 OPTIMISATION HINTS
239
240			=over 4
241
242	root	1.14	=item bool ecb_is_constant(expr)
243	root	1.1
244	root	1.3	Returns true iff the expression can be deduced to be a compile-time
245			constant, and false otherwise.
246
247			For example, when you have a C<rndm16> function that returns a 16 bit
248			random number, and you have a function that maps this to a range from
249	root	1.5	0..n-1, then you could use this inline function in a header file:
250	root	1.3
251			ecb_inline uint32_t
252			rndm (uint32_t n)
253			{
254	root	1.6	return (n * (uint32_t)rndm16 ()) >> 16;
255	root	1.3	}
256
257			However, for powers of two, you could use a normal mask, but that is only
258			worth it if, at compile time, you can detect this case. This is the case
259			when the passed number is a constant and also a power of two (C<n & (n -
260			1) == 0>):
261
262			ecb_inline uint32_t
263			rndm (uint32_t n)
264			{
265			return is_constant (n) && !(n & (n - 1))
266			? rndm16 () & (num - 1)
267	root	1.6	: (n * (uint32_t)rndm16 ()) >> 16;
268	root	1.3	}
269
270	root	1.14	=item bool ecb_expect (expr, value)
271	root	1.1
272	root	1.7	Evaluates C<expr> and returns it. In addition, it tells the compiler that
273			the C<expr> evaluates to C<value> a lot, which can be used for static
274			branch optimisations.
275	root	1.1
276	root	1.27	Usually, you want to use the more intuitive C<ecb_expect_true> and
277			C<ecb_expect_false> functions instead.
278	root	1.1
279	root	1.27	=item bool ecb_expect_true (cond)
280	root	1.1
281	root	1.27	=item bool ecb_expect_false (cond)
282	root	1.1
283	root	1.7	These two functions expect a expression that is true or false and return
284			C<1> or C<0>, respectively, so when used in the condition of an C<if> or
285			other conditional statement, it will not change the program:
286
287			/* these two do the same thing */
288			if (some_condition) ...;
289	root	1.27	if (ecb_expect_true (some_condition)) ...;
290	root	1.7
291	root	1.27	However, by using C<ecb_expect_true>, you tell the compiler that the
292			condition is likely to be true (and for C<ecb_expect_false>, that it is
293			unlikely to be true).
294	root	1.7
295	root	1.9	For example, when you check for a null pointer and expect this to be a
296	root	1.27	rare, exceptional, case, then use C<ecb_expect_false>:
297	root	1.7
298			void my_free (void *ptr)
299			{
300	root	1.27	if (ecb_expect_false (ptr == 0))
301	root	1.7	return;
302			}
303
304			Consequent use of these functions to mark away exceptional cases or to
305			tell the compiler what the hot path through a function is can increase
306			performance considerably.
307
308	root	1.27	You might know these functions under the name C<likely> and C<unlikely>
309			- while these are common aliases, we find that the expect name is easier
310			to understand when quickly skimming code. If you wish, you can use
311			C<ecb_likely> instead of C<ecb_expect_true> and C<ecb_unlikely> instead of
312			C<ecb_expect_false> - these are simply aliases.
313
314	root	1.7	A very good example is in a function that reserves more space for some
315			memory block (for example, inside an implementation of a string stream) -
316	root	1.9	each time something is added, you have to check for a buffer overrun, but
317	root	1.7	you expect that most checks will turn out to be false:
318
319			/* make sure we have "size" extra room in our buffer */
320			ecb_inline void
321			reserve (int size)
322			{
323	root	1.27	if (ecb_expect_false (current + size > end))
324	root	1.7	real_reserve_method (size); /* presumably noinline */
325			}
326
327	root	1.14	=item bool ecb_assume (cond)
328	root	1.7
329			Try to tell the compiler that some condition is true, even if it's not
330			obvious.
331
332			This can be used to teach the compiler about invariants or other
333			conditions that might improve code generation, but which are impossible to
334			deduce form the code itself.
335
336	root	1.27	For example, the example reservation function from the C<ecb_expect_false>
337	root	1.7	description could be written thus (only C<ecb_assume> was added):
338
339			ecb_inline void
340			reserve (int size)
341			{
342	root	1.27	if (ecb_expect_false (current + size > end))
343	root	1.7	real_reserve_method (size); /* presumably noinline */
344
345			ecb_assume (current + size <= end);
346			}
347
348			If you then call this function twice, like this:
349
350			reserve (10);
351			reserve (1);
352
353			Then the compiler I<might> be able to optimise out the second call
354			completely, as it knows that C<< current + 1 > end >> is false and the
355			call will never be executed.
356
357			=item bool ecb_unreachable ()
358
359			This function does nothing itself, except tell the compiler that it will
360	root	1.9	never be executed. Apart from suppressing a warning in some cases, this
361	root	1.7	function can be used to implement C<ecb_assume> or similar functions.
362
363	root	1.14	=item bool ecb_prefetch (addr, rw, locality)
364	root	1.7
365			Tells the compiler to try to prefetch memory at the given C<addr>ess
366	root	1.10	for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
367	root	1.7	C<0> means that there will only be one access later, C<3> means that
368			the data will likely be accessed very often, and values in between mean
369			something... in between. The memory pointed to by the address does not
370			need to be accessible (it could be a null pointer for example), but C<rw>
371			and C<locality> must be compile-time constants.
372
373			An obvious way to use this is to prefetch some data far away, in a big
374	root	1.9	array you loop over. This prefetches memory some 128 array elements later,
375	root	1.7	in the hope that it will be ready when the CPU arrives at that location.
376
377			int sum = 0;
378
379			for (i = 0; i < N; ++i)
380			{
381			sum += arr [i]
382			ecb_prefetch (arr + i + 128, 0, 0);
383			}
384
385			It's hard to predict how far to prefetch, and most CPUs that can prefetch
386			are often good enough to predict this kind of behaviour themselves. It
387			gets more interesting with linked lists, especially when you do some fair
388			processing on each list element:
389
390			for (node *n = start; n; n = n->next)
391			{
392			ecb_prefetch (n->next, 0, 0);
393			... do medium amount of work with *n
394			}
395
396			After processing the node, (part of) the next node might already be in
397			cache.
398	root	1.1
399	root	1.2	=back
400	root	1.1
401			=head2 BIT FIDDLING / BITSTUFFS
402
403	root	1.4	=over 4
404
405	root	1.3	=item bool ecb_big_endian ()
406
407			=item bool ecb_little_endian ()
408
409	sf-exg	1.11	These two functions return true if the byte order is big endian
410			(most-significant byte first) or little endian (least-significant byte
411			first) respectively.
412
413	root	1.24	On systems that are neither, their return values are unspecified.
414
415	root	1.3	=item int ecb_ctz32 (uint32_t x)
416
417	sf-exg	1.11	Returns the index of the least significant bit set in C<x> (or
418	root	1.24	equivalently the number of bits set to 0 before the least significant bit
419			set), starting from 0. If C<x> is 0 the result is undefined. A common use
420			case is to compute the integer binary logarithm, i.e., C<floor (log2
421			(n))>. For example:
422	sf-exg	1.11
423	root	1.15	ecb_ctz32 (3) = 0
424			ecb_ctz32 (6) = 1
425	sf-exg	1.11
426	root	1.3	=item int ecb_popcount32 (uint32_t x)
427
428	sf-exg	1.11	Returns the number of bits set to 1 in C<x>. For example:
429
430	root	1.15	ecb_popcount32 (7) = 3
431			ecb_popcount32 (255) = 8
432	sf-exg	1.11
433	root	1.8	=item uint32_t ecb_bswap16 (uint32_t x)
434
435	root	1.3	=item uint32_t ecb_bswap32 (uint32_t x)
436
437	root	1.21	These two functions return the value of the 16-bit (32-bit) value C<x>
438			after reversing the order of bytes (0x11223344 becomes 0x44332211).
439	sf-exg	1.13
440	root	1.3	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
441
442			=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
443
444	root	1.22	These two functions return the value of C<x> after rotating all the bits
445	sf-exg	1.11	by C<count> positions to the right or left respectively.
446
447	root	1.20	Current GCC versions understand these functions and usually compile them
448			to "optimal" code (e.g. a single C<roll> on x86).
449
450	root	1.3	=back
451	root	1.1
452			=head2 ARITHMETIC
453
454	root	1.3	=over 4
455
456	root	1.14	=item x = ecb_mod (m, n)
457	root	1.3
458	root	1.25	Returns C<m> modulo C<n>, which is the same as the positive remainder
459			of the division operation between C<m> and C<n>, using floored
460			division. Unlike the C remainder operator C<%>, this function ensures that
461			the return value is always positive and that the two numbers I<m> and
462			I<m' = m + i * n> result in the same value modulo I<n> - in other words,
463			C<ecb_mod> implements the mathematical modulo operation, which is missing
464			in the language.
465	root	1.14
466	sf-exg	1.23	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
467	root	1.14	negatable, that is, both C<m> and C<-m> must be representable in its
468	root	1.30	type (this typically excludes the minimum signed integer value, the same
469	root	1.25	limitation as for C</> and C<%> in C).
470	sf-exg	1.11
471	root	1.24	Current GCC versions compile this into an efficient branchless sequence on
472	root	1.28	almost all CPUs.
473	root	1.24
474			For example, when you want to rotate forward through the members of an
475			array for increasing C<m> (which might be negative), then you should use
476			C<ecb_mod>, as the C<%> operator might give either negative results, or
477			change direction for negative values:
478
479			for (m = -100; m <= 100; ++m)
480			int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
481
482	root	1.3	=back
483	root	1.1
484			=head2 UTILITY
485
486	root	1.3	=over 4
487
488	sf-exg	1.23	=item element_count = ecb_array_length (name)
489	root	1.3
490	sf-exg	1.13	Returns the number of elements in the array C<name>. For example:
491
492			int primes[] = { 2, 3, 5, 7, 11 };
493			int sum = 0;
494
495			for (i = 0; i < ecb_array_length (primes); i++)
496			sum += primes [i];
497
498	root	1.3	=back
499	root	1.1
500