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