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

Comparing libecb/ecb.pod (file contents):
Revision 1.61 by sf-exg, Thu Feb 12 12:37:33 2015 UTC vs.
Revision 1.62 by root, Wed Feb 18 20:29:27 2015 UTC

… …
68platform (currently C<4> or C<8>) and can be used in preprocessor 68platform (currently C<4> or C<8>) and can be used in preprocessor
69expressions. 69expressions.
70 70
71For C<ptrdiff_t> and C<size_t> use C<stddef.h>. 71For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
72 72
73=head2 LANGUAGE/COMPILER VERSIONS 73=head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS
74 74
75All the following symbols expand to an expression that can be tested in 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 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). 77ensure it's either C<0> or C<1> if you need that).
78 78
… …
160The designers of the new X32 ABI for some inexplicable reason decided to 160The designers of the new X32 ABI for some inexplicable reason decided to
161make it look exactly like amd64, even though it's completely incompatible 161make it look exactly like amd64, even though it's completely incompatible
162to that ABI, breaking about every piece of software that assumed that 162to that ABI, breaking about every piece of software that assumed that
163C<__x86_64> stands for, well, the x86-64 ABI, making these macros 163C<__x86_64> stands for, well, the x86-64 ABI, making these macros
164necessary. 164necessary.
165
166=back
167
168=head2 MACRO TRICKERY
169
170=over 4
171
172=item ECB_CONCAT (a, b)
173
174Expands any macros in C<a> and C<b>, then concatenates the result to form
175a single token. This is mainly useful to form identifiers from components,
176e.g.:
177
178 #define S1 str
179 #define S2 cpy
180
181 ECB_CONCAT (S1, S2)(dst, src); // == strcpy (dst, src);
182
183=item ECB_STRINGIFY (arg)
184
185Expands any macros in C<arg> and returns the stringified version of
186it. This is mainly useful to get the contents of a macro in string form,
187e.g.:
188
189 #define SQL_LIMIT 100
190 sql_exec ("select * from table limit " ECB_STRINGIFY (SQL_LIMIT));
165 191
166=back 192=back
167 193
168=head2 ATTRIBUTES 194=head2 ATTRIBUTES
169 195
… …
198=item ecb_deprecated 224=item ecb_deprecated
199 225
200Similar to C<ecb_unused>, but marks a function, variable or type as 226Similar to C<ecb_unused>, but marks a function, variable or type as
201deprecated. This makes some compilers warn when the type is used. 227deprecated. This makes some compilers warn when the type is used.
202 228
229=item ecb_deprecated_message (message)
230
231Same as C<ecb_deprecated>, but if possible, supply a diagnostic that is
232used instead of a generic depreciation message when the object is being
233used.
234
203=item ecb_inline 235=item ecb_inline
204 236
205Expands either to C<static inline> or to just C<static>, if inline 237Expands either to C<static inline> or to just C<static>, if inline
206isn't supported. It should be used to declare functions that should be 238isn't supported. It should be used to declare functions that should be
207inlined, for code size or speed reasons. 239inlined, for code size or speed reasons.
… …
382 return is_constant (n) && !(n & (n - 1)) 414 return is_constant (n) && !(n & (n - 1))
383 ? rndm16 () & (num - 1) 415 ? rndm16 () & (num - 1)
384 : (n * (uint32_t)rndm16 ()) >> 16; 416 : (n * (uint32_t)rndm16 ()) >> 16;
385 } 417 }
386 418
387=item bool ecb_expect (expr, value) 419=item ecb_expect (expr, value)
388 420
389Evaluates C<expr> and returns it. In addition, it tells the compiler that 421Evaluates C<expr> and returns it. In addition, it tells the compiler that
390the C<expr> evaluates to C<value> a lot, which can be used for static 422the C<expr> evaluates to C<value> a lot, which can be used for static
391branch optimisations. 423branch optimisations.
392 424
… …
439 { 471 {
440 if (ecb_expect_false (current + size > end)) 472 if (ecb_expect_false (current + size > end))
441 real_reserve_method (size); /* presumably noinline */ 473 real_reserve_method (size); /* presumably noinline */
442 } 474 }
443 475
444=item bool ecb_assume (cond) 476=item ecb_assume (cond)
445 477
446Try to tell the compiler that some condition is true, even if it's not 478Try to tell the compiler that some condition is true, even if it's not
447obvious. 479obvious.
448 480
449This can be used to teach the compiler about invariants or other 481This can be used to teach the compiler about invariants or other
… …
469 501
470Then the compiler I<might> be able to optimise out the second call 502Then the compiler I<might> be able to optimise out the second call
471completely, as it knows that C<< current + 1 > end >> is false and the 503completely, as it knows that C<< current + 1 > end >> is false and the
472call will never be executed. 504call will never be executed.
473 505
474=item bool ecb_unreachable () 506=item ecb_unreachable ()
475 507
476This function does nothing itself, except tell the compiler that it will 508This function does nothing itself, except tell the compiler that it will
477never be executed. Apart from suppressing a warning in some cases, this 509never be executed. Apart from suppressing a warning in some cases, this
478function can be used to implement C<ecb_assume> or similar functions. 510function can be used to implement C<ecb_assume> or similar functions.
479 511
480=item bool ecb_prefetch (addr, rw, locality) 512=item ecb_prefetch (addr, rw, locality)
481 513
482Tells the compiler to try to prefetch memory at the given C<addr>ess 514Tells the compiler to try to prefetch memory at the given C<addr>ess
483for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of 515for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
484C<0> means that there will only be one access later, C<3> means that 516C<0> means that there will only be one access later, C<3> means that
485the data will likely be accessed very often, and values in between mean 517the data will likely be accessed very often, and values in between mean
… …
634 666
635=head2 FLOATING POINT FIDDLING 667=head2 FLOATING POINT FIDDLING
636 668
637=over 4 669=over 4
638 670
671=item ECB_INFINITY
672
673Evaluates to positive infinity if supported by the platform, otherwise to
674a truly huge number.
675
676=item ECB_NON
677
678Evaluates to a quiet NAN if supported by the platform, otherwise to
679C<ECB_INFINITY>.
680
681=item float ecb_ldexpf (float x, int exp)
682
683Same as C<ldexpf>, but always available.
684
639=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM] 685=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
640 686
641=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM] 687=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
642 688
643These functions each take an argument in the native C<float> or C<double> 689These functions each take an argument in the native C<float> or C<double>

Diff Legend

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