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

Comparing libecb/ecb.pod (file contents):
Revision 1.14 by root, Thu May 26 23:23:08 2011 UTC vs.
Revision 1.18 by root, Fri May 27 00:01:28 2011 UTC

… …
3=head2 ABOUT LIBECB 3=head2 ABOUT LIBECB
4 4
5Libecb is currently a simple header file that doesn't require any 5Libecb is currently a simple header file that doesn't require any
6configuration to use or include in your project. 6configuration to use or include in your project.
7 7
8It's part of the e-suite of libraries, other memembers of which include 8It's part of the e-suite of libraries, other members of which include
9libev and libeio. 9libev and libeio.
10 10
11Its homepage can be found here: 11Its homepage can be found here:
12 12
13 http://software.schmorp.de/pkg/libecb 13 http://software.schmorp.de/pkg/libecb
14 14
15It mainly provides a number of wrappers around GCC built-ins, together 15It mainly provides a number of wrappers around GCC built-ins, together
16with replacement functions for other compilers. In addition to this, 16with replacement functions for other compilers. In addition to this,
17it provides a number of other lowlevel C utilities, such endienness 17it provides a number of other lowlevel C utilities, such as endianness
18detection, byte swapping or bit rotations. 18detection, byte swapping or bit rotations.
19
20Or in other words, things that should be built-in into any standard C
21system, but aren't.
19 22
20More might come. 23More might come.
21 24
22=head2 ABOUT THE HEADER 25=head2 ABOUT THE HEADER
23 26
… …
27 #include <ecb.h> 30 #include <ecb.h>
28 31
29The header should work fine for both C and C++ compilation, and gives you 32The header should work fine for both C and C++ compilation, and gives you
30all of F<inttypes.h> in addition to the ECB symbols. 33all of F<inttypes.h> in addition to the ECB symbols.
31 34
32There are currently no objetc files to link to - future versions might 35There are currently no object files to link to - future versions might
33come with an (optional) object code library to link against, to reduce 36come with an (optional) object code library to link against, to reduce
34code size or gain access to additional features. 37code size or gain access to additional features.
35 38
36It also currently includes everything from F<inttypes.h>. 39It also currently includes everything from F<inttypes.h>.
37 40
… …
58 61
59=over 4 62=over 4
60 63
61=item ecb_attribute ((attrs...)) 64=item ecb_attribute ((attrs...))
62 65
63A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and 66A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
64to nothing on other compilers, so the effect is that only GCC sees these. 67nothing on other compilers, so the effect is that only GCC sees these.
68
69Example: use the C<deprecated> attribute on a function.
70
71 ecb_attribute((__deprecated__)) void
72 do_not_use_me_anymore (void);
65 73
66=item ecb_unused 74=item ecb_unused
67 75
68Marks a function or a variable as "unused", which simply suppresses a 76Marks a function or a variable as "unused", which simply suppresses a
69warning by GCC when it detects it as unused. This is useful when you e.g. 77warning by GCC when it detects it as unused. This is useful when you e.g.
70declare a variable but do not always use it: 78declare a variable but do not always use it:
71 79
72 { 80 {
73 int var ecb_unused; 81 int var ecb_unused;
74 82
75 #ifdef SOMECONDITION 83 #ifdef SOMECONDITION
76 var = ...; 84 var = ...;
77 return var; 85 return var;
78 #else 86 #else
79 return 0; 87 return 0;
80 #endif 88 #endif
81 } 89 }
82 90
83=item ecb_noinline 91=item ecb_noinline
84 92
85Prevent a function from being inlined - it might be optimised away, but 93Prevent a function from being inlined - it might be optimised away, but
86not inlined into other functions. This is useful if you know your function 94not inlined into other functions. This is useful if you know your function
87is rarely called and large enough for inlining not to be helpful. 95is rarely called and large enough for inlining not to be helpful.
88 96
89=item ecb_noreturn 97=item ecb_noreturn
90 98
99Marks a function as "not returning, ever". Some typical functions that
100don't return are C<exit> or C<abort> (which really works hard to not
101return), and now you can make your own:
102
103 ecb_noreturn void
104 my_abort (const char *errline)
105 {
106 puts (errline);
107 abort ();
108 }
109
110In this case, the compiler would probbaly be smart enough to decude it on
111it's own, so this is mainly useful for declarations.
112
91=item ecb_const 113=item ecb_const
92 114
115Declares that the function only depends on the values of it's arguments,
116much like a mathematical function. It specifically does not read or write
117any memory any arguments might point to, global variables, or call any
118non-const functions. It also must not have any side effects.
119
120Such a function can be optimised much more aggressively by the compiler -
121for example, multiple calls with the same arguments can be optimised into
122a single call, which wouldn't be possible if the compiler would have to
123expect any side effects.
124
125It is best suited for functions in the sense of mathematical functions,
126such as a function return the square root of its input argument.
127
128Not suited would be a function that calculates the hash of some memory
129area you pass in, prints some messages or looks at a global variable to
130decide on rounding.
131
132See C<ecb_pure> for a slightly less restrictive class of functions.
133
93=item ecb_pure 134=item ecb_pure
94 135
136Similar to C<ecb_const>, declares a function that has no side
137effects. Unlike C<ecb_const>, the function is allowed to examine global
138variables and any other memory areas (such as the ones passed to it via
139pointers).
140
141While these functions cannot be optimised as aggressively as C<ecb_const>
142functions, they can still be optimised away in many occasions, and the
143compiler has more freedom in moving calls to them around.
144
145Typical examples for such functions would be C<strlen> or C<memcmp>. A
146function that calculates the MD5 sum of some input and updates some MD5
147state passed as argument would I<NOT> be pure, however, as it would modify
148some memory area that is not the return value.
149
95=item ecb_hot 150=item ecb_hot
96 151
152This declares a function as "hot" with regards to the cache - the function
153is used so often, that it is very beneficial to keep it in the cache if
154possible.
155
156The compiler reacts by trying to place hot functions near to each other in
157memory.
158
159Whether a function is hot or not often depend son the whole program,
160and less on the function itself. C<ecb_cold> is likely more useful in
161practise.
162
97=item ecb_cold 163=item ecb_cold
98 164
165The opposite of C<ecb_hot> - declares a function as "cold" with regards to
166the cache, or in other words, this function is not called often, or not at
167speed-critical times, and keeping it in the cache might be a waste of said
168cache.
169
170In addition to placing cold functions together (or at least away from hot
171functions), this knowledge can be used in other ways, for example, the
172function will be optimised for size, as opposed to speed, and codepaths
173leading to calls to those functions can automatically be marked as if
174C<ecb_unlikel> had been used to reach them.
175
176Good examples for such functions would be error reporting functions, or
177functions only called in exceptional or rare cases.
178
99=item ecb_artificial 179=item ecb_artificial
180
181Declares the function as "artificial", in this case meaning that this
182function is not really mean to be a function, but more like an accessor
183- many methods in C++ classes are mere accessor functions, and having a
184crash reported in such a method, or single-stepping through them, is not
185usually so helpful, especially when it's inlined to just a few instructions.
186
187Marking them as artificial will instruct the debugger about just this,
188leading to happier debugging and thus happier lives.
189
190Example: in some kind of smart-pointer class, mark the pointer accessor as
191artificial, so that the whole class acts more like a pointer and less like
192some C++ abstraction monster.
193
194 template<typename T>
195 struct my_smart_ptr
196 {
197 T *value;
198
199 ecb_artificial
200 operator T *()
201 {
202 return value;
203 }
204 };
100 205
101=back 206=back
102 207
103=head2 OPTIMISATION HINTS 208=head2 OPTIMISATION HINTS
104 209
… …
139branch optimisations. 244branch optimisations.
140 245
141Usually, you want to use the more intuitive C<ecb_likely> and 246Usually, you want to use the more intuitive C<ecb_likely> and
142C<ecb_unlikely> functions instead. 247C<ecb_unlikely> functions instead.
143 248
144=item bool ecb_likely (bool) 249=item bool ecb_likely (cond)
145 250
146=item bool ecb_unlikely (bool) 251=item bool ecb_unlikely (cond)
147 252
148These two functions expect a expression that is true or false and return 253These two functions expect a expression that is true or false and return
149C<1> or C<0>, respectively, so when used in the condition of an C<if> or 254C<1> or C<0>, respectively, so when used in the condition of an C<if> or
150other conditional statement, it will not change the program: 255other conditional statement, it will not change the program:
151 256
… …
275equivalently the number of bits set to 0 before the least significant 380equivalently the number of bits set to 0 before the least significant
276bit set), starting from 0. If C<x> is 0 the result is undefined. A 381bit set), starting from 0. If C<x> is 0 the result is undefined. A
277common use case is to compute the integer binary logarithm, i.e., 382common use case is to compute the integer binary logarithm, i.e.,
278floor(log2(n)). For example: 383floor(log2(n)). For example:
279 384
280 ecb_ctz32(3) = 0 385 ecb_ctz32 (3) = 0
281 ecb_ctz32(6) = 1 386 ecb_ctz32 (6) = 1
282 387
283=item int ecb_popcount32 (uint32_t x) 388=item int ecb_popcount32 (uint32_t x)
284 389
285Returns the number of bits set to 1 in C<x>. For example: 390Returns the number of bits set to 1 in C<x>. For example:
286 391
287 ecb_popcount32(7) = 3 392 ecb_popcount32 (7) = 3
288 ecb_popcount32(255) = 8 393 ecb_popcount32 (255) = 8
289 394
290=item uint32_t ecb_bswap16 (uint32_t x) 395=item uint32_t ecb_bswap16 (uint32_t x)
291 396
292=item uint32_t ecb_bswap32 (uint32_t x) 397=item uint32_t ecb_bswap32 (uint32_t x)
293 398
… …
308=over 4 413=over 4
309 414
310=item x = ecb_mod (m, n) 415=item x = ecb_mod (m, n)
311 416
312Returns the positive remainder of the modulo operation between C<m> and 417Returns the positive remainder of the modulo operation between C<m> and
313C<n>. Unlike the C moduloe operator C<%>, this function ensures that the 418C<n>. Unlike the C modulo operator C<%>, this function ensures that the
314return value is always positive). 419return value is always positive).
315 420
316C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be 421C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be
317negatable, that is, both C<m> and C<-m> must be representable in its 422negatable, that is, both C<m> and C<-m> must be representable in its
318type. 423type.

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines