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

Comparing libecb/ecb.pod (file contents):
Revision 1.15 by root, Thu May 26 23:26:29 2011 UTC vs.
Revision 1.18 by root, Fri May 27 00:01:28 2011 UTC

… …
3=head2 ABOUT LIBECB 3=head2 ABOUT LIBECB
4 4
5Libecb is currently a simple header file that doesn't require any 5Libecb is currently a simple header file that doesn't require any
6configuration to use or include in your project. 6configuration to use or include in your project.
7 7
8It's part of the e-suite of libraries, other memembers of which include 8It's part of the e-suite of libraries, other members of which include
9libev and libeio. 9libev and libeio.
10 10
11Its homepage can be found here: 11Its homepage can be found here:
12 12
13 http://software.schmorp.de/pkg/libecb 13 http://software.schmorp.de/pkg/libecb
14 14
15It mainly provides a number of wrappers around GCC built-ins, together 15It mainly provides a number of wrappers around GCC built-ins, together
16with replacement functions for other compilers. In addition to this, 16with replacement functions for other compilers. In addition to this,
17it provides a number of other lowlevel C utilities, such endienness 17it provides a number of other lowlevel C utilities, such as endianness
18detection, byte swapping or bit rotations. 18detection, byte swapping or bit rotations.
19
20Or in other words, things that should be built-in into any standard C
21system, but aren't.
19 22
20More might come. 23More might come.
21 24
22=head2 ABOUT THE HEADER 25=head2 ABOUT THE HEADER
23 26
… …
27 #include <ecb.h> 30 #include <ecb.h>
28 31
29The header should work fine for both C and C++ compilation, and gives you 32The header should work fine for both C and C++ compilation, and gives you
30all of F<inttypes.h> in addition to the ECB symbols. 33all of F<inttypes.h> in addition to the ECB symbols.
31 34
32There are currently no objetc files to link to - future versions might 35There are currently no object files to link to - future versions might
33come with an (optional) object code library to link against, to reduce 36come with an (optional) object code library to link against, to reduce
34code size or gain access to additional features. 37code size or gain access to additional features.
35 38
36It also currently includes everything from F<inttypes.h>. 39It also currently includes everything from F<inttypes.h>.
37 40
… …
91not inlined into other functions. This is useful if you know your function 94not inlined into other functions. This is useful if you know your function
92is rarely called and large enough for inlining not to be helpful. 95is rarely called and large enough for inlining not to be helpful.
93 96
94=item ecb_noreturn 97=item ecb_noreturn
95 98
99Marks a function as "not returning, ever". Some typical functions that
100don't return are C<exit> or C<abort> (which really works hard to not
101return), and now you can make your own:
102
103 ecb_noreturn void
104 my_abort (const char *errline)
105 {
106 puts (errline);
107 abort ();
108 }
109
110In this case, the compiler would probbaly be smart enough to decude it on
111it's own, so this is mainly useful for declarations.
112
96=item ecb_const 113=item ecb_const
97 114
115Declares that the function only depends on the values of it's arguments,
116much like a mathematical function. It specifically does not read or write
117any memory any arguments might point to, global variables, or call any
118non-const functions. It also must not have any side effects.
119
120Such a function can be optimised much more aggressively by the compiler -
121for example, multiple calls with the same arguments can be optimised into
122a single call, which wouldn't be possible if the compiler would have to
123expect any side effects.
124
125It is best suited for functions in the sense of mathematical functions,
126such as a function return the square root of its input argument.
127
128Not suited would be a function that calculates the hash of some memory
129area you pass in, prints some messages or looks at a global variable to
130decide on rounding.
131
132See C<ecb_pure> for a slightly less restrictive class of functions.
133
98=item ecb_pure 134=item ecb_pure
99 135
136Similar to C<ecb_const>, declares a function that has no side
137effects. Unlike C<ecb_const>, the function is allowed to examine global
138variables and any other memory areas (such as the ones passed to it via
139pointers).
140
141While these functions cannot be optimised as aggressively as C<ecb_const>
142functions, they can still be optimised away in many occasions, and the
143compiler has more freedom in moving calls to them around.
144
145Typical examples for such functions would be C<strlen> or C<memcmp>. A
146function that calculates the MD5 sum of some input and updates some MD5
147state passed as argument would I<NOT> be pure, however, as it would modify
148some memory area that is not the return value.
149
100=item ecb_hot 150=item ecb_hot
101 151
152This declares a function as "hot" with regards to the cache - the function
153is used so often, that it is very beneficial to keep it in the cache if
154possible.
155
156The compiler reacts by trying to place hot functions near to each other in
157memory.
158
159Whether a function is hot or not often depend son the whole program,
160and less on the function itself. C<ecb_cold> is likely more useful in
161practise.
162
102=item ecb_cold 163=item ecb_cold
103 164
165The opposite of C<ecb_hot> - declares a function as "cold" with regards to
166the cache, or in other words, this function is not called often, or not at
167speed-critical times, and keeping it in the cache might be a waste of said
168cache.
169
170In addition to placing cold functions together (or at least away from hot
171functions), this knowledge can be used in other ways, for example, the
172function will be optimised for size, as opposed to speed, and codepaths
173leading to calls to those functions can automatically be marked as if
174C<ecb_unlikel> had been used to reach them.
175
176Good examples for such functions would be error reporting functions, or
177functions only called in exceptional or rare cases.
178
104=item ecb_artificial 179=item ecb_artificial
180
181Declares the function as "artificial", in this case meaning that this
182function is not really mean to be a function, but more like an accessor
183- many methods in C++ classes are mere accessor functions, and having a
184crash reported in such a method, or single-stepping through them, is not
185usually so helpful, especially when it's inlined to just a few instructions.
186
187Marking them as artificial will instruct the debugger about just this,
188leading to happier debugging and thus happier lives.
189
190Example: in some kind of smart-pointer class, mark the pointer accessor as
191artificial, so that the whole class acts more like a pointer and less like
192some C++ abstraction monster.
193
194 template<typename T>
195 struct my_smart_ptr
196 {
197 T *value;
198
199 ecb_artificial
200 operator T *()
201 {
202 return value;
203 }
204 };
105 205
106=back 206=back
107 207
108=head2 OPTIMISATION HINTS 208=head2 OPTIMISATION HINTS
109 209
… …
313=over 4 413=over 4
314 414
315=item x = ecb_mod (m, n) 415=item x = ecb_mod (m, n)
316 416
317Returns the positive remainder of the modulo operation between C<m> and 417Returns the positive remainder of the modulo operation between C<m> and
318C<n>. Unlike the C moduloe operator C<%>, this function ensures that the 418C<n>. Unlike the C modulo operator C<%>, this function ensures that the
319return value is always positive). 419return value is always positive).
320 420
321C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be 421C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be
322negatable, that is, both C<m> and C<-m> must be representable in its 422negatable, that is, both C<m> and C<-m> must be representable in its
323type. 423type.

Diff Legend

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