ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
Revision: 1.14
Committed: Thu May 26 23:23:08 2011 UTC (13 years ago) by root
Branch: MAIN
Changes since 1.13: +63 -17 lines
Log Message:
*** empty log message ***

File Contents

# 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     It's part of the e-suite of libraries, other memembers of which include
9     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     it provides a number of other lowlevel C utilities, such endienness
18     detection, byte swapping or bit rotations.
19    
20     More might come.
21 root 1.3
22     =head2 ABOUT THE HEADER
23    
24 root 1.14 At the moment, all you have to do is copy F<ecb.h> somewhere where your
25     compiler can find it and include it:
26    
27     #include <ecb.h>
28    
29     The header should work fine for both C and C++ compilation, and gives you
30     all of F<inttypes.h> in addition to the ECB symbols.
31    
32     There are currently no objetc files to link to - future versions might
33     come with an (optional) object code library to link against, to reduce
34     code size or gain access to additional features.
35    
36     It also currently includes everything from F<inttypes.h>.
37    
38     =head2 ABOUT THIS MANUAL / CONVENTIONS
39    
40     This manual mainly describes each (public) function available after
41     including the F<ecb.h> header. The header might define other symbols than
42     these, but these are not part of the public API, and not supported in any
43     way.
44    
45     When the manual mentions a "function" then this could be defined either as
46     as inline function, a macro, or an external symbol.
47    
48     When functions use a concrete standard type, such as C<int> or
49     C<uint32_t>, then the corresponding function works only with that type. If
50     only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
51     the corresponding function relies on C to implement the correct types, and
52     is usually implemented as a macro. Specifically, a "bool" in this manual
53     refers to any kind of boolean value, not a specific type.
54 root 1.1
55     =head2 GCC ATTRIBUTES
56    
57 root 1.3 blabla where to put, what others
58    
59 root 1.1 =over 4
60    
61 root 1.2 =item ecb_attribute ((attrs...))
62 root 1.1
63 root 1.2 A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and
64     to nothing on other compilers, so the effect is that only GCC sees these.
65    
66 root 1.3 =item ecb_unused
67    
68     Marks a function or a variable as "unused", which simply suppresses a
69     warning by GCC when it detects it as unused. This is useful when you e.g.
70     declare a variable but do not always use it:
71    
72     {
73     int var ecb_unused;
74    
75     #ifdef SOMECONDITION
76     var = ...;
77     return var;
78     #else
79     return 0;
80     #endif
81     }
82    
83 root 1.2 =item ecb_noinline
84    
85 root 1.9 Prevent a function from being inlined - it might be optimised away, but
86 root 1.3 not inlined into other functions. This is useful if you know your function
87     is rarely called and large enough for inlining not to be helpful.
88    
89 root 1.2 =item ecb_noreturn
90    
91     =item ecb_const
92    
93     =item ecb_pure
94    
95     =item ecb_hot
96    
97     =item ecb_cold
98    
99     =item ecb_artificial
100    
101     =back
102 root 1.1
103     =head2 OPTIMISATION HINTS
104    
105     =over 4
106    
107 root 1.14 =item bool ecb_is_constant(expr)
108 root 1.1
109 root 1.3 Returns true iff the expression can be deduced to be a compile-time
110     constant, and false otherwise.
111    
112     For example, when you have a C<rndm16> function that returns a 16 bit
113     random number, and you have a function that maps this to a range from
114 root 1.5 0..n-1, then you could use this inline function in a header file:
115 root 1.3
116     ecb_inline uint32_t
117     rndm (uint32_t n)
118     {
119 root 1.6 return (n * (uint32_t)rndm16 ()) >> 16;
120 root 1.3 }
121    
122     However, for powers of two, you could use a normal mask, but that is only
123     worth it if, at compile time, you can detect this case. This is the case
124     when the passed number is a constant and also a power of two (C<n & (n -
125     1) == 0>):
126    
127     ecb_inline uint32_t
128     rndm (uint32_t n)
129     {
130     return is_constant (n) && !(n & (n - 1))
131     ? rndm16 () & (num - 1)
132 root 1.6 : (n * (uint32_t)rndm16 ()) >> 16;
133 root 1.3 }
134    
135 root 1.14 =item bool ecb_expect (expr, value)
136 root 1.1
137 root 1.7 Evaluates C<expr> and returns it. In addition, it tells the compiler that
138     the C<expr> evaluates to C<value> a lot, which can be used for static
139     branch optimisations.
140 root 1.1
141 root 1.7 Usually, you want to use the more intuitive C<ecb_likely> and
142     C<ecb_unlikely> functions instead.
143 root 1.1
144 root 1.14 =item bool ecb_likely (bool)
145 root 1.1
146 root 1.14 =item bool ecb_unlikely (bool)
147 root 1.1
148 root 1.7 These two functions expect a expression that is true or false and return
149     C<1> or C<0>, respectively, so when used in the condition of an C<if> or
150     other conditional statement, it will not change the program:
151    
152     /* these two do the same thing */
153     if (some_condition) ...;
154     if (ecb_likely (some_condition)) ...;
155    
156     However, by using C<ecb_likely>, you tell the compiler that the condition
157 sf-exg 1.11 is likely to be true (and for C<ecb_unlikely>, that it is unlikely to be
158 root 1.7 true).
159    
160 root 1.9 For example, when you check for a null pointer and expect this to be a
161     rare, exceptional, case, then use C<ecb_unlikely>:
162 root 1.7
163     void my_free (void *ptr)
164     {
165     if (ecb_unlikely (ptr == 0))
166     return;
167     }
168    
169     Consequent use of these functions to mark away exceptional cases or to
170     tell the compiler what the hot path through a function is can increase
171     performance considerably.
172    
173     A very good example is in a function that reserves more space for some
174     memory block (for example, inside an implementation of a string stream) -
175 root 1.9 each time something is added, you have to check for a buffer overrun, but
176 root 1.7 you expect that most checks will turn out to be false:
177    
178     /* make sure we have "size" extra room in our buffer */
179     ecb_inline void
180     reserve (int size)
181     {
182     if (ecb_unlikely (current + size > end))
183     real_reserve_method (size); /* presumably noinline */
184     }
185    
186 root 1.14 =item bool ecb_assume (cond)
187 root 1.7
188     Try to tell the compiler that some condition is true, even if it's not
189     obvious.
190    
191     This can be used to teach the compiler about invariants or other
192     conditions that might improve code generation, but which are impossible to
193     deduce form the code itself.
194    
195     For example, the example reservation function from the C<ecb_unlikely>
196     description could be written thus (only C<ecb_assume> was added):
197    
198     ecb_inline void
199     reserve (int size)
200     {
201     if (ecb_unlikely (current + size > end))
202     real_reserve_method (size); /* presumably noinline */
203    
204     ecb_assume (current + size <= end);
205     }
206    
207     If you then call this function twice, like this:
208    
209     reserve (10);
210     reserve (1);
211    
212     Then the compiler I<might> be able to optimise out the second call
213     completely, as it knows that C<< current + 1 > end >> is false and the
214     call will never be executed.
215    
216     =item bool ecb_unreachable ()
217    
218     This function does nothing itself, except tell the compiler that it will
219 root 1.9 never be executed. Apart from suppressing a warning in some cases, this
220 root 1.7 function can be used to implement C<ecb_assume> or similar functions.
221    
222 root 1.14 =item bool ecb_prefetch (addr, rw, locality)
223 root 1.7
224     Tells the compiler to try to prefetch memory at the given C<addr>ess
225 root 1.10 for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
226 root 1.7 C<0> means that there will only be one access later, C<3> means that
227     the data will likely be accessed very often, and values in between mean
228     something... in between. The memory pointed to by the address does not
229     need to be accessible (it could be a null pointer for example), but C<rw>
230     and C<locality> must be compile-time constants.
231    
232     An obvious way to use this is to prefetch some data far away, in a big
233 root 1.9 array you loop over. This prefetches memory some 128 array elements later,
234 root 1.7 in the hope that it will be ready when the CPU arrives at that location.
235    
236     int sum = 0;
237    
238     for (i = 0; i < N; ++i)
239     {
240     sum += arr [i]
241     ecb_prefetch (arr + i + 128, 0, 0);
242     }
243    
244     It's hard to predict how far to prefetch, and most CPUs that can prefetch
245     are often good enough to predict this kind of behaviour themselves. It
246     gets more interesting with linked lists, especially when you do some fair
247     processing on each list element:
248    
249     for (node *n = start; n; n = n->next)
250     {
251     ecb_prefetch (n->next, 0, 0);
252     ... do medium amount of work with *n
253     }
254    
255     After processing the node, (part of) the next node might already be in
256     cache.
257 root 1.1
258 root 1.2 =back
259 root 1.1
260     =head2 BIT FIDDLING / BITSTUFFS
261    
262 root 1.4 =over 4
263    
264 root 1.3 =item bool ecb_big_endian ()
265    
266     =item bool ecb_little_endian ()
267    
268 sf-exg 1.11 These two functions return true if the byte order is big endian
269     (most-significant byte first) or little endian (least-significant byte
270     first) respectively.
271    
272 root 1.3 =item int ecb_ctz32 (uint32_t x)
273    
274 sf-exg 1.11 Returns the index of the least significant bit set in C<x> (or
275     equivalently the number of bits set to 0 before the least significant
276     bit set), starting from 0. If C<x> is 0 the result is undefined. A
277     common use case is to compute the integer binary logarithm, i.e.,
278     floor(log2(n)). For example:
279    
280 sf-exg 1.12 ecb_ctz32(3) = 0
281     ecb_ctz32(6) = 1
282 sf-exg 1.11
283 root 1.3 =item int ecb_popcount32 (uint32_t x)
284    
285 sf-exg 1.11 Returns the number of bits set to 1 in C<x>. For example:
286    
287     ecb_popcount32(7) = 3
288     ecb_popcount32(255) = 8
289    
290 root 1.8 =item uint32_t ecb_bswap16 (uint32_t x)
291    
292 root 1.3 =item uint32_t ecb_bswap32 (uint32_t x)
293    
294 sf-exg 1.13 These two functions return the value of the 16-bit (32-bit) variable
295     C<x> after reversing the order of bytes.
296    
297 root 1.3 =item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
298    
299     =item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
300    
301 sf-exg 1.11 These two functions return the value of C<x> after shifting all the bits
302     by C<count> positions to the right or left respectively.
303    
304 root 1.3 =back
305 root 1.1
306     =head2 ARITHMETIC
307    
308 root 1.3 =over 4
309    
310 root 1.14 =item x = ecb_mod (m, n)
311 root 1.3
312 root 1.14 Returns the positive remainder of the modulo operation between C<m> and
313     C<n>. Unlike the C moduloe operator C<%>, this function ensures that the
314     return value is always positive).
315    
316     C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be
317     negatable, that is, both C<m> and C<-m> must be representable in its
318     type.
319 sf-exg 1.11
320 root 1.3 =back
321 root 1.1
322     =head2 UTILITY
323    
324 root 1.3 =over 4
325    
326 root 1.8 =item element_count = ecb_array_length (name) [MACRO]
327 root 1.3
328 sf-exg 1.13 Returns the number of elements in the array C<name>. For example:
329    
330     int primes[] = { 2, 3, 5, 7, 11 };
331     int sum = 0;
332    
333     for (i = 0; i < ecb_array_length (primes); i++)
334     sum += primes [i];
335    
336 root 1.3 =back
337 root 1.1
338