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

# Content
1 =head1 LIBECB - e-C-Builtins
2
3 =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
22 =head2 ABOUT THE HEADER
23
24 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
55 =head2 GCC ATTRIBUTES
56
57 blabla where to put, what others
58
59 =over 4
60
61 =item ecb_attribute ((attrs...))
62
63 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 =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 =item ecb_noinline
84
85 Prevent a function from being inlined - it might be optimised away, but
86 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 =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
103 =head2 OPTIMISATION HINTS
104
105 =over 4
106
107 =item bool ecb_is_constant(expr)
108
109 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 0..n-1, then you could use this inline function in a header file:
115
116 ecb_inline uint32_t
117 rndm (uint32_t n)
118 {
119 return (n * (uint32_t)rndm16 ()) >> 16;
120 }
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 : (n * (uint32_t)rndm16 ()) >> 16;
133 }
134
135 =item bool ecb_expect (expr, value)
136
137 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
141 Usually, you want to use the more intuitive C<ecb_likely> and
142 C<ecb_unlikely> functions instead.
143
144 =item bool ecb_likely (bool)
145
146 =item bool ecb_unlikely (bool)
147
148 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 is likely to be true (and for C<ecb_unlikely>, that it is unlikely to be
158 true).
159
160 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
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 each time something is added, you have to check for a buffer overrun, but
176 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 =item bool ecb_assume (cond)
187
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 never be executed. Apart from suppressing a warning in some cases, this
220 function can be used to implement C<ecb_assume> or similar functions.
221
222 =item bool ecb_prefetch (addr, rw, locality)
223
224 Tells the compiler to try to prefetch memory at the given C<addr>ess
225 for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
226 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 array you loop over. This prefetches memory some 128 array elements later,
234 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
258 =back
259
260 =head2 BIT FIDDLING / BITSTUFFS
261
262 =over 4
263
264 =item bool ecb_big_endian ()
265
266 =item bool ecb_little_endian ()
267
268 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 =item int ecb_ctz32 (uint32_t x)
273
274 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 ecb_ctz32(3) = 0
281 ecb_ctz32(6) = 1
282
283 =item int ecb_popcount32 (uint32_t x)
284
285 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 =item uint32_t ecb_bswap16 (uint32_t x)
291
292 =item uint32_t ecb_bswap32 (uint32_t x)
293
294 These two functions return the value of the 16-bit (32-bit) variable
295 C<x> after reversing the order of bytes.
296
297 =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 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 =back
305
306 =head2 ARITHMETIC
307
308 =over 4
309
310 =item x = ecb_mod (m, n)
311
312 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
320 =back
321
322 =head2 UTILITY
323
324 =over 4
325
326 =item element_count = ecb_array_length (name) [MACRO]
327
328 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 =back
337
338