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

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.14 by root, Thu May 26 23:23:08 2011 UTC vs.
Revision 1.16 by sf-exg, Thu May 26 23:32:41 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 19
20More might come. 20More might come.
21 21
22=head2 ABOUT THE HEADER 22=head2 ABOUT THE HEADER
… …
27 #include <ecb.h> 27 #include <ecb.h>
28 28
29The header should work fine for both C and C++ compilation, and gives you 29The header should work fine for both C and C++ compilation, and gives you
30all of F<inttypes.h> in addition to the ECB symbols. 30all of F<inttypes.h> in addition to the ECB symbols.
31 31
32There are currently no objetc files to link to - future versions might 32There are currently no object files to link to - future versions might
33come with an (optional) object code library to link against, to reduce 33come with an (optional) object code library to link against, to reduce
34code size or gain access to additional features. 34code size or gain access to additional features.
35 35
36It also currently includes everything from F<inttypes.h>. 36It also currently includes everything from F<inttypes.h>.
37 37
… …
58 58
59=over 4 59=over 4
60 60
61=item ecb_attribute ((attrs...)) 61=item ecb_attribute ((attrs...))
62 62
63A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and 63A 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. 64nothing on other compilers, so the effect is that only GCC sees these.
65
66Example: use the C<deprecated> attribute on a function.
67
68 ecb_attribute((__deprecated__)) void
69 do_not_use_me_anymore (void);
65 70
66=item ecb_unused 71=item ecb_unused
67 72
68Marks a function or a variable as "unused", which simply suppresses a 73Marks 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. 74warning by GCC when it detects it as unused. This is useful when you e.g.
70declare a variable but do not always use it: 75declare a variable but do not always use it:
71 76
72 { 77 {
73 int var ecb_unused; 78 int var ecb_unused;
74 79
75 #ifdef SOMECONDITION 80 #ifdef SOMECONDITION
76 var = ...; 81 var = ...;
77 return var; 82 return var;
78 #else 83 #else
79 return 0; 84 return 0;
80 #endif 85 #endif
81 } 86 }
82 87
83=item ecb_noinline 88=item ecb_noinline
84 89
85Prevent a function from being inlined - it might be optimised away, but 90Prevent a function from being inlined - it might be optimised away, but
86not inlined into other functions. This is useful if you know your function 91not inlined into other functions. This is useful if you know your function
… …
139branch optimisations. 144branch optimisations.
140 145
141Usually, you want to use the more intuitive C<ecb_likely> and 146Usually, you want to use the more intuitive C<ecb_likely> and
142C<ecb_unlikely> functions instead. 147C<ecb_unlikely> functions instead.
143 148
144=item bool ecb_likely (bool) 149=item bool ecb_likely (cond)
145 150
146=item bool ecb_unlikely (bool) 151=item bool ecb_unlikely (cond)
147 152
148These two functions expect a expression that is true or false and return 153These 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 154C<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: 155other conditional statement, it will not change the program:
151 156
… …
275equivalently the number of bits set to 0 before the least significant 280equivalently 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 281bit 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., 282common use case is to compute the integer binary logarithm, i.e.,
278floor(log2(n)). For example: 283floor(log2(n)). For example:
279 284
280 ecb_ctz32(3) = 0 285 ecb_ctz32 (3) = 0
281 ecb_ctz32(6) = 1 286 ecb_ctz32 (6) = 1
282 287
283=item int ecb_popcount32 (uint32_t x) 288=item int ecb_popcount32 (uint32_t x)
284 289
285Returns the number of bits set to 1 in C<x>. For example: 290Returns the number of bits set to 1 in C<x>. For example:
286 291
287 ecb_popcount32(7) = 3 292 ecb_popcount32 (7) = 3
288 ecb_popcount32(255) = 8 293 ecb_popcount32 (255) = 8
289 294
290=item uint32_t ecb_bswap16 (uint32_t x) 295=item uint32_t ecb_bswap16 (uint32_t x)
291 296
292=item uint32_t ecb_bswap32 (uint32_t x) 297=item uint32_t ecb_bswap32 (uint32_t x)
293 298
… …
308=over 4 313=over 4
309 314
310=item x = ecb_mod (m, n) 315=item x = ecb_mod (m, n)
311 316
312Returns the positive remainder of the modulo operation between C<m> and 317Returns the positive remainder of the modulo operation between C<m> and
313C<n>. Unlike the C moduloe operator C<%>, this function ensures that the 318C<n>. Unlike the C modulo operator C<%>, this function ensures that the
314return value is always positive). 319return value is always positive).
315 320
316C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be 321C<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 322negatable, that is, both C<m> and C<-m> must be representable in its
318type. 323type.

Diff Legend

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