… | |
… | |
68 | platform (currently C<4> or C<8>) and can be used in preprocessor |
68 | platform (currently C<4> or C<8>) and can be used in preprocessor |
69 | expressions. |
69 | expressions. |
70 | |
70 | |
71 | For C<ptrdiff_t> and C<size_t> use C<stddef.h>. |
71 | For 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 | |
75 | All the following symbols expand to an expression that can be tested in |
75 | All the following symbols expand to an expression that can be tested in |
76 | preprocessor instructions as well as treated as a boolean (use C<!!> to |
76 | 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). |
77 | ensure it's either C<0> or C<1> if you need that). |
78 | |
78 | |
79 | =over 4 |
79 | =over 4 |
80 | |
80 | |
81 | =item ECB_C |
81 | =item ECB_C |
82 | |
82 | |
83 | True if the implementation defines the C<__STDC__> macro to a true value, |
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. |
84 | while not claiming to be C++. |
85 | |
85 | |
86 | =item ECB_C99 |
86 | =item ECB_C99 |
87 | |
87 | |
88 | True if the implementation claims to be compliant to C99 (ISO/IEC |
88 | True if the implementation claims to be compliant to C99 (ISO/IEC |
89 | 9899:1999) or any later version. |
89 | 9899:1999) or any later version, while not claiming to be C++. |
90 | |
90 | |
91 | Note that later versions (ECB_C11) remove core features again (for |
91 | Note that later versions (ECB_C11) remove core features again (for |
92 | example, variable length arrays). |
92 | example, variable length arrays). |
93 | |
93 | |
94 | =item ECB_C11 |
94 | =item ECB_C11 |
95 | |
95 | |
96 | True if the implementation claims to be compliant to C11 (ISO/IEC |
96 | True if the implementation claims to be compliant to C11 (ISO/IEC |
97 | 9899:2011) or any later version. |
97 | 9899:2011) or any later version, while not claiming to be C++. |
98 | |
98 | |
99 | =item ECB_CPP |
99 | =item ECB_CPP |
100 | |
100 | |
101 | True if the implementation defines the C<__cplusplus__> macro to a true |
101 | True if the implementation defines the C<__cplusplus__> macro to a true |
102 | value, which is typically true for C++ compilers. |
102 | value, which is typically true for C++ compilers. |
… | |
… | |
104 | =item ECB_CPP11 |
104 | =item ECB_CPP11 |
105 | |
105 | |
106 | True if the implementation claims to be compliant to ISO/IEC 14882:2011 |
106 | True if the implementation claims to be compliant to ISO/IEC 14882:2011 |
107 | (C++11) or any later version. |
107 | (C++11) or any later version. |
108 | |
108 | |
109 | =item ECB_GCC_VERSION(major,minor) |
109 | =item ECB_GCC_VERSION (major, minor) |
110 | |
110 | |
111 | Expands to a true value (suitable for testing in by the preprocessor) |
111 | Expands to a true value (suitable for testing in by the preprocessor) |
112 | if the compiler used is GNU C and the version is the given version, or |
112 | if the compiler used is GNU C and the version is the given version, or |
113 | higher. |
113 | higher. |
114 | |
114 | |
… | |
… | |
150 | |
150 | |
151 | This is true for basically all modern platforms, although F<ecb.h> might |
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 |
152 | not be able to deduce this correctly everywhere and might err on the safe |
153 | side. |
153 | side. |
154 | |
154 | |
|
|
155 | =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 | |
155 | =back |
166 | =back |
156 | |
167 | |
|
|
168 | =head2 MACRO TRICKERY |
|
|
169 | |
|
|
170 | =over 4 |
|
|
171 | |
|
|
172 | =item ECB_CONCAT (a, b) |
|
|
173 | |
|
|
174 | Expands any macros in C<a> and C<b>, then concatenates the result to form |
|
|
175 | a single token. This is mainly useful to form identifiers from components, |
|
|
176 | e.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 | |
|
|
185 | Expands any macros in C<arg> and returns the stringified version of |
|
|
186 | it. This is mainly useful to get the contents of a macro in string form, |
|
|
187 | e.g.: |
|
|
188 | |
|
|
189 | #define SQL_LIMIT 100 |
|
|
190 | sql_exec ("select * from table limit " ECB_STRINGIFY (SQL_LIMIT)); |
|
|
191 | |
|
|
192 | =back |
|
|
193 | |
157 | =head2 GCC ATTRIBUTES |
194 | =head2 ATTRIBUTES |
158 | |
195 | |
159 | A major part of libecb deals with GCC attributes. These are additional |
196 | A major part of libecb deals with additional attributes that can be |
160 | attributes that you can assign to functions, variables and sometimes even |
197 | assigned to functions, variables and sometimes even types - much like |
161 | types - much like C<const> or C<volatile> in C. |
198 | C<const> or C<volatile> in C. They are implemented using either GCC |
162 | |
199 | attributes or other compiler/language specific features. Attributes |
163 | While GCC allows declarations to show up in many surprising places, |
|
|
164 | but not in many expected places, the safest way is to put attribute |
|
|
165 | declarations before the whole declaration: |
200 | declarations must be put before the whole declaration: |
166 | |
201 | |
167 | ecb_const int mysqrt (int a); |
202 | ecb_const int mysqrt (int a); |
168 | ecb_unused int i; |
203 | ecb_unused int i; |
169 | |
204 | |
170 | For variables, it is often nicer to put the attribute after the name, and |
|
|
171 | avoid multiple declarations using commas: |
|
|
172 | |
|
|
173 | int i ecb_unused; |
|
|
174 | |
|
|
175 | =over 4 |
205 | =over 4 |
176 | |
|
|
177 | =item ecb_attribute ((attrs...)) |
|
|
178 | |
|
|
179 | A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to |
|
|
180 | nothing on other compilers, so the effect is that only GCC sees these. |
|
|
181 | |
|
|
182 | Example: use the C<deprecated> attribute on a function. |
|
|
183 | |
|
|
184 | ecb_attribute((__deprecated__)) void |
|
|
185 | do_not_use_me_anymore (void); |
|
|
186 | |
206 | |
187 | =item ecb_unused |
207 | =item ecb_unused |
188 | |
208 | |
189 | Marks a function or a variable as "unused", which simply suppresses a |
209 | Marks a function or a variable as "unused", which simply suppresses a |
190 | warning by GCC when it detects it as unused. This is useful when you e.g. |
210 | warning by GCC when it detects it as unused. This is useful when you e.g. |
191 | declare a variable but do not always use it: |
211 | declare a variable but do not always use it: |
192 | |
212 | |
193 | { |
213 | { |
194 | int var ecb_unused; |
214 | ecb_unused int var; |
195 | |
215 | |
196 | #ifdef SOMECONDITION |
216 | #ifdef SOMECONDITION |
197 | var = ...; |
217 | var = ...; |
198 | return var; |
218 | return var; |
199 | #else |
219 | #else |
200 | return 0; |
220 | return 0; |
201 | #endif |
221 | #endif |
202 | } |
222 | } |
203 | |
223 | |
|
|
224 | =item ecb_deprecated |
|
|
225 | |
|
|
226 | Similar to C<ecb_unused>, but marks a function, variable or type as |
|
|
227 | deprecated. This makes some compilers warn when the type is used. |
|
|
228 | |
|
|
229 | =item ecb_deprecated_message (message) |
|
|
230 | |
|
|
231 | Same as C<ecb_deprecated>, but if possible, supply a diagnostic that is |
|
|
232 | used instead of a generic depreciation message when the object is being |
|
|
233 | used. |
|
|
234 | |
204 | =item ecb_inline |
235 | =item ecb_inline |
205 | |
236 | |
206 | This is not actually an attribute, but you use it like one. It expands |
|
|
207 | either to C<static inline> or to just C<static>, if inline isn't |
237 | Expands either to C<static inline> or to just C<static>, if inline |
208 | supported. It should be used to declare functions that should be inlined, |
238 | isn't supported. It should be used to declare functions that should be |
209 | for code size or speed reasons. |
239 | inlined, for code size or speed reasons. |
210 | |
240 | |
211 | Example: inline this function, it surely will reduce codesize. |
241 | Example: inline this function, it surely will reduce codesize. |
212 | |
242 | |
213 | ecb_inline int |
243 | ecb_inline int |
214 | negmul (int a, int b) |
244 | negmul (int a, int b) |
… | |
… | |
236 | } |
266 | } |
237 | |
267 | |
238 | In this case, the compiler would probably be smart enough to deduce it on |
268 | In this case, the compiler would probably be smart enough to deduce it on |
239 | its own, so this is mainly useful for declarations. |
269 | its own, so this is mainly useful for declarations. |
240 | |
270 | |
|
|
271 | =item ecb_restrict |
|
|
272 | |
|
|
273 | Expands to the C<restrict> keyword or equivalent on compilers that support |
|
|
274 | them, and to nothing on others. Must be specified on a pointer type or |
|
|
275 | an array index to indicate that the memory doesn't alias with any other |
|
|
276 | restricted pointer in the same scope. |
|
|
277 | |
|
|
278 | Example: multiply a vector, and allow the compiler to parallelise the |
|
|
279 | loop, because it knows it doesn't overwrite input values. |
|
|
280 | |
|
|
281 | void |
|
|
282 | multiply (ecb_restrict float *src, |
|
|
283 | ecb_restrict float *dst, |
|
|
284 | int len, float factor) |
|
|
285 | { |
|
|
286 | int i; |
|
|
287 | |
|
|
288 | for (i = 0; i < len; ++i) |
|
|
289 | dst [i] = src [i] * factor; |
|
|
290 | } |
|
|
291 | |
241 | =item ecb_const |
292 | =item ecb_const |
242 | |
293 | |
243 | Declares that the function only depends on the values of its arguments, |
294 | Declares that the function only depends on the values of its arguments, |
244 | much like a mathematical function. It specifically does not read or write |
295 | much like a mathematical function. It specifically does not read or write |
245 | any memory any arguments might point to, global variables, or call any |
296 | any memory any arguments might point to, global variables, or call any |
… | |
… | |
305 | functions only called in exceptional or rare cases. |
356 | functions only called in exceptional or rare cases. |
306 | |
357 | |
307 | =item ecb_artificial |
358 | =item ecb_artificial |
308 | |
359 | |
309 | Declares the function as "artificial", in this case meaning that this |
360 | Declares the function as "artificial", in this case meaning that this |
310 | function is not really mean to be a function, but more like an accessor |
361 | function is not really meant to be a function, but more like an accessor |
311 | - many methods in C++ classes are mere accessor functions, and having a |
362 | - many methods in C++ classes are mere accessor functions, and having a |
312 | crash reported in such a method, or single-stepping through them, is not |
363 | crash reported in such a method, or single-stepping through them, is not |
313 | usually so helpful, especially when it's inlined to just a few instructions. |
364 | usually so helpful, especially when it's inlined to just a few instructions. |
314 | |
365 | |
315 | Marking them as artificial will instruct the debugger about just this, |
366 | Marking them as artificial will instruct the debugger about just this, |
… | |
… | |
335 | |
386 | |
336 | =head2 OPTIMISATION HINTS |
387 | =head2 OPTIMISATION HINTS |
337 | |
388 | |
338 | =over 4 |
389 | =over 4 |
339 | |
390 | |
340 | =item bool ecb_is_constant(expr) |
391 | =item bool ecb_is_constant (expr) |
341 | |
392 | |
342 | Returns true iff the expression can be deduced to be a compile-time |
393 | Returns true iff the expression can be deduced to be a compile-time |
343 | constant, and false otherwise. |
394 | constant, and false otherwise. |
344 | |
395 | |
345 | For example, when you have a C<rndm16> function that returns a 16 bit |
396 | For example, when you have a C<rndm16> function that returns a 16 bit |
… | |
… | |
363 | return is_constant (n) && !(n & (n - 1)) |
414 | return is_constant (n) && !(n & (n - 1)) |
364 | ? rndm16 () & (num - 1) |
415 | ? rndm16 () & (num - 1) |
365 | : (n * (uint32_t)rndm16 ()) >> 16; |
416 | : (n * (uint32_t)rndm16 ()) >> 16; |
366 | } |
417 | } |
367 | |
418 | |
368 | =item bool ecb_expect (expr, value) |
419 | =item ecb_expect (expr, value) |
369 | |
420 | |
370 | Evaluates C<expr> and returns it. In addition, it tells the compiler that |
421 | Evaluates C<expr> and returns it. In addition, it tells the compiler that |
371 | the C<expr> evaluates to C<value> a lot, which can be used for static |
422 | the C<expr> evaluates to C<value> a lot, which can be used for static |
372 | branch optimisations. |
423 | branch optimisations. |
373 | |
424 | |
… | |
… | |
420 | { |
471 | { |
421 | if (ecb_expect_false (current + size > end)) |
472 | if (ecb_expect_false (current + size > end)) |
422 | real_reserve_method (size); /* presumably noinline */ |
473 | real_reserve_method (size); /* presumably noinline */ |
423 | } |
474 | } |
424 | |
475 | |
425 | =item bool ecb_assume (cond) |
476 | =item ecb_assume (cond) |
426 | |
477 | |
427 | Try to tell the compiler that some condition is true, even if it's not |
478 | Try to tell the compiler that some condition is true, even if it's not |
428 | obvious. |
479 | obvious. |
429 | |
480 | |
430 | This can be used to teach the compiler about invariants or other |
481 | This can be used to teach the compiler about invariants or other |
… | |
… | |
450 | |
501 | |
451 | Then the compiler I<might> be able to optimise out the second call |
502 | Then the compiler I<might> be able to optimise out the second call |
452 | completely, as it knows that C<< current + 1 > end >> is false and the |
503 | completely, as it knows that C<< current + 1 > end >> is false and the |
453 | call will never be executed. |
504 | call will never be executed. |
454 | |
505 | |
455 | =item bool ecb_unreachable () |
506 | =item ecb_unreachable () |
456 | |
507 | |
457 | This function does nothing itself, except tell the compiler that it will |
508 | This function does nothing itself, except tell the compiler that it will |
458 | never be executed. Apart from suppressing a warning in some cases, this |
509 | never be executed. Apart from suppressing a warning in some cases, this |
459 | function can be used to implement C<ecb_assume> or similar functions. |
510 | function can be used to implement C<ecb_assume> or similar functions. |
460 | |
511 | |
461 | =item bool ecb_prefetch (addr, rw, locality) |
512 | =item ecb_prefetch (addr, rw, locality) |
462 | |
513 | |
463 | Tells the compiler to try to prefetch memory at the given C<addr>ess |
514 | Tells the compiler to try to prefetch memory at the given C<addr>ess |
464 | for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of |
515 | for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of |
465 | C<0> means that there will only be one access later, C<3> means that |
516 | C<0> means that there will only be one access later, C<3> means that |
466 | the data will likely be accessed very often, and values in between mean |
517 | the data will likely be accessed very often, and values in between mean |
… | |
… | |
615 | |
666 | |
616 | =head2 FLOATING POINT FIDDLING |
667 | =head2 FLOATING POINT FIDDLING |
617 | |
668 | |
618 | =over 4 |
669 | =over 4 |
619 | |
670 | |
|
|
671 | =item ECB_INFINITY |
|
|
672 | |
|
|
673 | Evaluates to positive infinity if supported by the platform, otherwise to |
|
|
674 | a truly huge number. |
|
|
675 | |
|
|
676 | =item ECB_NON |
|
|
677 | |
|
|
678 | Evaluates to a quiet NAN if supported by the platform, otherwise to |
|
|
679 | C<ECB_INFINITY>. |
|
|
680 | |
|
|
681 | =item float ecb_ldexpf (float x, int exp) |
|
|
682 | |
|
|
683 | Same as C<ldexpf>, but always available. |
|
|
684 | |
620 | =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] |
621 | |
686 | |
622 | =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] |
623 | |
688 | |
624 | These functions each take an argument in the native C<float> or C<double> |
689 | These functions each take an argument in the native C<float> or C<double> |
… | |
… | |
647 | /* this results in a single add instruction to toggle the bit, and 4 extra */ |
712 | /* this results in a single add instruction to toggle the bit, and 4 extra */ |
648 | /* instructions to move the float value to an integer register and back. */ |
713 | /* instructions to move the float value to an integer register and back. */ |
649 | |
714 | |
650 | x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U) |
715 | x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U) |
651 | |
716 | |
|
|
717 | =item float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM] |
|
|
718 | |
652 | =item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM] |
719 | =item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM] |
653 | |
720 | |
654 | =item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM] |
721 | =item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM] |
655 | |
722 | |
656 | The reverse operation of the previos function - takes the bit representation |
723 | The reverse operation of the previous function - takes the bit |
657 | of an IEEE binary32 or binary64 number and converts it to the native C<float> |
724 | representation of an IEEE binary16, binary32 or binary64 number and |
658 | or C<double> format. |
725 | converts it to the native C<float> or C<double> format. |
659 | |
726 | |
660 | This function should work even when the native floating point format isn't |
727 | This function should work even when the native floating point format isn't |
661 | IEEE compliant, of course at a speed and code size penalty, and of course |
728 | IEEE compliant, of course at a speed and code size penalty, and of course |
662 | also within reasonable limits (it tries to convert normals and denormals, |
729 | also within reasonable limits (it tries to convert normals and denormals, |
663 | and might be lucky for infinities, and with extraordinary luck, also for |
730 | and might be lucky for infinities, and with extraordinary luck, also for |