ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
Revision: 1.59
Committed: Mon Jan 26 12:04:56 2015 UTC (9 years, 4 months ago) by sf-exg
Branch: MAIN
Changes since 1.58: +1 -1 lines
Log Message:
Fix typo.

File Contents

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