ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
(Generate patch)

Comparing libecb/ecb.pod (file contents):
Revision 1.6 by root, Thu May 26 20:06:43 2011 UTC vs.
Revision 1.7 by root, Thu May 26 20:49:40 2011 UTC

… …
6 6
7- how to include it 7- how to include it
8- it includes inttypes.h 8- it includes inttypes.h
9- no .a 9- no .a
10- whats a bool 10- whats a bool
11- function mean macro or function
12- macro means untyped
11 13
12=head2 GCC ATTRIBUTES 14=head2 GCC ATTRIBUTES
13 15
14blabla where to put, what others 16blabla where to put, what others
15 17
… …
87 return is_constant (n) && !(n & (n - 1)) 89 return is_constant (n) && !(n & (n - 1))
88 ? rndm16 () & (num - 1) 90 ? rndm16 () & (num - 1)
89 : (n * (uint32_t)rndm16 ()) >> 16; 91 : (n * (uint32_t)rndm16 ()) >> 16;
90 } 92 }
91 93
92=item bool ecb_expect(expr,value) 94=item bool ecb_expect (expr, value)
93 95
96Evaluates C<expr> and returns it. In addition, it tells the compiler that
97the C<expr> evaluates to C<value> a lot, which can be used for static
98branch optimisations.
99
100Usually, you want to use the more intuitive C<ecb_likely> and
101C<ecb_unlikely> functions instead.
102
103=item bool ecb_likely (bool)
104
94=item bool ecb_unlikely(bool) 105=item bool ecb_unlikely (bool)
95 106
96=item bool ecb_likely(bool) 107These two functions expect a expression that is true or false and return
108C<1> or C<0>, respectively, so when used in the condition of an C<if> or
109other conditional statement, it will not change the program:
97 110
111 /* these two do the same thing */
112 if (some_condition) ...;
113 if (ecb_likely (some_condition)) ...;
114
115However, by using C<ecb_likely>, you tell the compiler that the condition
116is likely to be true (and for C<ecb_unlikel>, that it is unlikely to be
117true).
118
119For example, when you check for a 0-ptr and expect this to be a rare,
120exceptional, case, then use C<ecb_unlikely>:
121
122 void my_free (void *ptr)
123 {
124 if (ecb_unlikely (ptr == 0))
125 return;
126 }
127
128Consequent use of these functions to mark away exceptional cases or to
129tell the compiler what the hot path through a function is can increase
130performance considerably.
131
132A very good example is in a function that reserves more space for some
133memory block (for example, inside an implementation of a string stream) -
134eahc time something is added, you have to check for a buffer overrun, but
135you expect that most checks will turn out to be false:
136
137 /* make sure we have "size" extra room in our buffer */
138 ecb_inline void
139 reserve (int size)
140 {
141 if (ecb_unlikely (current + size > end))
142 real_reserve_method (size); /* presumably noinline */
143 }
144
98=item bool ecb_assume(cond) 145=item bool ecb_assume (cond)
99 146
147Try to tell the compiler that some condition is true, even if it's not
148obvious.
149
150This can be used to teach the compiler about invariants or other
151conditions that might improve code generation, but which are impossible to
152deduce form the code itself.
153
154For example, the example reservation function from the C<ecb_unlikely>
155description could be written thus (only C<ecb_assume> was added):
156
157 ecb_inline void
158 reserve (int size)
159 {
160 if (ecb_unlikely (current + size > end))
161 real_reserve_method (size); /* presumably noinline */
162
163 ecb_assume (current + size <= end);
164 }
165
166If you then call this function twice, like this:
167
168 reserve (10);
169 reserve (1);
170
171Then the compiler I<might> be able to optimise out the second call
172completely, as it knows that C<< current + 1 > end >> is false and the
173call will never be executed.
174
100=item bool ecb_unreachable() 175=item bool ecb_unreachable ()
101 176
177This function does nothing itself, except tell the compiler that it will
178never be executed. Apart from supressing a warning in some cases, this
179function can be used to implement C<ecb_assume> or similar functions.
180
102=item bool ecb_prefetch(addr,rw,locality) 181=item bool ecb_prefetch (addr, rw, locality)
182
183Tells the compiler to try to prefetch memory at the given C<addr>ess
184for either reading (c<rw> = 0) or writing (C<rw> = 1). A C<locality> of
185C<0> means that there will only be one access later, C<3> means that
186the data will likely be accessed very often, and values in between mean
187something... in between. The memory pointed to by the address does not
188need to be accessible (it could be a null pointer for example), but C<rw>
189and C<locality> must be compile-time constants.
190
191An obvious way to use this is to prefetch some data far away, in a big
192array you loop over. This prefethces memory some 128 array elements later,
193in the hope that it will be ready when the CPU arrives at that location.
194
195 int sum = 0;
196
197 for (i = 0; i < N; ++i)
198 {
199 sum += arr [i]
200 ecb_prefetch (arr + i + 128, 0, 0);
201 }
202
203It's hard to predict how far to prefetch, and most CPUs that can prefetch
204are often good enough to predict this kind of behaviour themselves. It
205gets more interesting with linked lists, especially when you do some fair
206processing on each list element:
207
208 for (node *n = start; n; n = n->next)
209 {
210 ecb_prefetch (n->next, 0, 0);
211 ... do medium amount of work with *n
212 }
213
214After processing the node, (part of) the next node might already be in
215cache.
103 216
104=back 217=back
105 218
106=head2 BIT FIDDLING / BITSTUFFS 219=head2 BIT FIDDLING / BITSTUFFS
107 220

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines