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

Comparing libecb/ecb.pod (file contents):
Revision 1.11 by sf-exg, Thu May 26 21:18:52 2011 UTC vs.
Revision 1.35 by root, Fri Jun 17 21:38:31 2011 UTC

…		…
		1	=head1 LIBECB - e-C-Builtins
		2
1	=head1 LIBECB	3	=head2 ABOUT LIBECB
2		4
3	You suck, we don't(tm)	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.
4		25
5	=head2 ABOUT THE HEADER	26	=head2 ABOUT THE HEADER
6		27
7	- how to include it	28	At the moment, all you have to do is copy F<ecb.h> somewhere where your
8	- it includes inttypes.h	29	compiler can find it and include it:
9	- no .a	30
10	- whats a bool	31	#include <ecb.h>
11	- function mean macro or function	32
12	- macro means untyped	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.
13		58
14	=head2 GCC ATTRIBUTES	59	=head2 GCC ATTRIBUTES
15		60
16	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;
17		76
18	=over 4	77	=over 4
19		78
20	=item ecb_attribute ((attrs...))	79	=item ecb_attribute ((attrs...))
21		80
22	A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and	81	A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
23	to nothing on other compilers, so the effect is that only GCC sees these.	82	nothing on other compilers, so the effect is that only GCC sees these.
		83
		84	Example: use the C<deprecated> attribute on a function.
		85
		86	ecb_attribute((__deprecated__)) void
		87	do_not_use_me_anymore (void);
24		88
25	=item ecb_unused	89	=item ecb_unused
26		90
27	Marks a function or a variable as "unused", which simply suppresses a	91	Marks a function or a variable as "unused", which simply suppresses a
28	warning by GCC when it detects it as unused. This is useful when you e.g.	92	warning by GCC when it detects it as unused. This is useful when you e.g.
29	declare a variable but do not always use it:	93	declare a variable but do not always use it:
30		94
		95	{
		96	int var ecb_unused;
		97
		98	#ifdef SOMECONDITION
		99	var = ...;
		100	return var;
		101	#else
		102	return 0;
		103	#endif
		104	}
		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)
31	{	117	{
32	int var ecb_unused;	118	return - (a * b);
33
34	#ifdef SOMECONDITION
35	var = ...;
36	return var;
37	#else
38	return 0;
39	#endif
40	}	119	}
41		120
42	=item ecb_noinline	121	=item ecb_noinline
43		122
44	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
45	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
46	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.
47		126
48	=item ecb_noreturn	127	=item ecb_noreturn
49		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
50	=item ecb_const	143	=item ecb_const
51		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
52	=item ecb_pure	164	=item ecb_pure
53		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
54	=item ecb_hot	180	=item ecb_hot
55		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
56	=item ecb_cold	193	=item ecb_cold
57		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
58	=item ecb_artificial	209	=item ecb_artificial
59		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	};
		235
