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