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, 1 month ago) by root
Branch: MAIN
Changes since 1.14: +22 -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 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
71 =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 {
78 int var ecb_unused;
79
80 #ifdef SOMECONDITION
81 var = ...;
82 return var;
83 #else
84 return 0;
85 #endif
86 }
87
88 =item ecb_noinline
89
90 Prevent a function from being inlined - it might be optimised away, but
91 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 =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
108 =head2 OPTIMISATION HINTS
109
110 =over 4
111
112 =item bool ecb_is_constant(expr)
113
114 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 0..n-1, then you could use this inline function in a header file:
120
121 ecb_inline uint32_t
122 rndm (uint32_t n)
123 {
124 return (n * (uint32_t)rndm16 ()) >> 16;
125 }
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 : (n * (uint32_t)rndm16 ()) >> 16;
138 }
139
140 =item bool ecb_expect (expr, value)
141
142 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
146 Usually, you want to use the more intuitive C<ecb_likely> and
147 C<ecb_unlikely> functions instead.
148
149 =item bool ecb_likely (cond)
150
151 =item bool ecb_unlikely (cond)
152
153 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 is likely to be true (and for C<ecb_unlikely>, that it is unlikely to be
163 true).
164
165 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
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 each time something is added, you have to check for a buffer overrun, but
181 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 =item bool ecb_assume (cond)
192
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 never be executed. Apart from suppressing a warning in some cases, this
225 function can be used to implement C<ecb_assume> or similar functions.
226
227 =item bool ecb_prefetch (addr, rw, locality)
228
229 Tells the compiler to try to prefetch memory at the given C<addr>ess
230 for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
231 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 array you loop over. This prefetches memory some 128 array elements later,
239 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
263 =back
264
265 =head2 BIT FIDDLING / BITSTUFFS
266
267 =over 4
268
269 =item bool ecb_big_endian ()
270
271 =item bool ecb_little_endian ()
272
273 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 =item int ecb_ctz32 (uint32_t x)
278
279 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 ecb_ctz32 (3) = 0
286 ecb_ctz32 (6) = 1
287
288 =item int ecb_popcount32 (uint32_t x)
289
290 Returns the number of bits set to 1 in C<x>. For example:
291
292 ecb_popcount32 (7) = 3
293 ecb_popcount32 (255) = 8
294
295 =item uint32_t ecb_bswap16 (uint32_t x)
296
297 =item uint32_t ecb_bswap32 (uint32_t x)
298
299 These two functions return the value of the 16-bit (32-bit) variable
300 C<x> after reversing the order of bytes.
301
302 =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 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 =back
310
311 =head2 ARITHMETIC
312
313 =over 4
314
315 =item x = ecb_mod (m, n)
316
317 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
325 =back
326
327 =head2 UTILITY
328
329 =over 4
330
331 =item element_count = ecb_array_length (name) [MACRO]
332
333 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 =back
342
343