60	=back	236	=back
61		237
62	=head2 OPTIMISATION HINTS	238	=head2 OPTIMISATION HINTS
63		239
64	=over 4	240	=over 4
65		241
66	=item bool ecb_is_constant(expr) [MACRO]	242	=item bool ecb_is_constant(expr)
67		243
68	Returns true iff the expression can be deduced to be a compile-time	244	Returns true iff the expression can be deduced to be a compile-time
69	constant, and false otherwise.	245	constant, and false otherwise.
70		246
71	For example, when you have a C<rndm16> function that returns a 16 bit	247	For example, when you have a C<rndm16> function that returns a 16 bit
89	return is_constant (n) && !(n & (n - 1))	265	return is_constant (n) && !(n & (n - 1))
90	? rndm16 () & (num - 1)	266	? rndm16 () & (num - 1)
91	: (n * (uint32_t)rndm16 ()) >> 16;	267	: (n * (uint32_t)rndm16 ()) >> 16;
92	}	268	}
93		269
94	=item bool ecb_expect (expr, value) [MACRO]	270	=item bool ecb_expect (expr, value)
95		271
96	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
97	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
98	branch optimisations.	274	branch optimisations.
99		275
100	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
101	C<ecb_unlikely> functions instead.	277	C<ecb_expect_false> functions instead.
102		278
103	=item bool ecb_likely (bool) [MACRO]	279	=item bool ecb_expect_true (cond)
104		280
105	=item bool ecb_unlikely (bool) [MACRO]	281	=item bool ecb_expect_false (cond)
106		282
107	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
108	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
109	other conditional statement, it will not change the program:	285	other conditional statement, it will not change the program:
110		286
111	/* these two do the same thing */	287	/* these two do the same thing */
112	if (some_condition) ...;	288	if (some_condition) ...;
113	if (ecb_likely (some_condition)) ...;	289	if (ecb_expect_true (some_condition)) ...;
114		290
115	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
116	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
117	true).	293	unlikely to be true).
118		294
119	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
120	rare, exceptional, case, then use C<ecb_unlikely>:	296	rare, exceptional, case, then use C<ecb_expect_false>:
121		297
122	void my_free (void *ptr)	298	void my_free (void *ptr)
123	{	299	{
124	if (ecb_unlikely (ptr == 0))	300	if (ecb_expect_false (ptr == 0))
125	return;	301	return;
126	}	302	}
127		303
128	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
129	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
130	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.
131		313
132	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
133	memory block (for example, inside an implementation of a string stream) -	315	memory block (for example, inside an implementation of a string stream) -
134	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
135	you expect that most checks will turn out to be false:	317	you expect that most checks will turn out to be false:
136		318
137	/* make sure we have "size" extra room in our buffer */	319	/* make sure we have "size" extra room in our buffer */
138	ecb_inline void	320	ecb_inline void
139	reserve (int size)	321	reserve (int size)
140	{	322	{
141	if (ecb_unlikely (current + size > end))	323	if (ecb_expect_false (current + size > end))
142	real_reserve_method (size); /* presumably noinline */	324	real_reserve_method (size); /* presumably noinline */
143	}	325	}
144		326
145	=item bool ecb_assume (cond) [MACRO]	327	=item bool ecb_assume (cond)
146		328
147	Try to tell the compiler that some condition is true, even if it's not	329	Try to tell the compiler that some condition is true, even if it's not
148	obvious.	330	obvious.
149		331
150	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
151	conditions that might improve code generation, but which are impossible to	333	conditions that might improve code generation, but which are impossible to
152	deduce form the code itself.	334	deduce form the code itself.
153		335
154	For example, the example reservation function from the C<ecb_unlikely>	336	For example, the example reservation function from the C<ecb_expect_false>
155	description could be written thus (only C<ecb_assume> was added):	337	description could be written thus (only C<ecb_assume> was added):
156		338
157	ecb_inline void	339	ecb_inline void
158	reserve (int size)	340	reserve (int size)
159	{	341	{
160	if (ecb_unlikely (current + size > end))	342	if (ecb_expect_false (current + size > end))
161	real_reserve_method (size); /* presumably noinline */	343	real_reserve_method (size); /* presumably noinline */
162		344
163	ecb_assume (current + size <= end);	345	ecb_assume (current + size <= end);
164	}	346	}
165		347
…		…
176		358
177	This function does nothing itself, except tell the compiler that it will	359	This function does nothing itself, except tell the compiler that it will
178	never be executed. Apart from suppressing a warning in some cases, this	360	never be executed. Apart from suppressing a warning in some cases, this
179	function can be used to implement C<ecb_assume> or similar functions.	361	function can be used to implement C<ecb_assume> or similar functions.
180		362
181	=item bool ecb_prefetch (addr, rw, locality) [MACRO]	363	=item bool ecb_prefetch (addr, rw, locality)
182		364
183	Tells the compiler to try to prefetch memory at the given C<addr>ess	365	Tells the compiler to try to prefetch memory at the given C<addr>ess
184	for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of	366	for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
185	C<0> means that there will only be one access later, C<3> means that	367	C<0> means that there will only be one access later, C<3> means that
186	the data will likely be accessed very often, and values in between mean	368	the data will likely be accessed very often, and values in between mean
…		…
226		408
227	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
228	(most-significant byte first) or little endian (least-significant byte	410	(most-significant byte first) or little endian (least-significant byte
229	first) respectively.	411	first) respectively.
230		412
		413	On systems that are neither, their return values are unspecified.
		414
231	=item int ecb_ctz32 (uint32_t x)	415	=item int ecb_ctz32 (uint32_t x)
232		416
		417	=item int ecb_ctz64 (uint64_t x)
		418
233	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
234	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
235	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.
236	common use case is to compute the integer binary logarithm, i.e.,
237	floor(log2(n)). For example:
238		422
		423	For example:
		424
239	ecb_ctz32(3) = 1	425	ecb_ctz32 (3) = 0
240	ecb_ctz32(6) = 2	426	ecb_ctz32 (6) = 1
		427
		428	=item int ecb_ld32 (uint32_t x)
		429
		430	=item int ecb_ld64 (uint64_t x)
		431
		432	Returns the index of the most significant bit set in C<x>, or the number
		433	of digits the number requires in binary (so that C<< 2**ld <= x <
		434	2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
		435	to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
		436	example to see how many bits a certain number requires to be encoded.
		437
		438	This function is similar to the "count leading zero bits" function, except
		439	that that one returns how many zero bits are "in front" of the number (in
		440	the given data type), while C<ecb_ld> returns how many bits the number
		441	itself requires.
241		442
242	=item int ecb_popcount32 (uint32_t x)	443	=item int ecb_popcount32 (uint32_t x)
243		444
		445	=item int ecb_popcount64 (uint64_t x)
		446
244	Returns the number of bits set to 1 in C<x>. For example:	447	Returns the number of bits set to 1 in C<x>. For example:
245		448
246	ecb_popcount32(7) = 3	449	ecb_popcount32 (7) = 3
247	ecb_popcount32(255) = 8	450	ecb_popcount32 (255) = 8
248		451
249	=item uint32_t ecb_bswap16 (uint32_t x)	452	=item uint32_t ecb_bswap16 (uint32_t x)
250		453
251	=item uint32_t ecb_bswap32 (uint32_t x)	454	=item uint32_t ecb_bswap32 (uint32_t x)
252		455
		456	=item uint64_t ecb_bswap64 (uint64_t x)
		457
		458	These functions return the value of the 16-bit (32-bit, 64-bit) value
		459	C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
		460	C<ecb_bswap32>).
		461
		462	=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
		463
		464	=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
		465
		466	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
		467
		468	=item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
		469
		470	=item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
		471
		472	=item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
		473
253	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	474	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
254		475
255	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	476	=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
256		477
257	These two functions return the value of C<x> after shifting all the bits	478	These two families of functions return the value of C<x> after rotating
258	by C<count> positions to the right or left respectively.	479	all the bits by C<count> positions to the right (C<ecb_rotr>) or left
		480	(C<ecb_rotl>).
		481
		482	Current GCC versions understand these functions and usually compile them
		483	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
		484	x86).
259		485
260	=back	486	=back
261		487
262	=head2 ARITHMETIC	488	=head2 ARITHMETIC
263		489
264	=over 4	490	=over 4
265		491
266	=item x = ecb_mod (m, n) [MACRO]	492	=item x = ecb_mod (m, n)
267		493
268	Returns the positive remainder of the modulo operation between C<m>	494	Returns C<m> modulo C<n>, which is the same as the positive remainder
269	and C<n>.	495	of the division operation between C<m> and C<n>, using floored
		496	division. Unlike the C remainder operator C<%>, this function ensures that
		497	the return value is always positive and that the two numbers I<m> and
		498	I<m' = m + i * n> result in the same value modulo I<n> - in other words,
		499	C<ecb_mod> implements the mathematical modulo operation, which is missing
		500	in the language.
		501
		502	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
		503	negatable, that is, both C<m> and C<-m> must be representable in its
		504	type (this typically excludes the minimum signed integer value, the same
		505	limitation as for C</> and C<%> in C).
		506
		507	Current GCC versions compile this into an efficient branchless sequence on
		508	almost all CPUs.
		509
		510	For example, when you want to rotate forward through the members of an
		511	array for increasing C<m> (which might be negative), then you should use
		512	C<ecb_mod>, as the C<%> operator might give either negative results, or
		513	change direction for negative values:
		514
		515	for (m = -100; m <= 100; ++m)
		516	int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
270		517
271	=back	518	=back
272		519
273	=head2 UTILITY	520	=head2 UTILITY
274		521
275	=over 4	522	=over 4
276		523
277	=item element_count = ecb_array_length (name) [MACRO]	524	=item element_count = ecb_array_length (name)
		525
		526	Returns the number of elements in the array C<name>. For example:
		527
		528	int primes[] = { 2, 3, 5, 7, 11 };
		529	int sum = 0;
		530
		531	for (i = 0; i < ecb_array_length (primes); i++)
		532	sum += primes [i];
278		533
279	=back	534	=back
280		535
281		536

Diff Legend

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

Comparing libecb/ecb.pod (file contents): Revision 1.11 by sf-exg, Thu May 26 21:18:52 2011 UTC vs. Revision 1.35 by root, Fri Jun 17 21:38:31 2011 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.11 by sf-exg, Thu May 26 21:18:52 2011 UTC vs.
Revision 1.35 by root, Fri Jun 17 21:38:31 2011 UTC