[ViewVC] Diff of: cvs/libecb/ecb.pod

Comparing libecb/ecb.pod (file contents):
Revision 1.15 by root, Thu May 26 23:26:29 2011 UTC vs.
Revision 1.39 by root, Sat Dec 10 11:58:38 2011 UTC

…		…
3	=head2 ABOUT LIBECB	3	=head2 ABOUT LIBECB
4		4
5	Libecb is currently a simple header file that doesn't require any	5	Libecb is currently a simple header file that doesn't require any
6	configuration to use or include in your project.	6	configuration to use or include in your project.
7		7
8	It's part of the e-suite of libraries, other memembers of which include	8	It's part of the e-suite of libraries, other members of which include
9	libev and libeio.	9	libev and libeio.
10		10
11	Its homepage can be found here:	11	Its homepage can be found here:
12		12
13	http://software.schmorp.de/pkg/libecb	13	http://software.schmorp.de/pkg/libecb
14		14
15	It mainly provides a number of wrappers around GCC built-ins, together	15	It mainly provides a number of wrappers around GCC built-ins, together
16	with replacement functions for other compilers. In addition to this,	16	with replacement functions for other compilers. In addition to this,
17	it provides a number of other lowlevel C utilities, such endienness	17	it provides a number of other lowlevel C utilities, such as endianness
18	detection, byte swapping or bit rotations.	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.
19		23
20	More might come.	24	More might come.
21		25
22	=head2 ABOUT THE HEADER	26	=head2 ABOUT THE HEADER
23		27
…		…
27	#include <ecb.h>	31	#include <ecb.h>
28		32
29	The header should work fine for both C and C++ compilation, and gives you	33	The header should work fine for both C and C++ compilation, and gives you
30	all of F<inttypes.h> in addition to the ECB symbols.	34	all of F<inttypes.h> in addition to the ECB symbols.
31		35
32	There are currently no objetc files to link to - future versions might	36	There are currently no object files to link to - future versions might
33	come with an (optional) object code library to link against, to reduce	37	come with an (optional) object code library to link against, to reduce
34	code size or gain access to additional features.	38	code size or gain access to additional features.
35		39
36	It also currently includes everything from F<inttypes.h>.	40	It also currently includes everything from F<inttypes.h>.
37		41
…		…
52	is usually implemented as a macro. Specifically, a "bool" in this manual	56	is usually implemented as a macro. Specifically, a "bool" in this manual
53	refers to any kind of boolean value, not a specific type.	57	refers to any kind of boolean value, not a specific type.
54		58
55	=head2 GCC ATTRIBUTES	59	=head2 GCC ATTRIBUTES
56		60
57	blabla where to put, what others	61	A major part of libecb deals with GCC attributes. These are additional
		62	attributes that you can assign to functions, variables and sometimes even
		63	types - much like C<const> or C<volatile> in C.
		64
		65	While GCC allows declarations to show up in many surprising places,
		66	but not in many expected places, the safest way is to put attribute
		67	declarations before the whole declaration:
		68
		69	ecb_const int mysqrt (int a);
		70	ecb_unused int i;
		71
		72	For variables, it is often nicer to put the attribute after the name, and
		73	avoid multiple declarations using commas:
		74
		75	int i ecb_unused;
58		76
59	=over 4	77	=over 4
60		78
61	=item ecb_attribute ((attrs...))	79	=item ecb_attribute ((attrs...))
62		80
…		…
83	#else	101	#else
84	return 0;	102	return 0;
85	#endif	103	#endif
86	}	104	}
87		105
		106	=item ecb_inline
		107
		108	This is not actually an attribute, but you use it like one. It expands
		109	either to C<static inline> or to just C<static>, if inline isn't
		110	supported. It should be used to declare functions that should be inlined,
		111	for code size or speed reasons.
		112
		113	Example: inline this function, it surely will reduce codesize.
		114
		115	ecb_inline int
		116	negmul (int a, int b)
		117	{
		118	return - (a * b);
		119	}
		120
