ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
Revision: 1.54
Committed: Wed Dec 19 23:33:47 2012 UTC (11 years, 5 months ago) by root
Branch: MAIN
Changes since 1.53: +11 -0 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.14 =head1 LIBECB - e-C-Builtins
2 root 1.3
3 root 1.14 =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 sf-exg 1.16 It's part of the e-suite of libraries, other members of which include
9 root 1.14 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 sf-exg 1.16 it provides a number of other lowlevel C utilities, such as endianness
18 root 1.14 detection, byte swapping or bit rotations.
19    
20 root 1.24 Or in other words, things that should be built into any standard C system,
21     but aren't, implemented as efficient as possible with GCC, and still
22     correct with other compilers.
23 root 1.17
24 root 1.14 More might come.
25 root 1.3
26     =head2 ABOUT THE HEADER
27    
28 root 1.14 At the moment, all you have to do is copy F<ecb.h> somewhere where your
29     compiler can find it and include it:
30    
31     #include <ecb.h>
32    
33     The header should work fine for both C and C++ compilation, and gives you
34     all of F<inttypes.h> in addition to the ECB symbols.
35    
36 sf-exg 1.16 There are currently no object files to link to - future versions might
37 root 1.14 come with an (optional) object code library to link against, to reduce
38     code size or gain access to additional features.
39    
40     It also currently includes everything from F<inttypes.h>.
41    
42     =head2 ABOUT THIS MANUAL / CONVENTIONS
43    
44     This manual mainly describes each (public) function available after
45     including the F<ecb.h> header. The header might define other symbols than
46     these, but these are not part of the public API, and not supported in any
47     way.
48    
49     When the manual mentions a "function" then this could be defined either as
50     as inline function, a macro, or an external symbol.
51    
52     When functions use a concrete standard type, such as C<int> or
53     C<uint32_t>, then the corresponding function works only with that type. If
54     only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
55     the corresponding function relies on C to implement the correct types, and
56     is usually implemented as a macro. Specifically, a "bool" in this manual
57     refers to any kind of boolean value, not a specific type.
58 root 1.1
59 root 1.40 =head2 TYPES / TYPE SUPPORT
60    
61     ecb.h makes sure that the following types are defined (in the expected way):
62    
63 root 1.42 int8_t uint8_t int16_t uint16_t
64     int32_t uint32_t int64_t uint64_t
65 root 1.49 intptr_t uintptr_t
66 root 1.40
67     The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
68 root 1.45 platform (currently C<4> or C<8>) and can be used in preprocessor
69     expressions.
70 root 1.40
71 root 1.49 For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
72    
73 root 1.43 =head2 LANGUAGE/COMPILER VERSIONS
74    
75 sf-exg 1.46 All the following symbols expand to an expression that can be tested in
76 root 1.44 preprocessor instructions as well as treated as a boolean (use C<!!> to
77     ensure it's either C<0> or C<1> if you need that).
78    
79 root 1.43 =over 4
80    
81 root 1.44 =item ECB_C
82    
83     True if the implementation defines the C<__STDC__> macro to a true value,
84     which is typically true for both C and C++ compilers.
85    
86 root 1.43 =item ECB_C99
87    
88 root 1.47 True if the implementation claims to be compliant to C99 (ISO/IEC
89     9899:1999) or any later version.
90    
91     Note that later versions (ECB_C11) remove core features again (for
92     example, variable length arrays).
93 root 1.43
94     =item ECB_C11
95    
96 root 1.47 True if the implementation claims to be compliant to C11 (ISO/IEC
97     9899:2011) or any later version.
98 root 1.44
99     =item ECB_CPP
100    
101     True if the implementation defines the C<__cplusplus__> macro to a true
102     value, which is typically true for C++ compilers.
103    
104     =item ECB_CPP11
105    
106     True if the implementation claims to be compliant to ISO/IEC 14882:2011
107 sf-exg 1.46 (C++11) or any later version.
108 root 1.43
109     =item ECB_GCC_VERSION(major,minor)
110    
111     Expands to a true value (suitable for testing in by the preprocessor)
112 sf-exg 1.46 if the compiler used is GNU C and the version is the given version, or
113 root 1.43 higher.
114    
115     This macro tries to return false on compilers that claim to be GCC
116     compatible but aren't.
117    
118 root 1.50 =item ECB_EXTERN_C
119    
120     Expands to C<extern "C"> in C++, and a simple C<extern> in C.
121    
122     This can be used to declare a single external C function:
123    
124     ECB_EXTERN_C int printf (const char *format, ...);
125    
126     =item ECB_EXTERN_C_BEG / ECB_EXTERN_C_END
127    
128     These two macros can be used to wrap multiple C<extern "C"> definitions -
129     they expand to nothing in C.
130    
131     They are most useful in header files:
132    
133     ECB_EXTERN_C_BEG
134    
135     int mycfun1 (int x);
136     int mycfun2 (int x);
137    
138     ECB_EXTERN_C_END
139    
140     =item ECB_STDFP
141    
142     If this evaluates to a true value (suitable for testing in by the
143     preprocessor), then C<float> and C<double> use IEEE 754 single/binary32
144     and double/binary64 representations internally I<and> the endianness of
145     both types match the endianness of C<uint32_t> and C<uint64_t>.
146    
147     This means you can just copy the bits of a C<float> (or C<double>) to an
148     C<uint32_t> (or C<uint64_t>) and get the raw IEEE 754 bit representation
149     without having to think about format or endianness.
150    
151     This is true for basically all modern platforms, although F<ecb.h> might
152     not be able to deduce this correctly everywhere and might err on the safe
153     side.
154    
155 root 1.54 =item ECB_AMD64, ECB_AMD64_X32
156    
157     These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32
158     ABI, respectively, and undefined elsewhere.
159    
160     The designers of the new X32 ABI for some inexplicable reason decided to
161     make it look exactly like amd64, even though it's completely incompatible
162     to that ABI, breaking about every piece of software that assumed that
163     C<__x86_64> stands for, well, the x86-64 ABI, making these macros
164     necessary.
165    
166 root 1.43 =back
167    
168 root 1.1 =head2 GCC ATTRIBUTES
169    
170 root 1.20 A major part of libecb deals with GCC attributes. These are additional
171 sf-exg 1.26 attributes that you can assign to functions, variables and sometimes even
172 root 1.20 types - much like C<const> or C<volatile> in C.
173    
174     While GCC allows declarations to show up in many surprising places,
175 sf-exg 1.26 but not in many expected places, the safest way is to put attribute
176 root 1.20 declarations before the whole declaration:
177    
178     ecb_const int mysqrt (int a);
179     ecb_unused int i;
180    
181     For variables, it is often nicer to put the attribute after the name, and
182     avoid multiple declarations using commas:
183    
184     int i ecb_unused;
185 root 1.3
186 root 1.1 =over 4
187    
188 root 1.2 =item ecb_attribute ((attrs...))
189 root 1.1
190 root 1.15 A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
191     nothing on other compilers, so the effect is that only GCC sees these.
192    
193     Example: use the C<deprecated> attribute on a function.
194    
195     ecb_attribute((__deprecated__)) void
196     do_not_use_me_anymore (void);
197 root 1.2
198 root 1.3 =item ecb_unused
199    
200     Marks a function or a variable as "unused", which simply suppresses a
201     warning by GCC when it detects it as unused. This is useful when you e.g.
202     declare a variable but do not always use it:
203    
204 root 1.15 {
205     int var ecb_unused;
206 root 1.3
207 root 1.15 #ifdef SOMECONDITION
208     var = ...;
209     return var;
210     #else
211     return 0;
212     #endif
213     }
214 root 1.3
215 root 1.31 =item ecb_inline
216 root 1.29
217     This is not actually an attribute, but you use it like one. It expands
218     either to C<static inline> or to just C<static>, if inline isn't
219     supported. It should be used to declare functions that should be inlined,
220     for code size or speed reasons.
221    
222     Example: inline this function, it surely will reduce codesize.
223    
224 root 1.31 ecb_inline int
225 root 1.29 negmul (int a, int b)
226     {
227     return - (a * b);
228     }
229    
230 root 1.2 =item ecb_noinline
231    
232 root 1.9 Prevent a function from being inlined - it might be optimised away, but
233 root 1.3 not inlined into other functions. This is useful if you know your function
234     is rarely called and large enough for inlining not to be helpful.
235    
236 root 1.2 =item ecb_noreturn
237    
238 root 1.17 Marks a function as "not returning, ever". Some typical functions that
239     don't return are C<exit> or C<abort> (which really works hard to not
240     return), and now you can make your own:
241    
242     ecb_noreturn void
243     my_abort (const char *errline)
244     {
245     puts (errline);
246     abort ();
247     }
248    
249 sf-exg 1.19 In this case, the compiler would probably be smart enough to deduce it on
250     its own, so this is mainly useful for declarations.
251 root 1.17
252 root 1.53 =item ecb_restrict
253    
254     Expands to the C<restrict> keyword or equivalent on compilers that support
255     them, and to nothing on others. Must be specified on a pointer type or
256     an array index to indicate that the memory doesn't alias with any other
257     restricted pointer in the same scope.
258    
259     Example: multiply a vector, and allow the compiler to parallelise the
260     loop, because it knows it doesn't overwrite input values.
261    
262     void
263     multiply (float *ecb_restrict src,
264     float *ecb_restrict dst,
265     int len, float factor)
266     {
267     int i;
268    
269     for (i = 0; i < len; ++i)
270     dst [i] = src [i] * factor;
271     }
272    
273 root 1.2 =item ecb_const
274    
275 sf-exg 1.19 Declares that the function only depends on the values of its arguments,
276 root 1.17 much like a mathematical function. It specifically does not read or write
277     any memory any arguments might point to, global variables, or call any
278     non-const functions. It also must not have any side effects.
279    
280     Such a function can be optimised much more aggressively by the compiler -
281     for example, multiple calls with the same arguments can be optimised into
282     a single call, which wouldn't be possible if the compiler would have to
283     expect any side effects.
284    
285     It is best suited for functions in the sense of mathematical functions,
286 sf-exg 1.19 such as a function returning the square root of its input argument.
287 root 1.17
288     Not suited would be a function that calculates the hash of some memory
289     area you pass in, prints some messages or looks at a global variable to
290     decide on rounding.
291    
292     See C<ecb_pure> for a slightly less restrictive class of functions.
293    
294 root 1.2 =item ecb_pure
295    
296 root 1.17 Similar to C<ecb_const>, declares a function that has no side
297     effects. Unlike C<ecb_const>, the function is allowed to examine global
298     variables and any other memory areas (such as the ones passed to it via
299     pointers).
300    
301     While these functions cannot be optimised as aggressively as C<ecb_const>
302     functions, they can still be optimised away in many occasions, and the
303     compiler has more freedom in moving calls to them around.
304    
305     Typical examples for such functions would be C<strlen> or C<memcmp>. A
306     function that calculates the MD5 sum of some input and updates some MD5
307     state passed as argument would I<NOT> be pure, however, as it would modify
308     some memory area that is not the return value.
309    
310 root 1.2 =item ecb_hot
311    
312 root 1.17 This declares a function as "hot" with regards to the cache - the function
313     is used so often, that it is very beneficial to keep it in the cache if
314     possible.
315    
316     The compiler reacts by trying to place hot functions near to each other in
317     memory.
318    
319 sf-exg 1.19 Whether a function is hot or not often depends on the whole program,
320 root 1.17 and less on the function itself. C<ecb_cold> is likely more useful in
321     practise.
322    
323 root 1.2 =item ecb_cold
324    
325 root 1.17 The opposite of C<ecb_hot> - declares a function as "cold" with regards to
326     the cache, or in other words, this function is not called often, or not at
327     speed-critical times, and keeping it in the cache might be a waste of said
328     cache.
329    
330     In addition to placing cold functions together (or at least away from hot
331     functions), this knowledge can be used in other ways, for example, the
332     function will be optimised for size, as opposed to speed, and codepaths
333     leading to calls to those functions can automatically be marked as if
334 root 1.27 C<ecb_expect_false> had been used to reach them.
335 root 1.17
336     Good examples for such functions would be error reporting functions, or
337     functions only called in exceptional or rare cases.
338    
339 root 1.2 =item ecb_artificial
340    
341 root 1.17 Declares the function as "artificial", in this case meaning that this
342 root 1.52 function is not really meant to be a function, but more like an accessor
343 root 1.17 - many methods in C++ classes are mere accessor functions, and having a
344     crash reported in such a method, or single-stepping through them, is not
345     usually so helpful, especially when it's inlined to just a few instructions.
346    
347     Marking them as artificial will instruct the debugger about just this,
348     leading to happier debugging and thus happier lives.
349    
350     Example: in some kind of smart-pointer class, mark the pointer accessor as
351     artificial, so that the whole class acts more like a pointer and less like
352     some C++ abstraction monster.
353    
354     template<typename T>
355     struct my_smart_ptr
356     {
357     T *value;
358    
359     ecb_artificial
360     operator T *()
361     {
362     return value;
363     }
364     };
365    
366 root 1.2 =back
367 root 1.1
368     =head2 OPTIMISATION HINTS
369    
370     =over 4
371    
372 root 1.14 =item bool ecb_is_constant(expr)
373 root 1.1
374 root 1.3 Returns true iff the expression can be deduced to be a compile-time
375     constant, and false otherwise.
376    
377     For example, when you have a C<rndm16> function that returns a 16 bit
378     random number, and you have a function that maps this to a range from
379 root 1.5 0..n-1, then you could use this inline function in a header file:
380 root 1.3
381     ecb_inline uint32_t
382     rndm (uint32_t n)
383     {
384 root 1.6 return (n * (uint32_t)rndm16 ()) >> 16;
385 root 1.3 }
386    
387     However, for powers of two, you could use a normal mask, but that is only
388     worth it if, at compile time, you can detect this case. This is the case
389     when the passed number is a constant and also a power of two (C<n & (n -
390     1) == 0>):
391    
392     ecb_inline uint32_t
393     rndm (uint32_t n)
394     {
395     return is_constant (n) && !(n & (n - 1))
396     ? rndm16 () & (num - 1)
397 root 1.6 : (n * (uint32_t)rndm16 ()) >> 16;
398 root 1.3 }
399    
400 root 1.14 =item bool ecb_expect (expr, value)
401 root 1.1
402 root 1.7 Evaluates C<expr> and returns it. In addition, it tells the compiler that
403     the C<expr> evaluates to C<value> a lot, which can be used for static
404     branch optimisations.
405 root 1.1
406 root 1.27 Usually, you want to use the more intuitive C<ecb_expect_true> and
407     C<ecb_expect_false> functions instead.
408 root 1.1
409 root 1.27 =item bool ecb_expect_true (cond)
410 root 1.1
411 root 1.27 =item bool ecb_expect_false (cond)
412 root 1.1
413 root 1.7 These two functions expect a expression that is true or false and return
414     C<1> or C<0>, respectively, so when used in the condition of an C<if> or
415     other conditional statement, it will not change the program:
416    
417     /* these two do the same thing */
418     if (some_condition) ...;
419 root 1.27 if (ecb_expect_true (some_condition)) ...;
420 root 1.7
421 root 1.27 However, by using C<ecb_expect_true>, you tell the compiler that the
422     condition is likely to be true (and for C<ecb_expect_false>, that it is
423     unlikely to be true).
424 root 1.7
425 root 1.9 For example, when you check for a null pointer and expect this to be a
426 root 1.27 rare, exceptional, case, then use C<ecb_expect_false>:
427 root 1.7
428     void my_free (void *ptr)
429     {
430 root 1.27 if (ecb_expect_false (ptr == 0))
431 root 1.7 return;
432     }
433    
434     Consequent use of these functions to mark away exceptional cases or to
435     tell the compiler what the hot path through a function is can increase
436     performance considerably.
437    
438 root 1.27 You might know these functions under the name C<likely> and C<unlikely>
439     - while these are common aliases, we find that the expect name is easier
440     to understand when quickly skimming code. If you wish, you can use
441     C<ecb_likely> instead of C<ecb_expect_true> and C<ecb_unlikely> instead of
442     C<ecb_expect_false> - these are simply aliases.
443    
444 root 1.7 A very good example is in a function that reserves more space for some
445     memory block (for example, inside an implementation of a string stream) -
446 root 1.9 each time something is added, you have to check for a buffer overrun, but
447 root 1.7 you expect that most checks will turn out to be false:
448    
449     /* make sure we have "size" extra room in our buffer */
450     ecb_inline void
451     reserve (int size)
452     {
453 root 1.27 if (ecb_expect_false (current + size > end))
454 root 1.7 real_reserve_method (size); /* presumably noinline */
455     }
456    
457 root 1.14 =item bool ecb_assume (cond)
458 root 1.7
459     Try to tell the compiler that some condition is true, even if it's not
460     obvious.
461    
462     This can be used to teach the compiler about invariants or other
463     conditions that might improve code generation, but which are impossible to
464     deduce form the code itself.
465    
466 root 1.27 For example, the example reservation function from the C<ecb_expect_false>
467 root 1.7 description could be written thus (only C<ecb_assume> was added):
468    
469     ecb_inline void
470     reserve (int size)
471     {
472 root 1.27 if (ecb_expect_false (current + size > end))
473 root 1.7 real_reserve_method (size); /* presumably noinline */
474    
475     ecb_assume (current + size <= end);
476     }
477    
478     If you then call this function twice, like this:
479    
480     reserve (10);
481     reserve (1);
482    
483     Then the compiler I<might> be able to optimise out the second call
484     completely, as it knows that C<< current + 1 > end >> is false and the
485     call will never be executed.
486    
487     =item bool ecb_unreachable ()
488    
489     This function does nothing itself, except tell the compiler that it will
490 root 1.9 never be executed. Apart from suppressing a warning in some cases, this
491 root 1.7 function can be used to implement C<ecb_assume> or similar functions.
492    
493 root 1.14 =item bool ecb_prefetch (addr, rw, locality)
494 root 1.7
495     Tells the compiler to try to prefetch memory at the given C<addr>ess
496 root 1.10 for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
497 root 1.7 C<0> means that there will only be one access later, C<3> means that
498     the data will likely be accessed very often, and values in between mean
499     something... in between. The memory pointed to by the address does not
500     need to be accessible (it could be a null pointer for example), but C<rw>
501     and C<locality> must be compile-time constants.
502    
503     An obvious way to use this is to prefetch some data far away, in a big
504 root 1.9 array you loop over. This prefetches memory some 128 array elements later,
505 root 1.7 in the hope that it will be ready when the CPU arrives at that location.
506    
507     int sum = 0;
508    
509     for (i = 0; i < N; ++i)
510     {
511     sum += arr [i]
512     ecb_prefetch (arr + i + 128, 0, 0);
513     }
514    
515     It's hard to predict how far to prefetch, and most CPUs that can prefetch
516     are often good enough to predict this kind of behaviour themselves. It
517     gets more interesting with linked lists, especially when you do some fair
518     processing on each list element:
519    
520     for (node *n = start; n; n = n->next)
521     {
522     ecb_prefetch (n->next, 0, 0);
523     ... do medium amount of work with *n
524     }
525    
526     After processing the node, (part of) the next node might already be in
527     cache.
528 root 1.1
529 root 1.2 =back
530 root 1.1
531 root 1.36 =head2 BIT FIDDLING / BIT WIZARDRY
532 root 1.1
533 root 1.4 =over 4
534    
535 root 1.3 =item bool ecb_big_endian ()
536    
537     =item bool ecb_little_endian ()
538    
539 sf-exg 1.11 These two functions return true if the byte order is big endian
540     (most-significant byte first) or little endian (least-significant byte
541     first) respectively.
542    
543 root 1.24 On systems that are neither, their return values are unspecified.
544    
545 root 1.3 =item int ecb_ctz32 (uint32_t x)
546    
547 root 1.35 =item int ecb_ctz64 (uint64_t x)
548    
549 sf-exg 1.11 Returns the index of the least significant bit set in C<x> (or
550 root 1.24 equivalently the number of bits set to 0 before the least significant bit
551 root 1.35 set), starting from 0. If C<x> is 0 the result is undefined.
552    
553 root 1.36 For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
554    
555 root 1.35 For example:
556 sf-exg 1.11
557 root 1.15 ecb_ctz32 (3) = 0
558     ecb_ctz32 (6) = 1
559 sf-exg 1.11
560 root 1.41 =item bool ecb_is_pot32 (uint32_t x)
561    
562     =item bool ecb_is_pot64 (uint32_t x)
563    
564     Return true iff C<x> is a power of two or C<x == 0>.
565    
566     For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
567    
568 root 1.35 =item int ecb_ld32 (uint32_t x)
569    
570     =item int ecb_ld64 (uint64_t x)
571    
572     Returns the index of the most significant bit set in C<x>, or the number
573     of digits the number requires in binary (so that C<< 2**ld <= x <
574     2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
575     to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
576     example to see how many bits a certain number requires to be encoded.
577    
578     This function is similar to the "count leading zero bits" function, except
579     that that one returns how many zero bits are "in front" of the number (in
580     the given data type), while C<ecb_ld> returns how many bits the number
581     itself requires.
582    
583 root 1.36 For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
584    
585 root 1.3 =item int ecb_popcount32 (uint32_t x)
586    
587 root 1.35 =item int ecb_popcount64 (uint64_t x)
588    
589 root 1.36 Returns the number of bits set to 1 in C<x>.
590    
591     For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
592    
593     For example:
594 sf-exg 1.11
595 root 1.15 ecb_popcount32 (7) = 3
596     ecb_popcount32 (255) = 8
597 sf-exg 1.11
598 root 1.39 =item uint8_t ecb_bitrev8 (uint8_t x)
599    
600     =item uint16_t ecb_bitrev16 (uint16_t x)
601    
602     =item uint32_t ecb_bitrev32 (uint32_t x)
603    
604     Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
605     and so on.
606    
607     Example:
608    
609     ecb_bitrev8 (0xa7) = 0xea
610     ecb_bitrev32 (0xffcc4411) = 0x882233ff
611    
612 root 1.8 =item uint32_t ecb_bswap16 (uint32_t x)
613    
614 root 1.3 =item uint32_t ecb_bswap32 (uint32_t x)
615    
616 root 1.34 =item uint64_t ecb_bswap64 (uint64_t x)
617 sf-exg 1.13
618 root 1.34 These functions return the value of the 16-bit (32-bit, 64-bit) value
619     C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
620     C<ecb_bswap32>).
621    
622     =item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
623    
624     =item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
625 root 1.3
626     =item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
627    
628 root 1.34 =item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
629    
630     =item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
631    
632     =item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
633    
634     =item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
635    
636 root 1.33 =item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
637    
638 root 1.34 These two families of functions return the value of C<x> after rotating
639     all the bits by C<count> positions to the right (C<ecb_rotr>) or left
640     (C<ecb_rotl>).
641 sf-exg 1.11
642 root 1.20 Current GCC versions understand these functions and usually compile them
643 root 1.34 to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
644     x86).
645 root 1.20
646 root 1.3 =back
647 root 1.1
648 root 1.50 =head2 FLOATING POINT FIDDLING
649    
650     =over 4
651    
652     =item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
653    
654     =item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
655    
656     These functions each take an argument in the native C<float> or C<double>
657     type and return the IEEE 754 bit representation of it.
658    
659     The bit representation is just as IEEE 754 defines it, i.e. the sign bit
660     will be the most significant bit, followed by exponent and mantissa.
661    
662     This function should work even when the native floating point format isn't
663     IEEE compliant, of course at a speed and code size penalty, and of course
664     also within reasonable limits (it tries to convert NaNs, infinities and
665     denormals, but will likely convert negative zero to positive zero).
666    
667     On all modern platforms (where C<ECB_STDFP> is true), the compiler should
668     be able to optimise away this function completely.
669    
670     These functions can be helpful when serialising floats to the network - you
671     can serialise the return value like a normal uint32_t/uint64_t.
672    
673     Another use for these functions is to manipulate floating point values
674     directly.
675    
676     Silly example: toggle the sign bit of a float.
677    
678     /* On gcc-4.7 on amd64, */
679     /* this results in a single add instruction to toggle the bit, and 4 extra */
680     /* instructions to move the float value to an integer register and back. */
681    
682     x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
683    
684     =item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
685    
686     =item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM]
687    
688     The reverse operation of the previos function - takes the bit representation
689     of an IEEE binary32 or binary64 number and converts it to the native C<float>
690     or C<double> format.
691    
692     This function should work even when the native floating point format isn't
693     IEEE compliant, of course at a speed and code size penalty, and of course
694     also within reasonable limits (it tries to convert normals and denormals,
695     and might be lucky for infinities, and with extraordinary luck, also for
696     negative zero).
697    
698     On all modern platforms (where C<ECB_STDFP> is true), the compiler should
699     be able to optimise away this function completely.
700    
701     =back
702    
703 root 1.1 =head2 ARITHMETIC
704    
705 root 1.3 =over 4
706    
707 root 1.14 =item x = ecb_mod (m, n)
708 root 1.3
709 root 1.25 Returns C<m> modulo C<n>, which is the same as the positive remainder
710     of the division operation between C<m> and C<n>, using floored
711     division. Unlike the C remainder operator C<%>, this function ensures that
712     the return value is always positive and that the two numbers I<m> and
713     I<m' = m + i * n> result in the same value modulo I<n> - in other words,
714     C<ecb_mod> implements the mathematical modulo operation, which is missing
715     in the language.
716 root 1.14
717 sf-exg 1.23 C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
718 root 1.14 negatable, that is, both C<m> and C<-m> must be representable in its
719 root 1.30 type (this typically excludes the minimum signed integer value, the same
720 root 1.25 limitation as for C</> and C<%> in C).
721 sf-exg 1.11
722 root 1.24 Current GCC versions compile this into an efficient branchless sequence on
723 root 1.28 almost all CPUs.
724 root 1.24
725     For example, when you want to rotate forward through the members of an
726     array for increasing C<m> (which might be negative), then you should use
727     C<ecb_mod>, as the C<%> operator might give either negative results, or
728     change direction for negative values:
729    
730     for (m = -100; m <= 100; ++m)
731     int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
732    
733 sf-exg 1.37 =item x = ecb_div_rd (val, div)
734    
735     =item x = ecb_div_ru (val, div)
736    
737     Returns C<val> divided by C<div> rounded down or up, respectively.
738     C<val> and C<div> must have integer types and C<div> must be strictly
739 sf-exg 1.38 positive. Note that these functions are implemented with macros in C
740     and with function templates in C++.
741 sf-exg 1.37
742 root 1.3 =back
743 root 1.1
744     =head2 UTILITY
745    
746 root 1.3 =over 4
747    
748 sf-exg 1.23 =item element_count = ecb_array_length (name)
749 root 1.3
750 sf-exg 1.13 Returns the number of elements in the array C<name>. For example:
751    
752     int primes[] = { 2, 3, 5, 7, 11 };
753     int sum = 0;
754    
755     for (i = 0; i < ecb_array_length (primes); i++)
756     sum += primes [i];
757    
758 root 1.3 =back
759 root 1.1
760 root 1.43 =head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
761    
762     These symbols need to be defined before including F<ecb.h> the first time.
763    
764     =over 4
765    
766 root 1.51 =item ECB_NO_THREADS
767 root 1.43
768     If F<ecb.h> is never used from multiple threads, then this symbol can
769     be defined, in which case memory fences (and similar constructs) are
770     completely removed, leading to more efficient code and fewer dependencies.
771    
772     Setting this symbol to a true value implies C<ECB_NO_SMP>.
773    
774     =item ECB_NO_SMP
775    
776     The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
777     multiple threads, but never concurrently (e.g. if the system the program
778     runs on has only a single CPU with a single core, no hyperthreading and so
779     on), then this symbol can be defined, leading to more efficient code and
780     fewer dependencies.
781    
782 root 1.50 =item ECB_NO_LIBM
783    
784     When defined to C<1>, do not export any functions that might introduce
785     dependencies on the math library (usually called F<-lm>) - these are
786     marked with [-UECB_NO_LIBM].
787    
788 root 1.43 =back
789    
790 root 1.1