ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
Revision: 1.49
Committed: Thu Jun 28 14:50:01 2012 UTC (11 years, 11 months ago) by root
Branch: MAIN
Changes since 1.48: +3 -1 lines
Log Message:
*** empty log message ***

File Contents

# User Rev Content
1 root 1.14 =head1 LIBECB - e-C-Builtins
2 root 1.3
3 root 1.14 =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 sf-exg 1.16 It's part of the e-suite of libraries, other members of which include
9 root 1.14 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 sf-exg 1.16 it provides a number of other lowlevel C utilities, such as endianness
18 root 1.14 detection, byte swapping or bit rotations.
19    
20 root 1.24 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 root 1.17
24 root 1.14 More might come.
25 root 1.3
26     =head2 ABOUT THE HEADER
27    
28 root 1.14 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 sf-exg 1.16 There are currently no object files to link to - future versions might
37 root 1.14 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 root 1.1
59 root 1.40 =head2 TYPES / TYPE SUPPORT
60    
61     ecb.h makes sure that the following types are defined (in the expected way):
62    
63 root 1.42 int8_t uint8_t int16_t uint16_t
64     int32_t uint32_t int64_t uint64_t
65 root 1.49 intptr_t uintptr_t
66 root 1.40
67     The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
68 root 1.45 platform (currently C<4> or C<8>) and can be used in preprocessor
69     expressions.
70 root 1.40
71 root 1.49 For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
72    
73 root 1.43 =head2 LANGUAGE/COMPILER VERSIONS
74    
75 sf-exg 1.46 All the following symbols expand to an expression that can be tested in
76 root 1.44 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 root 1.43 =over 4
80    
81 root 1.44 =item ECB_C
82    
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.
85    
86 root 1.43 =item ECB_C99
87    
88 root 1.47 True if the implementation claims to be compliant to C99 (ISO/IEC
89     9899:1999) or any later version.
90    
91     Note that later versions (ECB_C11) remove core features again (for
92     example, variable length arrays).
93 root 1.43
94     =item ECB_C11
95    
96 root 1.47 True if the implementation claims to be compliant to C11 (ISO/IEC
97     9899:2011) or any later version.
98 root 1.44
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 sf-exg 1.46 (C++11) or any later version.
108 root 1.43
109     =item ECB_GCC_VERSION(major,minor)
110    
111     Expands to a true value (suitable for testing in by the preprocessor)
112 sf-exg 1.46 if the compiler used is GNU C and the version is the given version, or
113 root 1.43 higher.
114    
115     This macro tries to return false on compilers that claim to be GCC
116     compatible but aren't.
117    
118     =back
119    
120 root 1.1 =head2 GCC ATTRIBUTES
121    
122 root 1.20 A major part of libecb deals with GCC attributes. These are additional
123 sf-exg 1.26 attributes that you can assign to functions, variables and sometimes even
124 root 1.20 types - much like C<const> or C<volatile> in C.
125    
126     While GCC allows declarations to show up in many surprising places,
127 sf-exg 1.26 but not in many expected places, the safest way is to put attribute
128 root 1.20 declarations before the whole declaration:
129    
130     ecb_const int mysqrt (int a);
131     ecb_unused int i;
132    
133     For variables, it is often nicer to put the attribute after the name, and
134     avoid multiple declarations using commas:
135    
136     int i ecb_unused;
137 root 1.3
138 root 1.1 =over 4
139    
140 root 1.2 =item ecb_attribute ((attrs...))
141 root 1.1
142 root 1.15 A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
143     nothing on other compilers, so the effect is that only GCC sees these.
144    
145     Example: use the C<deprecated> attribute on a function.
146    
147     ecb_attribute((__deprecated__)) void
148     do_not_use_me_anymore (void);
149 root 1.2
150 root 1.3 =item ecb_unused
151    
152     Marks a function or a variable as "unused", which simply suppresses a
153     warning by GCC when it detects it as unused. This is useful when you e.g.
154     declare a variable but do not always use it:
155    
156 root 1.15 {
157     int var ecb_unused;
158 root 1.3
159 root 1.15 #ifdef SOMECONDITION
160     var = ...;
161     return var;
162     #else
163     return 0;
164     #endif
165     }
166 root 1.3
167 root 1.31 =item ecb_inline
168 root 1.29
169     This is not actually an attribute, but you use it like one. It expands
170     either to C<static inline> or to just C<static>, if inline isn't
171     supported. It should be used to declare functions that should be inlined,
172     for code size or speed reasons.
173    
174     Example: inline this function, it surely will reduce codesize.
175    
176 root 1.31 ecb_inline int
177 root 1.29 negmul (int a, int b)
178     {
179     return - (a * b);
180     }
181    
182 root 1.2 =item ecb_noinline
183    
184 root 1.9 Prevent a function from being inlined - it might be optimised away, but
185 root 1.3 not inlined into other functions. This is useful if you know your function
186     is rarely called and large enough for inlining not to be helpful.
187    
188 root 1.2 =item ecb_noreturn
189    
190 root 1.17 Marks a function as "not returning, ever". Some typical functions that
191     don't return are C<exit> or C<abort> (which really works hard to not
192     return), and now you can make your own:
193    
194     ecb_noreturn void
195     my_abort (const char *errline)
196     {
197     puts (errline);
198     abort ();
199     }
200    
201 sf-exg 1.19 In this case, the compiler would probably be smart enough to deduce it on
202     its own, so this is mainly useful for declarations.
203 root 1.17
204 root 1.2 =item ecb_const
205    
206 sf-exg 1.19 Declares that the function only depends on the values of its arguments,
207 root 1.17 much like a mathematical function. It specifically does not read or write
208     any memory any arguments might point to, global variables, or call any
209     non-const functions. It also must not have any side effects.
210    
211     Such a function can be optimised much more aggressively by the compiler -
212     for example, multiple calls with the same arguments can be optimised into
213     a single call, which wouldn't be possible if the compiler would have to
214     expect any side effects.
215    
216     It is best suited for functions in the sense of mathematical functions,
217 sf-exg 1.19 such as a function returning the square root of its input argument.
218 root 1.17
219     Not suited would be a function that calculates the hash of some memory
220     area you pass in, prints some messages or looks at a global variable to
221     decide on rounding.
222    
223     See C<ecb_pure> for a slightly less restrictive class of functions.
224    
225 root 1.2 =item ecb_pure
226    
227 root 1.17 Similar to C<ecb_const>, declares a function that has no side
228     effects. Unlike C<ecb_const>, the function is allowed to examine global
229     variables and any other memory areas (such as the ones passed to it via
230     pointers).
231    
232     While these functions cannot be optimised as aggressively as C<ecb_const>
233     functions, they can still be optimised away in many occasions, and the
234     compiler has more freedom in moving calls to them around.
235    
236     Typical examples for such functions would be C<strlen> or C<memcmp>. A
237     function that calculates the MD5 sum of some input and updates some MD5
238     state passed as argument would I<NOT> be pure, however, as it would modify
239     some memory area that is not the return value.
240    
241 root 1.2 =item ecb_hot
242    
243 root 1.17 This declares a function as "hot" with regards to the cache - the function
244     is used so often, that it is very beneficial to keep it in the cache if
245     possible.
246    
247     The compiler reacts by trying to place hot functions near to each other in
248     memory.
249    
250 sf-exg 1.19 Whether a function is hot or not often depends on the whole program,
251 root 1.17 and less on the function itself. C<ecb_cold> is likely more useful in
252     practise.
253    
254 root 1.2 =item ecb_cold
255    
256 root 1.17 The opposite of C<ecb_hot> - declares a function as "cold" with regards to
257     the cache, or in other words, this function is not called often, or not at
258     speed-critical times, and keeping it in the cache might be a waste of said
259     cache.
260    
261     In addition to placing cold functions together (or at least away from hot
262     functions), this knowledge can be used in other ways, for example, the
263     function will be optimised for size, as opposed to speed, and codepaths
264     leading to calls to those functions can automatically be marked as if
265 root 1.27 C<ecb_expect_false> had been used to reach them.
266 root 1.17
267     Good examples for such functions would be error reporting functions, or
268     functions only called in exceptional or rare cases.
269    
270 root 1.2 =item ecb_artificial
271    
272 root 1.17 Declares the function as "artificial", in this case meaning that this
273     function is not really mean to be a function, but more like an accessor
274     - many methods in C++ classes are mere accessor functions, and having a
275     crash reported in such a method, or single-stepping through them, is not
276     usually so helpful, especially when it's inlined to just a few instructions.
277    
278     Marking them as artificial will instruct the debugger about just this,
279     leading to happier debugging and thus happier lives.
280    
281     Example: in some kind of smart-pointer class, mark the pointer accessor as
282     artificial, so that the whole class acts more like a pointer and less like
283     some C++ abstraction monster.
284    
285     template<typename T>
286     struct my_smart_ptr
287     {
288     T *value;
289    
290     ecb_artificial
291     operator T *()
292     {
293     return value;
294     }
295     };
296    
297 root 1.2 =back
298 root 1.1
299     =head2 OPTIMISATION HINTS
300    
301     =over 4
302    
303 root 1.14 =item bool ecb_is_constant(expr)
304 root 1.1
305 root 1.3 Returns true iff the expression can be deduced to be a compile-time
306     constant, and false otherwise.
307    
308     For example, when you have a C<rndm16> function that returns a 16 bit
309     random number, and you have a function that maps this to a range from
310 root 1.5 0..n-1, then you could use this inline function in a header file:
311 root 1.3
312     ecb_inline uint32_t
313     rndm (uint32_t n)
314     {
315 root 1.6 return (n * (uint32_t)rndm16 ()) >> 16;
316 root 1.3 }
317    
318     However, for powers of two, you could use a normal mask, but that is only
319     worth it if, at compile time, you can detect this case. This is the case
320     when the passed number is a constant and also a power of two (C<n & (n -
321     1) == 0>):
322    
323     ecb_inline uint32_t
324     rndm (uint32_t n)
325     {
326     return is_constant (n) && !(n & (n - 1))
327     ? rndm16 () & (num - 1)
328 root 1.6 : (n * (uint32_t)rndm16 ()) >> 16;
329 root 1.3 }
330    
331 root 1.14 =item bool ecb_expect (expr, value)
332 root 1.1
333 root 1.7 Evaluates C<expr> and returns it. In addition, it tells the compiler that
334     the C<expr> evaluates to C<value> a lot, which can be used for static
335     branch optimisations.
336 root 1.1
337 root 1.27 Usually, you want to use the more intuitive C<ecb_expect_true> and
338     C<ecb_expect_false> functions instead.
339 root 1.1
340 root 1.27 =item bool ecb_expect_true (cond)
341 root 1.1
342 root 1.27 =item bool ecb_expect_false (cond)
343 root 1.1
344 root 1.7 These two functions expect a expression that is true or false and return
345     C<1> or C<0>, respectively, so when used in the condition of an C<if> or
346     other conditional statement, it will not change the program:
347    
348     /* these two do the same thing */
349     if (some_condition) ...;
350 root 1.27 if (ecb_expect_true (some_condition)) ...;
351 root 1.7
352 root 1.27 However, by using C<ecb_expect_true>, you tell the compiler that the
353     condition is likely to be true (and for C<ecb_expect_false>, that it is
354     unlikely to be true).
355 root 1.7
356 root 1.9 For example, when you check for a null pointer and expect this to be a
357 root 1.27 rare, exceptional, case, then use C<ecb_expect_false>:
358 root 1.7
359     void my_free (void *ptr)
360     {
361 root 1.27 if (ecb_expect_false (ptr == 0))
362 root 1.7 return;
363     }
364    
365     Consequent use of these functions to mark away exceptional cases or to
366     tell the compiler what the hot path through a function is can increase
367     performance considerably.
368    
369 root 1.27 You might know these functions under the name C<likely> and C<unlikely>
370     - while these are common aliases, we find that the expect name is easier
371     to understand when quickly skimming code. If you wish, you can use
372     C<ecb_likely> instead of C<ecb_expect_true> and C<ecb_unlikely> instead of
373     C<ecb_expect_false> - these are simply aliases.
374    
375 root 1.7 A very good example is in a function that reserves more space for some
376     memory block (for example, inside an implementation of a string stream) -
377 root 1.9 each time something is added, you have to check for a buffer overrun, but
378 root 1.7 you expect that most checks will turn out to be false:
379    
380     /* make sure we have "size" extra room in our buffer */
381     ecb_inline void
382     reserve (int size)
383     {
384 root 1.27 if (ecb_expect_false (current + size > end))
385 root 1.7 real_reserve_method (size); /* presumably noinline */
386     }
387    
388 root 1.14 =item bool ecb_assume (cond)
389 root 1.7
390     Try to tell the compiler that some condition is true, even if it's not
391     obvious.
392    
393     This can be used to teach the compiler about invariants or other
394     conditions that might improve code generation, but which are impossible to
395     deduce form the code itself.
396    
397 root 1.27 For example, the example reservation function from the C<ecb_expect_false>
398 root 1.7 description could be written thus (only C<ecb_assume> was added):
399    
400     ecb_inline void
401     reserve (int size)
402     {
403 root 1.27 if (ecb_expect_false (current + size > end))
404 root 1.7 real_reserve_method (size); /* presumably noinline */
405    
406     ecb_assume (current + size <= end);
407     }
408    
409     If you then call this function twice, like this:
410    
411     reserve (10);
412     reserve (1);
413    
414     Then the compiler I<might> be able to optimise out the second call
415     completely, as it knows that C<< current + 1 > end >> is false and the
416     call will never be executed.
417    
418     =item bool ecb_unreachable ()
419    
420     This function does nothing itself, except tell the compiler that it will
421 root 1.9 never be executed. Apart from suppressing a warning in some cases, this
422 root 1.7 function can be used to implement C<ecb_assume> or similar functions.
423    
424 root 1.14 =item bool ecb_prefetch (addr, rw, locality)
425 root 1.7
426     Tells the compiler to try to prefetch memory at the given C<addr>ess
427 root 1.10 for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
428 root 1.7 C<0> means that there will only be one access later, C<3> means that
429     the data will likely be accessed very often, and values in between mean
430     something... in between. The memory pointed to by the address does not
431     need to be accessible (it could be a null pointer for example), but C<rw>
432     and C<locality> must be compile-time constants.
433    
434     An obvious way to use this is to prefetch some data far away, in a big
435 root 1.9 array you loop over. This prefetches memory some 128 array elements later,
436 root 1.7 in the hope that it will be ready when the CPU arrives at that location.
437    
438     int sum = 0;
439    
440     for (i = 0; i < N; ++i)
441     {
442     sum += arr [i]
443     ecb_prefetch (arr + i + 128, 0, 0);
444     }
445    
446     It's hard to predict how far to prefetch, and most CPUs that can prefetch
447     are often good enough to predict this kind of behaviour themselves. It
448     gets more interesting with linked lists, especially when you do some fair
449     processing on each list element:
450    
451     for (node *n = start; n; n = n->next)
452     {
453     ecb_prefetch (n->next, 0, 0);
454     ... do medium amount of work with *n
455     }
456    
457     After processing the node, (part of) the next node might already be in
458     cache.
459 root 1.1
460 root 1.2 =back
461 root 1.1
462 root 1.36 =head2 BIT FIDDLING / BIT WIZARDRY
463 root 1.1
464 root 1.4 =over 4
465    
466 root 1.3 =item bool ecb_big_endian ()
467    
468     =item bool ecb_little_endian ()
469    
470 sf-exg 1.11 These two functions return true if the byte order is big endian
471     (most-significant byte first) or little endian (least-significant byte
472     first) respectively.
473    
474 root 1.24 On systems that are neither, their return values are unspecified.
475    
476 root 1.3 =item int ecb_ctz32 (uint32_t x)
477    
478 root 1.35 =item int ecb_ctz64 (uint64_t x)
479    
480 sf-exg 1.11 Returns the index of the least significant bit set in C<x> (or
481 root 1.24 equivalently the number of bits set to 0 before the least significant bit
482 root 1.35 set), starting from 0. If C<x> is 0 the result is undefined.
483    
484 root 1.36 For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
485    
486 root 1.35 For example:
487 sf-exg 1.11
488 root 1.15 ecb_ctz32 (3) = 0
489     ecb_ctz32 (6) = 1
490 sf-exg 1.11
491 root 1.41 =item bool ecb_is_pot32 (uint32_t x)
492    
493     =item bool ecb_is_pot64 (uint32_t x)
494    
495     Return true iff C<x> is a power of two or C<x == 0>.
496    
497     For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
498    
499 root 1.35 =item int ecb_ld32 (uint32_t x)
500    
501     =item int ecb_ld64 (uint64_t x)
502    
503     Returns the index of the most significant bit set in C<x>, or the number
504     of digits the number requires in binary (so that C<< 2**ld <= x <
505     2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
506     to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
507     example to see how many bits a certain number requires to be encoded.
508    
509     This function is similar to the "count leading zero bits" function, except
510     that that one returns how many zero bits are "in front" of the number (in
511     the given data type), while C<ecb_ld> returns how many bits the number
512     itself requires.
513    
514 root 1.36 For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
515    
516 root 1.3 =item int ecb_popcount32 (uint32_t x)
517    
518 root 1.35 =item int ecb_popcount64 (uint64_t x)
519    
520 root 1.36 Returns the number of bits set to 1 in C<x>.
521    
522     For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
523    
524     For example:
525 sf-exg 1.11
526 root 1.15 ecb_popcount32 (7) = 3
527     ecb_popcount32 (255) = 8
528 sf-exg 1.11
529 root 1.39 =item uint8_t ecb_bitrev8 (uint8_t x)
530    
531     =item uint16_t ecb_bitrev16 (uint16_t x)
532    
533     =item uint32_t ecb_bitrev32 (uint32_t x)
534    
535     Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
536     and so on.
537    
538     Example:
539    
540     ecb_bitrev8 (0xa7) = 0xea
541     ecb_bitrev32 (0xffcc4411) = 0x882233ff
542    
543 root 1.8 =item uint32_t ecb_bswap16 (uint32_t x)
544    
545 root 1.3 =item uint32_t ecb_bswap32 (uint32_t x)
546    
547 root 1.34 =item uint64_t ecb_bswap64 (uint64_t x)
548 sf-exg 1.13
549 root 1.34 These functions return the value of the 16-bit (32-bit, 64-bit) value
550     C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
551     C<ecb_bswap32>).
552    
553     =item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
554    
555     =item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
556 root 1.3
557     =item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
558    
559 root 1.34 =item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
560    
561     =item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
562    
563     =item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
564    
565     =item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
566    
567 root 1.33 =item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
568    
569 root 1.34 These two families of functions return the value of C<x> after rotating
570     all the bits by C<count> positions to the right (C<ecb_rotr>) or left
571     (C<ecb_rotl>).
572 sf-exg 1.11
573 root 1.20 Current GCC versions understand these functions and usually compile them
574 root 1.34 to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
575     x86).
576 root 1.20
577 root 1.3 =back
578 root 1.1
579     =head2 ARITHMETIC
580    
581 root 1.3 =over 4
582    
583 root 1.14 =item x = ecb_mod (m, n)
584 root 1.3
585 root 1.25 Returns C<m> modulo C<n>, which is the same as the positive remainder
586     of the division operation between C<m> and C<n>, using floored
587     division. Unlike the C remainder operator C<%>, this function ensures that
588     the return value is always positive and that the two numbers I<m> and
589     I<m' = m + i * n> result in the same value modulo I<n> - in other words,
590     C<ecb_mod> implements the mathematical modulo operation, which is missing
591     in the language.
592 root 1.14
593 sf-exg 1.23 C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
594 root 1.14 negatable, that is, both C<m> and C<-m> must be representable in its
595 root 1.30 type (this typically excludes the minimum signed integer value, the same
596 root 1.25 limitation as for C</> and C<%> in C).
597 sf-exg 1.11
598 root 1.24 Current GCC versions compile this into an efficient branchless sequence on
599 root 1.28 almost all CPUs.
600 root 1.24
601     For example, when you want to rotate forward through the members of an
602     array for increasing C<m> (which might be negative), then you should use
603     C<ecb_mod>, as the C<%> operator might give either negative results, or
604     change direction for negative values:
605    
606     for (m = -100; m <= 100; ++m)
607     int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
608    
609 sf-exg 1.37 =item x = ecb_div_rd (val, div)
610    
611     =item x = ecb_div_ru (val, div)
612    
613     Returns C<val> divided by C<div> rounded down or up, respectively.
614     C<val> and C<div> must have integer types and C<div> must be strictly
615 sf-exg 1.38 positive. Note that these functions are implemented with macros in C
616     and with function templates in C++.
617 sf-exg 1.37
618 root 1.3 =back
619 root 1.1
620     =head2 UTILITY
621    
622 root 1.3 =over 4
623    
624 sf-exg 1.23 =item element_count = ecb_array_length (name)
625 root 1.3
626 sf-exg 1.13 Returns the number of elements in the array C<name>. For example:
627    
628     int primes[] = { 2, 3, 5, 7, 11 };
629     int sum = 0;
630    
631     for (i = 0; i < ecb_array_length (primes); i++)
632     sum += primes [i];
633    
634 root 1.3 =back
635 root 1.1
636 root 1.43 =head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
637    
638     These symbols need to be defined before including F<ecb.h> the first time.
639    
640     =over 4
641    
642     =item ECB_NO_THRADS
643    
644     If F<ecb.h> is never used from multiple threads, then this symbol can
645     be defined, in which case memory fences (and similar constructs) are
646     completely removed, leading to more efficient code and fewer dependencies.
647    
648     Setting this symbol to a true value implies C<ECB_NO_SMP>.
649    
650     =item ECB_NO_SMP
651    
652     The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
653     multiple threads, but never concurrently (e.g. if the system the program
654     runs on has only a single CPU with a single core, no hyperthreading and so
655     on), then this symbol can be defined, leading to more efficient code and
656     fewer dependencies.
657    
658     =back
659    
660 root 1.1