88	=item ecb_noinline	121	=item ecb_noinline
89		122
90	Prevent a function from being inlined - it might be optimised away, but	123	Prevent a function from being inlined - it might be optimised away, but
91	not inlined into other functions. This is useful if you know your function	124	not inlined into other functions. This is useful if you know your function
92	is rarely called and large enough for inlining not to be helpful.	125	is rarely called and large enough for inlining not to be helpful.
93		126
94	=item ecb_noreturn	127	=item ecb_noreturn
95		128
		129	Marks a function as "not returning, ever". Some typical functions that
		130	don't return are C<exit> or C<abort> (which really works hard to not
		131	return), and now you can make your own:
		132
		133	ecb_noreturn void
		134	my_abort (const char *errline)
		135	{
		136	puts (errline);
		137	abort ();
		138	}
		139
		140	In this case, the compiler would probably be smart enough to deduce it on
		141	its own, so this is mainly useful for declarations.
		142
96	=item ecb_const	143	=item ecb_const
97		144
		145	Declares that the function only depends on the values of its arguments,
		146	much like a mathematical function. It specifically does not read or write
		147	any memory any arguments might point to, global variables, or call any
		148	non-const functions. It also must not have any side effects.
		149
		150	Such a function can be optimised much more aggressively by the compiler -
		151	for example, multiple calls with the same arguments can be optimised into
		152	a single call, which wouldn't be possible if the compiler would have to
		153	expect any side effects.
		154
		155	It is best suited for functions in the sense of mathematical functions,
		156	such as a function returning the square root of its input argument.
		157
		158	Not suited would be a function that calculates the hash of some memory
		159	area you pass in, prints some messages or looks at a global variable to
		160	decide on rounding.
		161
		162	See C<ecb_pure> for a slightly less restrictive class of functions.
		163
98	=item ecb_pure	164	=item ecb_pure
99		165
		166	Similar to C<ecb_const>, declares a function that has no side
		167	effects. Unlike C<ecb_const>, the function is allowed to examine global
		168	variables and any other memory areas (such as the ones passed to it via
		169	pointers).
		170
		171	While these functions cannot be optimised as aggressively as C<ecb_const>
		172	functions, they can still be optimised away in many occasions, and the
		173	compiler has more freedom in moving calls to them around.
		174
		175	Typical examples for such functions would be C<strlen> or C<memcmp>. A
		176	function that calculates the MD5 sum of some input and updates some MD5
		177	state passed as argument would I<NOT> be pure, however, as it would modify
		178	some memory area that is not the return value.
		179
100	=item ecb_hot	180	=item ecb_hot
101		181
		182	This declares a function as "hot" with regards to the cache - the function
		183	is used so often, that it is very beneficial to keep it in the cache if
		184	possible.
		185
		186	The compiler reacts by trying to place hot functions near to each other in
		187	memory.
		188
		189	Whether a function is hot or not often depends on the whole program,
		190	and less on the function itself. C<ecb_cold> is likely more useful in
		191	practise.
		192
102	=item ecb_cold	193	=item ecb_cold
103		194
		195	The opposite of C<ecb_hot> - declares a function as "cold" with regards to
		196	the cache, or in other words, this function is not called often, or not at
		197	speed-critical times, and keeping it in the cache might be a waste of said
		198	cache.
		199
		200	In addition to placing cold functions together (or at least away from hot
		201	functions), this knowledge can be used in other ways, for example, the
		202	function will be optimised for size, as opposed to speed, and codepaths
		203	leading to calls to those functions can automatically be marked as if
		204	C<ecb_expect_false> had been used to reach them.
		205
		206	Good examples for such functions would be error reporting functions, or
		207	functions only called in exceptional or rare cases.
		208
104	=item ecb_artificial	209	=item ecb_artificial
		210
		211	Declares the function as "artificial", in this case meaning that this
		212	function is not really mean to be a function, but more like an accessor
		213	- many methods in C++ classes are mere accessor functions, and having a
		214	crash reported in such a method, or single-stepping through them, is not
		215	usually so helpful, especially when it's inlined to just a few instructions.
		216
		217	Marking them as artificial will instruct the debugger about just this,
		218	leading to happier debugging and thus happier lives.
		219
		220	Example: in some kind of smart-pointer class, mark the pointer accessor as
		221	artificial, so that the whole class acts more like a pointer and less like
		222	some C++ abstraction monster.
		223
		224	template<typename T>
		225	struct my_smart_ptr
		226	{
		227	T *value;
		228
		229	ecb_artificial
		230	operator T *()
		231	{
		232	return value;
		233	}
		234	};
