ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
(Generate patch)

Comparing libecb/ecb.pod (file contents):
Revision 1.7 by root, Thu May 26 20:49:40 2011 UTC vs.
Revision 1.42 by root, Mon May 28 08:54:03 2012 UTC

1=head1 LIBECB - e-C-Builtins
2
1=head1 LIBECB 3=head2 ABOUT LIBECB
2 4
3You suck, we don't(tm) 5Libecb is currently a simple header file that doesn't require any
6configuration to use or include in your project.
7
8It's part of the e-suite of libraries, other members of which include
9libev and libeio.
10
11Its homepage can be found here:
12
13 http://software.schmorp.de/pkg/libecb
14
15It mainly provides a number of wrappers around GCC built-ins, together
16with replacement functions for other compilers. In addition to this,
17it provides a number of other lowlevel C utilities, such as endianness
18detection, byte swapping or bit rotations.
19
20Or in other words, things that should be built into any standard C system,
21but aren't, implemented as efficient as possible with GCC, and still
22correct with other compilers.
23
24More might come.
4 25
5=head2 ABOUT THE HEADER 26=head2 ABOUT THE HEADER
6 27
7- how to include it 28At the moment, all you have to do is copy F<ecb.h> somewhere where your
8- it includes inttypes.h 29compiler can find it and include it:
9- no .a 30
10- whats a bool 31 #include <ecb.h>
11- function mean macro or function 32
12- macro means untyped 33The header should work fine for both C and C++ compilation, and gives you
34all of F<inttypes.h> in addition to the ECB symbols.
35
36There are currently no object files to link to - future versions might
37come with an (optional) object code library to link against, to reduce
38code size or gain access to additional features.
39
40It also currently includes everything from F<inttypes.h>.
41
42=head2 ABOUT THIS MANUAL / CONVENTIONS
43
44This manual mainly describes each (public) function available after
45including the F<ecb.h> header. The header might define other symbols than
46these, but these are not part of the public API, and not supported in any
47way.
48
49When the manual mentions a "function" then this could be defined either as
50as inline function, a macro, or an external symbol.
51
52When functions use a concrete standard type, such as C<int> or
53C<uint32_t>, then the corresponding function works only with that type. If
54only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
55the corresponding function relies on C to implement the correct types, and
56is usually implemented as a macro. Specifically, a "bool" in this manual
57refers to any kind of boolean value, not a specific type.
58
59=head2 TYPES / TYPE SUPPORT
60
61ecb.h makes sure that the following types are defined (in the expected way):
62
63 int8_t uint8_t int16_t uint16_t
64 int32_t uint32_t int64_t uint64_t
65 intptr_t uintptr_t ptrdiff_t
66
67The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
68platform (currently C<4> or C<8>).
13 69
14=head2 GCC ATTRIBUTES 70=head2 GCC ATTRIBUTES
15 71
16blabla where to put, what others 72A major part of libecb deals with GCC attributes. These are additional
73attributes that you can assign to functions, variables and sometimes even
74types - much like C<const> or C<volatile> in C.
75
76While GCC allows declarations to show up in many surprising places,
77but not in many expected places, the safest way is to put attribute
78declarations before the whole declaration:
79
80 ecb_const int mysqrt (int a);
81 ecb_unused int i;
82
83For variables, it is often nicer to put the attribute after the name, and
84avoid multiple declarations using commas:
85
86 int i ecb_unused;
17 87
18=over 4 88=over 4
19 89
20=item ecb_attribute ((attrs...)) 90=item ecb_attribute ((attrs...))
21 91
22A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and 92A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
23to nothing on other compilers, so the effect is that only GCC sees these. 93nothing on other compilers, so the effect is that only GCC sees these.
94
95Example: use the C<deprecated> attribute on a function.
96
97 ecb_attribute((__deprecated__)) void
98 do_not_use_me_anymore (void);
24 99
25=item ecb_unused 100=item ecb_unused
26 101
27Marks a function or a variable as "unused", which simply suppresses a 102Marks a function or a variable as "unused", which simply suppresses a
28warning by GCC when it detects it as unused. This is useful when you e.g. 103warning by GCC when it detects it as unused. This is useful when you e.g.
29declare a variable but do not always use it: 104declare a variable but do not always use it:
30 105
106 {
107 int var ecb_unused;
108
109 #ifdef SOMECONDITION
110 var = ...;
111 return var;
112 #else
113 return 0;
114 #endif
115 }
116
117=item ecb_inline
118
119This is not actually an attribute, but you use it like one. It expands
120either to C<static inline> or to just C<static>, if inline isn't
121supported. It should be used to declare functions that should be inlined,
122for code size or speed reasons.
123
124Example: inline this function, it surely will reduce codesize.
125
126 ecb_inline int
127 negmul (int a, int b)
31 { 128 {
32 int var ecb_unused; 129 return - (a * b);
33
34 #ifdef SOMECONDITION
35 var = ...;
36 return var;
37 #else
38 return 0;
39 #endif
40 } 130 }
41 131
42=item ecb_noinline 132=item ecb_noinline
43 133
44Prevent a function from being inlined - it might be optimsied away, but 134Prevent a function from being inlined - it might be optimised away, but
45not inlined into other functions. This is useful if you know your function 135not inlined into other functions. This is useful if you know your function
46is rarely called and large enough for inlining not to be helpful. 136is rarely called and large enough for inlining not to be helpful.
47 137
48=item ecb_noreturn 138=item ecb_noreturn
49 139
140Marks a function as "not returning, ever". Some typical functions that
141don't return are C<exit> or C<abort> (which really works hard to not
142return), and now you can make your own:
143
144 ecb_noreturn void
145 my_abort (const char *errline)
146 {
147 puts (errline);
148 abort ();
149 }
150
151In this case, the compiler would probably be smart enough to deduce it on
152its own, so this is mainly useful for declarations.
153
50=item ecb_const 154=item ecb_const
51 155
156Declares that the function only depends on the values of its arguments,
157much like a mathematical function. It specifically does not read or write
158any memory any arguments might point to, global variables, or call any
159non-const functions. It also must not have any side effects.
160
161Such a function can be optimised much more aggressively by the compiler -
162for example, multiple calls with the same arguments can be optimised into
163a single call, which wouldn't be possible if the compiler would have to
164expect any side effects.
165
166It is best suited for functions in the sense of mathematical functions,
167such as a function returning the square root of its input argument.
168
169Not suited would be a function that calculates the hash of some memory
170area you pass in, prints some messages or looks at a global variable to
171decide on rounding.
172
173See C<ecb_pure> for a slightly less restrictive class of functions.
174
52=item ecb_pure 175=item ecb_pure
53 176
177Similar to C<ecb_const>, declares a function that has no side
178effects. Unlike C<ecb_const>, the function is allowed to examine global
179variables and any other memory areas (such as the ones passed to it via
180pointers).
181
182While these functions cannot be optimised as aggressively as C<ecb_const>
183functions, they can still be optimised away in many occasions, and the
184compiler has more freedom in moving calls to them around.
185
186Typical examples for such functions would be C<strlen> or C<memcmp>. A
187function that calculates the MD5 sum of some input and updates some MD5
188state passed as argument would I<NOT> be pure, however, as it would modify
189some memory area that is not the return value.
190
54=item ecb_hot 191=item ecb_hot
55 192
193This declares a function as "hot" with regards to the cache - the function
194is used so often, that it is very beneficial to keep it in the cache if
195possible.
196
197The compiler reacts by trying to place hot functions near to each other in
198memory.
199
200Whether a function is hot or not often depends on the whole program,
201and less on the function itself. C<ecb_cold> is likely more useful in
202practise.
203
56=item ecb_cold 204=item ecb_cold
57 205
206The opposite of C<ecb_hot> - declares a function as "cold" with regards to
207the cache, or in other words, this function is not called often, or not at
208speed-critical times, and keeping it in the cache might be a waste of said
209cache.
210
211In addition to placing cold functions together (or at least away from hot
212functions), this knowledge can be used in other ways, for example, the
213function will be optimised for size, as opposed to speed, and codepaths
214leading to calls to those functions can automatically be marked as if
215C<ecb_expect_false> had been used to reach them.
216
217Good examples for such functions would be error reporting functions, or
218functions only called in exceptional or rare cases.
219
58=item ecb_artificial 220=item ecb_artificial
221
222Declares the function as "artificial", in this case meaning that this
223function is not really mean to be a function, but more like an accessor
224- many methods in C++ classes are mere accessor functions, and having a
225crash reported in such a method, or single-stepping through them, is not
226usually so helpful, especially when it's inlined to just a few instructions.
227
228Marking them as artificial will instruct the debugger about just this,
229leading to happier debugging and thus happier lives.
230
231Example: in some kind of smart-pointer class, mark the pointer accessor as
232artificial, so that the whole class acts more like a pointer and less like
233some C++ abstraction monster.
234
235 template<typename T>
236 struct my_smart_ptr
237 {
238 T *value;
239
240 ecb_artificial
241 operator T *()
242 {
243 return value;
244 }
245 };
59 246
60=back 247=back
61 248
62=head2 OPTIMISATION HINTS 249=head2 OPTIMISATION HINTS
63 250
95 282
96Evaluates C<expr> and returns it. In addition, it tells the compiler that 283Evaluates C<expr> and returns it. In addition, it tells the compiler that
97the C<expr> evaluates to C<value> a lot, which can be used for static 284the C<expr> evaluates to C<value> a lot, which can be used for static
98branch optimisations. 285branch optimisations.
99 286
100Usually, you want to use the more intuitive C<ecb_likely> and 287Usually, you want to use the more intuitive C<ecb_expect_true> and
101C<ecb_unlikely> functions instead. 288C<ecb_expect_false> functions instead.
102 289
103=item bool ecb_likely (bool) 290=item bool ecb_expect_true (cond)
104 291
105=item bool ecb_unlikely (bool) 292=item bool ecb_expect_false (cond)
106 293
107These two functions expect a expression that is true or false and return 294These two functions expect a expression that is true or false and return
108C<1> or C<0>, respectively, so when used in the condition of an C<if> or 295C<1> or C<0>, respectively, so when used in the condition of an C<if> or
109other conditional statement, it will not change the program: 296other conditional statement, it will not change the program:
110 297
111 /* these two do the same thing */ 298 /* these two do the same thing */
112 if (some_condition) ...; 299 if (some_condition) ...;
113 if (ecb_likely (some_condition)) ...; 300 if (ecb_expect_true (some_condition)) ...;
114 301
115However, by using C<ecb_likely>, you tell the compiler that the condition 302However, by using C<ecb_expect_true>, you tell the compiler that the
116is likely to be true (and for C<ecb_unlikel>, that it is unlikely to be 303condition is likely to be true (and for C<ecb_expect_false>, that it is
117true). 304unlikely to be true).
118 305
119For example, when you check for a 0-ptr and expect this to be a rare, 306For example, when you check for a null pointer and expect this to be a
120exceptional, case, then use C<ecb_unlikely>: 307rare, exceptional, case, then use C<ecb_expect_false>:
121 308
122 void my_free (void *ptr) 309 void my_free (void *ptr)
123 { 310 {
124 if (ecb_unlikely (ptr == 0)) 311 if (ecb_expect_false (ptr == 0))
125 return; 312 return;
126 } 313 }
127 314
128Consequent use of these functions to mark away exceptional cases or to 315Consequent use of these functions to mark away exceptional cases or to
129tell the compiler what the hot path through a function is can increase 316tell the compiler what the hot path through a function is can increase
130performance considerably. 317performance considerably.
131 318
319You might know these functions under the name C<likely> and C<unlikely>
320- while these are common aliases, we find that the expect name is easier
321to understand when quickly skimming code. If you wish, you can use
322C<ecb_likely> instead of C<ecb_expect_true> and C<ecb_unlikely> instead of
323C<ecb_expect_false> - these are simply aliases.
324
132A very good example is in a function that reserves more space for some 325A very good example is in a function that reserves more space for some
133memory block (for example, inside an implementation of a string stream) - 326memory block (for example, inside an implementation of a string stream) -
134eahc time something is added, you have to check for a buffer overrun, but 327each time something is added, you have to check for a buffer overrun, but
135you expect that most checks will turn out to be false: 328you expect that most checks will turn out to be false:
136 329
137 /* make sure we have "size" extra room in our buffer */ 330 /* make sure we have "size" extra room in our buffer */
138 ecb_inline void 331 ecb_inline void
139 reserve (int size) 332 reserve (int size)
140 { 333 {
141 if (ecb_unlikely (current + size > end)) 334 if (ecb_expect_false (current + size > end))
142 real_reserve_method (size); /* presumably noinline */ 335 real_reserve_method (size); /* presumably noinline */
143 } 336 }
144 337
145=item bool ecb_assume (cond) 338=item bool ecb_assume (cond)
146 339
149 342
150This can be used to teach the compiler about invariants or other 343This can be used to teach the compiler about invariants or other
151conditions that might improve code generation, but which are impossible to 344conditions that might improve code generation, but which are impossible to
152deduce form the code itself. 345deduce form the code itself.
153 346
154For example, the example reservation function from the C<ecb_unlikely> 347For example, the example reservation function from the C<ecb_expect_false>
155description could be written thus (only C<ecb_assume> was added): 348description could be written thus (only C<ecb_assume> was added):
156 349
157 ecb_inline void 350 ecb_inline void
158 reserve (int size) 351 reserve (int size)
159 { 352 {
160 if (ecb_unlikely (current + size > end)) 353 if (ecb_expect_false (current + size > end))
161 real_reserve_method (size); /* presumably noinline */ 354 real_reserve_method (size); /* presumably noinline */
162 355
163 ecb_assume (current + size <= end); 356 ecb_assume (current + size <= end);
164 } 357 }
165 358
173call will never be executed. 366call will never be executed.
174 367
175=item bool ecb_unreachable () 368=item bool ecb_unreachable ()
176 369
177This function does nothing itself, except tell the compiler that it will 370This function does nothing itself, except tell the compiler that it will
178never be executed. Apart from supressing a warning in some cases, this 371never be executed. Apart from suppressing a warning in some cases, this
179function can be used to implement C<ecb_assume> or similar functions. 372function can be used to implement C<ecb_assume> or similar functions.
180 373
181=item bool ecb_prefetch (addr, rw, locality) 374=item bool ecb_prefetch (addr, rw, locality)
182 375
183Tells the compiler to try to prefetch memory at the given C<addr>ess 376Tells the compiler to try to prefetch memory at the given C<addr>ess
184for either reading (c<rw> = 0) or writing (C<rw> = 1). A C<locality> of 377for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
185C<0> means that there will only be one access later, C<3> means that 378C<0> means that there will only be one access later, C<3> means that
186the data will likely be accessed very often, and values in between mean 379the data will likely be accessed very often, and values in between mean
187something... in between. The memory pointed to by the address does not 380something... in between. The memory pointed to by the address does not
188need to be accessible (it could be a null pointer for example), but C<rw> 381need to be accessible (it could be a null pointer for example), but C<rw>
189and C<locality> must be compile-time constants. 382and C<locality> must be compile-time constants.
190 383
191An obvious way to use this is to prefetch some data far away, in a big 384An obvious way to use this is to prefetch some data far away, in a big
192array you loop over. This prefethces memory some 128 array elements later, 385array you loop over. This prefetches memory some 128 array elements later,
193in the hope that it will be ready when the CPU arrives at that location. 386in the hope that it will be ready when the CPU arrives at that location.
194 387
195 int sum = 0; 388 int sum = 0;
196 389
197 for (i = 0; i < N; ++i) 390 for (i = 0; i < N; ++i)
214After processing the node, (part of) the next node might already be in 407After processing the node, (part of) the next node might already be in
215cache. 408cache.
216 409
217=back 410=back
218 411
219=head2 BIT FIDDLING / BITSTUFFS 412=head2 BIT FIDDLING / BIT WIZARDRY
220 413
221=over 4 414=over 4
222 415
223=item bool ecb_big_endian () 416=item bool ecb_big_endian ()
224 417
225=item bool ecb_little_endian () 418=item bool ecb_little_endian ()
226 419
420These two functions return true if the byte order is big endian
421(most-significant byte first) or little endian (least-significant byte
422first) respectively.
423
424On systems that are neither, their return values are unspecified.
425
227=item int ecb_ctz32 (uint32_t x) 426=item int ecb_ctz32 (uint32_t x)
228 427
428=item int ecb_ctz64 (uint64_t x)
429
430Returns the index of the least significant bit set in C<x> (or
431equivalently the number of bits set to 0 before the least significant bit
432set), starting from 0. If C<x> is 0 the result is undefined.
433
434For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
435
436For example:
437
438 ecb_ctz32 (3) = 0
439 ecb_ctz32 (6) = 1
440
441=item bool ecb_is_pot32 (uint32_t x)
442
443=item bool ecb_is_pot64 (uint32_t x)
444
445Return true iff C<x> is a power of two or C<x == 0>.
446
447For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
448
449=item int ecb_ld32 (uint32_t x)
450
451=item int ecb_ld64 (uint64_t x)
452
453Returns the index of the most significant bit set in C<x>, or the number
454of digits the number requires in binary (so that C<< 2**ld <= x <
4552**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
456to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
457example to see how many bits a certain number requires to be encoded.
458
459This function is similar to the "count leading zero bits" function, except
460that that one returns how many zero bits are "in front" of the number (in
461the given data type), while C<ecb_ld> returns how many bits the number
462itself requires.
463
464For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
465
229=item int ecb_popcount32 (uint32_t x) 466=item int ecb_popcount32 (uint32_t x)
230 467
468=item int ecb_popcount64 (uint64_t x)
469
470Returns the number of bits set to 1 in C<x>.
471
472For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
473
474For example:
475
476 ecb_popcount32 (7) = 3
477 ecb_popcount32 (255) = 8
478
479=item uint8_t ecb_bitrev8 (uint8_t x)
480
481=item uint16_t ecb_bitrev16 (uint16_t x)
482
483=item uint32_t ecb_bitrev32 (uint32_t x)
484
485Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
486and so on.
487
488Example:
489
490 ecb_bitrev8 (0xa7) = 0xea
491 ecb_bitrev32 (0xffcc4411) = 0x882233ff
492
493=item uint32_t ecb_bswap16 (uint32_t x)
494
231=item uint32_t ecb_bswap32 (uint32_t x) 495=item uint32_t ecb_bswap32 (uint32_t x)
232 496
233=item uint32_t ecb_bswap16 (uint32_t x) 497=item uint64_t ecb_bswap64 (uint64_t x)
498
499These functions return the value of the 16-bit (32-bit, 64-bit) value
500C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
501C<ecb_bswap32>).
502
503=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
504
505=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
506
507=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
508
509=item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
510
511=item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
512
513=item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
234 514
235=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count) 515=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
236 516
237=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count) 517=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
518
519These two families of functions return the value of C<x> after rotating
520all the bits by C<count> positions to the right (C<ecb_rotr>) or left
521(C<ecb_rotl>).
522
523Current GCC versions understand these functions and usually compile them
524to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
525x86).
238 526
239=back 527=back
240 528
241=head2 ARITHMETIC 529=head2 ARITHMETIC
242 530
243=over 4 531=over 4
244 532
245=item x = ecb_mod (m, n) [MACRO] 533=item x = ecb_mod (m, n)
534
535Returns C<m> modulo C<n>, which is the same as the positive remainder
536of the division operation between C<m> and C<n>, using floored
537division. Unlike the C remainder operator C<%>, this function ensures that
538the return value is always positive and that the two numbers I<m> and
539I<m' = m + i * n> result in the same value modulo I<n> - in other words,
540C<ecb_mod> implements the mathematical modulo operation, which is missing
541in the language.
542
543C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
544negatable, that is, both C<m> and C<-m> must be representable in its
545type (this typically excludes the minimum signed integer value, the same
546limitation as for C</> and C<%> in C).
547
548Current GCC versions compile this into an efficient branchless sequence on
549almost all CPUs.
550
551For example, when you want to rotate forward through the members of an
552array for increasing C<m> (which might be negative), then you should use
553C<ecb_mod>, as the C<%> operator might give either negative results, or
554change direction for negative values:
555
556 for (m = -100; m <= 100; ++m)
557 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
558
559=item x = ecb_div_rd (val, div)
560
561=item x = ecb_div_ru (val, div)
562
563Returns C<val> divided by C<div> rounded down or up, respectively.
564C<val> and C<div> must have integer types and C<div> must be strictly
565positive. Note that these functions are implemented with macros in C
566and with function templates in C++.
246 567
247=back 568=back
248 569
249=head2 UTILITY 570=head2 UTILITY
250 571
251=over 4 572=over 4
252 573
253=item ecb_array_length (name) [MACRO] 574=item element_count = ecb_array_length (name)
575
576Returns the number of elements in the array C<name>. For example:
577
578 int primes[] = { 2, 3, 5, 7, 11 };
579 int sum = 0;
580
581 for (i = 0; i < ecb_array_length (primes); i++)
582 sum += primes [i];
254 583
255=back 584=back
256 585
257 586

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines