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.59 by sf-exg, Mon Jan 26 12:04:56 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
… …
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 165
166=back 166=back
167 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));
191
192=back
193
168=head2 GCC ATTRIBUTES 194=head2 ATTRIBUTES
169 195
170A major part of libecb deals with GCC attributes. These are additional 196A major part of libecb deals with additional attributes that can be
171attributes that you can assign to functions, variables and sometimes even 197assigned to functions, variables and sometimes even types - much like
172types - much like C<const> or C<volatile> in C. 198C<const> or C<volatile> in C. They are implemented using either GCC
173 199attributes or other compiler/language specific features. Attributes
174While GCC allows declarations to show up in many surprising places,
175but not in many expected places, the safest way is to put attribute
176declarations before the whole declaration: 200declarations must be put before the whole declaration:
177 201
178 ecb_const int mysqrt (int a); 202 ecb_const int mysqrt (int a);
179 ecb_unused int i; 203 ecb_unused int i;
180 204
181For variables, it is often nicer to put the attribute after the name, and
182avoid multiple declarations using commas:
183
184 int i ecb_unused;
185
186=over 4 205=over 4
187
188=item ecb_attribute ((attrs...))
189
190A simple wrapper that expands to C<__attribute__((attrs))> on GCC 3.1+ and
191Clang 2.8+, and to nothing on other compilers, so the effect is that only
192GCC and Clang see these.
193
194Example: use the C<deprecated> attribute on a function.
195
196 ecb_attribute((__deprecated__)) void
197 do_not_use_me_anymore (void);
198 206
199=item ecb_unused 207=item ecb_unused
200 208
201Marks a function or a variable as "unused", which simply suppresses a 209Marks a function or a variable as "unused", which simply suppresses a
202warning by GCC when it detects it as unused. This is useful when you e.g. 210warning by GCC when it detects it as unused. This is useful when you e.g.
203declare a variable but do not always use it: 211declare a variable but do not always use it:
204 212
205 { 213 {
206 int var ecb_unused; 214 ecb_unused int var;
207 215
208 #ifdef SOMECONDITION 216 #ifdef SOMECONDITION
209 var = ...; 217 var = ...;
210 return var; 218 return var;
211 #else 219 #else
… …
216=item ecb_deprecated 224=item ecb_deprecated
217 225
218Similar 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
219deprecated. This makes some compilers warn when the type is used. 227deprecated. This makes some compilers warn when the type is used.
220 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
221=item ecb_inline 235=item ecb_inline
222 236
223This is not actually an attribute, but you use it like one. It expands
224either to C<static inline> or to just C<static>, if inline isn't 237Expands either to C<static inline> or to just C<static>, if inline
225supported. It should be used to declare functions that should be inlined, 238isn't supported. It should be used to declare functions that should be
226for code size or speed reasons. 239inlined, for code size or speed reasons.
227 240
228Example: inline this function, it surely will reduce codesize. 241Example: inline this function, it surely will reduce codesize.
229 242
230 ecb_inline int 243 ecb_inline int
231 negmul (int a, int b) 244 negmul (int a, int b)
… …
264 277
265Example: multiply a vector, and allow the compiler to parallelise the 278Example: multiply a vector, and allow the compiler to parallelise the
266loop, because it knows it doesn't overwrite input values. 279loop, because it knows it doesn't overwrite input values.
267 280
268 void 281 void
269 multiply (float *ecb_restrict src, 282 multiply (ecb_restrict float *src,
270 float *ecb_restrict dst, 283 ecb_restrict float *dst,
271 int len, float factor) 284 int len, float factor)
272 { 285 {
273 int i; 286 int i;
274 287
275 for (i = 0; i < len; ++i) 288 for (i = 0; i < len; ++i)
… …
401 return is_constant (n) && !(n & (n - 1)) 414 return is_constant (n) && !(n & (n - 1))
402 ? rndm16 () & (num - 1) 415 ? rndm16 () & (num - 1)
403 : (n * (uint32_t)rndm16 ()) >> 16; 416 : (n * (uint32_t)rndm16 ()) >> 16;
404 } 417 }
405 418
406=item bool ecb_expect (expr, value) 419=item ecb_expect (expr, value)
407 420
408Evaluates 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
409the 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
410branch optimisations. 423branch optimisations.
411 424
… …
458 { 471 {
459 if (ecb_expect_false (current + size > end)) 472 if (ecb_expect_false (current + size > end))
460 real_reserve_method (size); /* presumably noinline */ 473 real_reserve_method (size); /* presumably noinline */
461 } 474 }
462 475
463=item bool ecb_assume (cond) 476=item ecb_assume (cond)
464 477
465Try 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
466obvious. 479obvious.
467 480
468This can be used to teach the compiler about invariants or other 481This can be used to teach the compiler about invariants or other
… …
488 501
489Then 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
490completely, 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
491call will never be executed. 504call will never be executed.
492 505
493=item bool ecb_unreachable () 506=item ecb_unreachable ()
494 507
495This function does nothing itself, except tell the compiler that it will 508This function does nothing itself, except tell the compiler that it will
496never be executed. Apart from suppressing a warning in some cases, this 509never be executed. Apart from suppressing a warning in some cases, this
497function can be used to implement C<ecb_assume> or similar functions. 510function can be used to implement C<ecb_assume> or similar functions.
498 511
499=item bool ecb_prefetch (addr, rw, locality) 512=item ecb_prefetch (addr, rw, locality)
500 513
501Tells 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
502for 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
503C<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
504the 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
… …
653 666
654=head2 FLOATING POINT FIDDLING 667=head2 FLOATING POINT FIDDLING
655 668
656=over 4 669=over 4
657 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
658=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]
659 686
660=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]
661 688
662These 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