105		235
106	=back	236	=back
107		237
108	=head2 OPTIMISATION HINTS	238	=head2 OPTIMISATION HINTS
109		239
…		…
141		271
142	Evaluates C<expr> and returns it. In addition, it tells the compiler that	272	Evaluates C<expr> and returns it. In addition, it tells the compiler that
143	the C<expr> evaluates to C<value> a lot, which can be used for static	273	the C<expr> evaluates to C<value> a lot, which can be used for static
144	branch optimisations.	274	branch optimisations.
145		275
146	Usually, you want to use the more intuitive C<ecb_likely> and	276	Usually, you want to use the more intuitive C<ecb_expect_true> and
147	C<ecb_unlikely> functions instead.	277	C<ecb_expect_false> functions instead.
148		278
		279	=item bool ecb_expect_true (cond)
		280
149	=item bool ecb_likely (cond)	281	=item bool ecb_expect_false (cond)
150
151	=item bool ecb_unlikely (cond)
152		282
153	These two functions expect a expression that is true or false and return	283	These two functions expect a expression that is true or false and return
154	C<1> or C<0>, respectively, so when used in the condition of an C<if> or	284	C<1> or C<0>, respectively, so when used in the condition of an C<if> or
155	other conditional statement, it will not change the program:	285	other conditional statement, it will not change the program:
156		286
157	/* these two do the same thing */	287	/* these two do the same thing */
158	if (some_condition) ...;	288	if (some_condition) ...;
159	if (ecb_likely (some_condition)) ...;	289	if (ecb_expect_true (some_condition)) ...;
160		290
161	However, by using C<ecb_likely>, you tell the compiler that the condition	291	However, by using C<ecb_expect_true>, you tell the compiler that the
162	is likely to be true (and for C<ecb_unlikely>, that it is unlikely to be	292	condition is likely to be true (and for C<ecb_expect_false>, that it is
163	true).	293	unlikely to be true).
164		294
165	For example, when you check for a null pointer and expect this to be a	295	For example, when you check for a null pointer and expect this to be a
166	rare, exceptional, case, then use C<ecb_unlikely>:	296	rare, exceptional, case, then use C<ecb_expect_false>:
167		297
168	void my_free (void *ptr)	298	void my_free (void *ptr)
169	{	299	{
170	if (ecb_unlikely (ptr == 0))	300	if (ecb_expect_false (ptr == 0))
171	return;	301	return;
172	}	302	}
173		303
174	Consequent use of these functions to mark away exceptional cases or to	304	Consequent use of these functions to mark away exceptional cases or to
175	tell the compiler what the hot path through a function is can increase	305	tell the compiler what the hot path through a function is can increase
176	performance considerably.	306	performance considerably.
		307
		308	You might know these functions under the name C<likely> and C<unlikely>
		309	- while these are common aliases, we find that the expect name is easier
		310	to understand when quickly skimming code. If you wish, you can use
		311	C<ecb_likely> instead of C<ecb_expect_true> and C<ecb_unlikely> instead of
		312	C<ecb_expect_false> - these are simply aliases.
