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.41 by root, Mon May 28 08:40:25 2012 UTC vs.
Revision 1.53 by root, Wed Dec 5 16:31:27 2012 UTC

… …
58 58
59=head2 TYPES / TYPE SUPPORT 59=head2 TYPES / TYPE SUPPORT
60 60
61ecb.h makes sure that the following types are defined (in the expected way): 61ecb.h makes sure that the following types are defined (in the expected way):
62 62
63 int8_t uint8_t int16_t uint16_t 63 int8_t uint8_t int16_t uint16_t
64 int32_t uint32_t int64_t uint64_t 64 int32_t uint32_t int64_t uint64_t
65 intptr_t uintptr_t 65 intptr_t uintptr_t
66 66
67The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this 67The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
68platform (currently C<4> or C<8>). 68platform (currently C<4> or C<8>) and can be used in preprocessor
69expressions.
70
71For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
72
73=head2 LANGUAGE/COMPILER VERSIONS
74
75All the following symbols expand to an expression that can be tested in
76preprocessor instructions as well as treated as a boolean (use C<!!> to
77ensure it's either C<0> or C<1> if you need that).
78
79=over 4
80
81=item ECB_C
82
83True if the implementation defines the C<__STDC__> macro to a true value,
84which is typically true for both C and C++ compilers.
85
86=item ECB_C99
87
88True if the implementation claims to be compliant to C99 (ISO/IEC
899899:1999) or any later version.
90
91Note that later versions (ECB_C11) remove core features again (for
92example, variable length arrays).
93
94=item ECB_C11
95
96True if the implementation claims to be compliant to C11 (ISO/IEC
979899:2011) or any later version.
98
99=item ECB_CPP
100
101True if the implementation defines the C<__cplusplus__> macro to a true
102value, which is typically true for C++ compilers.
103
104=item ECB_CPP11
105
106True if the implementation claims to be compliant to ISO/IEC 14882:2011
107(C++11) or any later version.
108
109=item ECB_GCC_VERSION(major,minor)
110
111Expands to a true value (suitable for testing in by the preprocessor)
112if the compiler used is GNU C and the version is the given version, or
113higher.
114
115This macro tries to return false on compilers that claim to be GCC
116compatible but aren't.
117
118=item ECB_EXTERN_C
119
120Expands to C<extern "C"> in C++, and a simple C<extern> in C.
121
122This 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
128These two macros can be used to wrap multiple C<extern "C"> definitions -
129they expand to nothing in C.
130
131They 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
142If this evaluates to a true value (suitable for testing in by the
143preprocessor), then C<float> and C<double> use IEEE 754 single/binary32
144and double/binary64 representations internally I<and> the endianness of
145both types match the endianness of C<uint32_t> and C<uint64_t>.
146
147This means you can just copy the bits of a C<float> (or C<double>) to an
148C<uint32_t> (or C<uint64_t>) and get the raw IEEE 754 bit representation
149without having to think about format or endianness.
150
151This is true for basically all modern platforms, although F<ecb.h> might
152not be able to deduce this correctly everywhere and might err on the safe
153side.
154
155=back
69 156
70=head2 GCC ATTRIBUTES 157=head2 GCC ATTRIBUTES
71 158
72A major part of libecb deals with GCC attributes. These are additional 159A major part of libecb deals with GCC attributes. These are additional
73attributes that you can assign to functions, variables and sometimes even 160attributes that you can assign to functions, variables and sometimes even
… …
149 } 236 }
150 237
151In this case, the compiler would probably be smart enough to deduce it on 238In this case, the compiler would probably be smart enough to deduce it on
152its own, so this is mainly useful for declarations. 239its own, so this is mainly useful for declarations.
153 240
241=item ecb_restrict
242
243Expands to the C<restrict> keyword or equivalent on compilers that support
244them, and to nothing on others. Must be specified on a pointer type or
245an array index to indicate that the memory doesn't alias with any other
246restricted pointer in the same scope.
247
248Example: multiply a vector, and allow the compiler to parallelise the
249loop, because it knows it doesn't overwrite input values.
250
251 void
252 multiply (float *ecb_restrict src,
253 float *ecb_restrict dst,
254 int len, float factor)
255 {
256 int i;
257
258 for (i = 0; i < len; ++i)
259 dst [i] = src [i] * factor;
260 }
261
154=item ecb_const 262=item ecb_const
155 263
156Declares that the function only depends on the values of its arguments, 264Declares that the function only depends on the values of its arguments,
157much like a mathematical function. It specifically does not read or write 265much like a mathematical function. It specifically does not read or write
158any memory any arguments might point to, global variables, or call any 266any memory any arguments might point to, global variables, or call any
… …
218functions only called in exceptional or rare cases. 326functions only called in exceptional or rare cases.
219 327
220=item ecb_artificial 328=item ecb_artificial
221 329
222Declares the function as "artificial", in this case meaning that this 330Declares the function as "artificial", in this case meaning that this
223function is not really mean to be a function, but more like an accessor 331function is not really meant to be a function, but more like an accessor
224- many methods in C++ classes are mere accessor functions, and having a 332- 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 333crash 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. 334usually so helpful, especially when it's inlined to just a few instructions.
227 335
228Marking them as artificial will instruct the debugger about just this, 336Marking them as artificial will instruct the debugger about just this,
… …
524to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on 632to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
525x86). 633x86).
526 634
527=back 635=back
528 636
637=head2 FLOATING POINT FIDDLING
638
639=over 4
640
641=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
642
643=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
644
645These functions each take an argument in the native C<float> or C<double>
646type and return the IEEE 754 bit representation of it.
647
648The bit representation is just as IEEE 754 defines it, i.e. the sign bit
649will be the most significant bit, followed by exponent and mantissa.
650
651This function should work even when the native floating point format isn't
652IEEE compliant, of course at a speed and code size penalty, and of course
653also within reasonable limits (it tries to convert NaNs, infinities and
654denormals, but will likely convert negative zero to positive zero).
655
656On all modern platforms (where C<ECB_STDFP> is true), the compiler should
657be able to optimise away this function completely.
658
659These functions can be helpful when serialising floats to the network - you
660can serialise the return value like a normal uint32_t/uint64_t.
661
662Another use for these functions is to manipulate floating point values
663directly.
664
665Silly example: toggle the sign bit of a float.
666
667 /* On gcc-4.7 on amd64, */
668 /* this results in a single add instruction to toggle the bit, and 4 extra */
669 /* instructions to move the float value to an integer register and back. */
670
671 x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
672
673=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
674
675=item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM]
676
677The reverse operation of the previos function - takes the bit representation
678of an IEEE binary32 or binary64 number and converts it to the native C<float>
679or C<double> format.
680
681This function should work even when the native floating point format isn't
682IEEE compliant, of course at a speed and code size penalty, and of course
683also within reasonable limits (it tries to convert normals and denormals,
684and might be lucky for infinities, and with extraordinary luck, also for
685negative zero).
686
687On all modern platforms (where C<ECB_STDFP> is true), the compiler should
688be able to optimise away this function completely.
689
690=back
691
529=head2 ARITHMETIC 692=head2 ARITHMETIC
530 693
531=over 4 694=over 4
532 695
533=item x = ecb_mod (m, n) 696=item x = ecb_mod (m, n)
… …
581 for (i = 0; i < ecb_array_length (primes); i++) 744 for (i = 0; i < ecb_array_length (primes); i++)
582 sum += primes [i]; 745 sum += primes [i];
583 746
584=back 747=back
585 748
749=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
586 750
751These symbols need to be defined before including F<ecb.h> the first time.
752
753=over 4
754
755=item ECB_NO_THREADS
756
757If F<ecb.h> is never used from multiple threads, then this symbol can
758be defined, in which case memory fences (and similar constructs) are
759completely removed, leading to more efficient code and fewer dependencies.
760
761Setting this symbol to a true value implies C<ECB_NO_SMP>.
762
763=item ECB_NO_SMP
764
765The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
766multiple threads, but never concurrently (e.g. if the system the program
767runs on has only a single CPU with a single core, no hyperthreading and so
768on), then this symbol can be defined, leading to more efficient code and
769fewer dependencies.
770
771=item ECB_NO_LIBM
772
773When defined to C<1>, do not export any functions that might introduce
774dependencies on the math library (usually called F<-lm>) - these are
775marked with [-UECB_NO_LIBM].
776
777=back
778
779

Diff Legend

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