177		313
178	A very good example is in a function that reserves more space for some	314	A very good example is in a function that reserves more space for some
179	memory block (for example, inside an implementation of a string stream) -	315	memory block (for example, inside an implementation of a string stream) -
180	each time something is added, you have to check for a buffer overrun, but	316	each time something is added, you have to check for a buffer overrun, but
181	you expect that most checks will turn out to be false:	317	you expect that most checks will turn out to be false:
182		318
183	/* make sure we have "size" extra room in our buffer */	319	/* make sure we have "size" extra room in our buffer */
184	ecb_inline void	320	ecb_inline void
185	reserve (int size)	321	reserve (int size)
186	{	322	{
187	if (ecb_unlikely (current + size > end))	323	if (ecb_expect_false (current + size > end))
188	real_reserve_method (size); /* presumably noinline */	324	real_reserve_method (size); /* presumably noinline */
189	}	325	}
190		326
191	=item bool ecb_assume (cond)	327	=item bool ecb_assume (cond)
192		328
…		…
195		331
196	This can be used to teach the compiler about invariants or other	332	This can be used to teach the compiler about invariants or other
197	conditions that might improve code generation, but which are impossible to	333	conditions that might improve code generation, but which are impossible to
198	deduce form the code itself.	334	deduce form the code itself.
199		335
200	For example, the example reservation function from the C<ecb_unlikely>	336	For example, the example reservation function from the C<ecb_expect_false>
201	description could be written thus (only C<ecb_assume> was added):	337	description could be written thus (only C<ecb_assume> was added):
202		338
203	ecb_inline void	339	ecb_inline void
204	reserve (int size)	340	reserve (int size)
205	{	341	{
206	if (ecb_unlikely (current + size > end))	342	if (ecb_expect_false (current + size > end))
207	real_reserve_method (size); /* presumably noinline */	343	real_reserve_method (size); /* presumably noinline */
208		344
209	ecb_assume (current + size <= end);	345	ecb_assume (current + size <= end);
210	}	346	}
211		347
…		…
260	After processing the node, (part of) the next node might already be in	396	After processing the node, (part of) the next node might already be in
261	cache.	397	cache.
262		398
263	=back	399	=back
264		400
265	=head2 BIT FIDDLING / BITSTUFFS	401	=head2 BIT FIDDLING / BIT WIZARDRY
266		402
267	=over 4	403	=over 4
268		404
269	=item bool ecb_big_endian ()	405	=item bool ecb_big_endian ()
270		406
…		…
272		408
273	These two functions return true if the byte order is big endian	409	These two functions return true if the byte order is big endian
274	(most-significant byte first) or little endian (least-significant byte	410	(most-significant byte first) or little endian (least-significant byte
275	first) respectively.	411	first) respectively.
276		412
		413	On systems that are neither, their return values are unspecified.
		414
277	=item int ecb_ctz32 (uint32_t x)	415	=item int ecb_ctz32 (uint32_t x)
278		416
		417	=item int ecb_ctz64 (uint64_t x)
		418
279	Returns the index of the least significant bit set in C<x> (or	419	Returns the index of the least significant bit set in C<x> (or
280	equivalently the number of bits set to 0 before the least significant	420	equivalently the number of bits set to 0 before the least significant bit
281	bit set), starting from 0. If C<x> is 0 the result is undefined. A	421	set), starting from 0. If C<x> is 0 the result is undefined.
282	common use case is to compute the integer binary logarithm, i.e.,	422
283	floor(log2(n)). For example:	423	For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
		424
		425	For example:
284		426
285	ecb_ctz32 (3) = 0	427	ecb_ctz32 (3) = 0
286	ecb_ctz32 (6) = 1	428	ecb_ctz32 (6) = 1
287		429
		430	=item int ecb_ld32 (uint32_t x)
		431
		432	=item int ecb_ld64 (uint64_t x)
		433
		434	Returns the index of the most significant bit set in C<x>, or the number
		435	of digits the number requires in binary (so that C<< 2**ld <= x <
		436	2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
		437	to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
		438	example to see how many bits a certain number requires to be encoded.
		439
		440	This function is similar to the "count leading zero bits" function, except
		441	that that one returns how many zero bits are "in front" of the number (in
		442	the given data type), while C<ecb_ld> returns how many bits the number
		443	itself requires.
		444
		445	For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
		446
288	=item int ecb_popcount32 (uint32_t x)	447	=item int ecb_popcount32 (uint32_t x)
289		448
		449	=item int ecb_popcount64 (uint64_t x)
		450
290	Returns the number of bits set to 1 in C<x>. For example:	451	Returns the number of bits set to 1 in C<x>.
		452
		453	For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
		454
		455	For example:
291		456
292	ecb_popcount32 (7) = 3	457	ecb_popcount32 (7) = 3
293	ecb_popcount32 (255) = 8	458	ecb_popcount32 (255) = 8
294		459
		460	=item uint8_t ecb_bitrev8 (uint8_t x)
		461
		462	=item uint16_t ecb_bitrev16 (uint16_t x)
		463
		464	=item uint32_t ecb_bitrev32 (uint32_t x)
		465
		466	Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
		467	and so on.
		468
		469	Example:
		470
		471	ecb_bitrev8 (0xa7) = 0xea
		472	ecb_bitrev32 (0xffcc4411) = 0x882233ff
		473
295	=item uint32_t ecb_bswap16 (uint32_t x)	474	=item uint32_t ecb_bswap16 (uint32_t x)
296		475
297	=item uint32_t ecb_bswap32 (uint32_t x)	476	=item uint32_t ecb_bswap32 (uint32_t x)
298		477
		478	=item uint64_t ecb_bswap64 (uint64_t x)
		479
299	These two functions return the value of the 16-bit (32-bit) variable	480	These functions return the value of the 16-bit (32-bit, 64-bit) value
300	C<x> after reversing the order of bytes.	481	C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
		482	C<ecb_bswap32>).
		483
		484	=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
		485
		486	=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
		487
		488	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
		489
		490	=item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
		491
		492	=item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
		493
		494	=item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
301		495
302	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	496	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
303		497
304	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	498	=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
305		499
306	These two functions return the value of C<x> after shifting all the bits	500	These two families of functions return the value of C<x> after rotating
307	by C<count> positions to the right or left respectively.	501	all the bits by C<count> positions to the right (C<ecb_rotr>) or left
		502	(C<ecb_rotl>).
		503
		504	Current GCC versions understand these functions and usually compile them
		505	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
		506	x86).
308		507
309	=back	508	=back
310		509
311	=head2 ARITHMETIC	510	=head2 ARITHMETIC
312		511
313	=over 4	512	=over 4
314		513
315	=item x = ecb_mod (m, n)	514	=item x = ecb_mod (m, n)
316		515
317	Returns the positive remainder of the modulo operation between C<m> and	516	Returns C<m> modulo C<n>, which is the same as the positive remainder
		517	of the division operation between C<m> and C<n>, using floored
318	C<n>. Unlike the C moduloe operator C<%>, this function ensures that the	518	division. Unlike the C remainder operator C<%>, this function ensures that
319	return value is always positive).	519	the return value is always positive and that the two numbers I<m> and
		520	I<m' = m + i * n> result in the same value modulo I<n> - in other words,
		521	C<ecb_mod> implements the mathematical modulo operation, which is missing
		522	in the language.
320		523
321	C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be	524	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
322	negatable, that is, both C<m> and C<-m> must be representable in its	525	negatable, that is, both C<m> and C<-m> must be representable in its
323	type.	526	type (this typically excludes the minimum signed integer value, the same
		527	limitation as for C</> and C<%> in C).
		528
		529	Current GCC versions compile this into an efficient branchless sequence on
		530	almost all CPUs.
		531
		532	For example, when you want to rotate forward through the members of an
		533	array for increasing C<m> (which might be negative), then you should use
		534	C<ecb_mod>, as the C<%> operator might give either negative results, or
		535	change direction for negative values:
		536
		537	for (m = -100; m <= 100; ++m)
		538	int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
		539
		540	=item x = ecb_div_rd (val, div)
		541
		542	=item x = ecb_div_ru (val, div)
		543
		544	Returns C<val> divided by C<div> rounded down or up, respectively.
		545	C<val> and C<div> must have integer types and C<div> must be strictly
		546	positive. Note that these functions are implemented with macros in C
		547	and with function templates in C++.
324		548
325	=back	549	=back
326		550
327	=head2 UTILITY	551	=head2 UTILITY
328		552
329	=over 4	553	=over 4
330		554
331	=item element_count = ecb_array_length (name) [MACRO]	555	=item element_count = ecb_array_length (name)
332		556
333	Returns the number of elements in the array C<name>. For example:	557	Returns the number of elements in the array C<name>. For example:
334		558
335	int primes[] = { 2, 3, 5, 7, 11 };	559	int primes[] = { 2, 3, 5, 7, 11 };
336	int sum = 0;	560	int sum = 0;

Diff Legend

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

Comparing libecb/ecb.pod (file contents): Revision 1.15 by root, Thu May 26 23:26:29 2011 UTC vs. Revision 1.39 by root, Sat Dec 10 11:58:38 2011 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.15 by root, Thu May 26 23:26:29 2011 UTC vs.
Revision 1.39 by root, Sat Dec 10 11:58:38 2011 UTC