[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.16 by sf-exg, Thu May 26 23:32:41 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	More might come.
4		21
5	=head2 ABOUT THE HEADER	22	=head2 ABOUT THE HEADER
6		23
7	- how to include it	24	At the moment, all you have to do is copy F<ecb.h> somewhere where your
8	- it includes inttypes.h	25	compiler can find it and include it:
9	- no .a	26
10	- whats a bool	27	#include <ecb.h>
11	- function mean macro or function	28
12	- macro means untyped	29	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.
		31
		32	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
		34	code size or gain access to additional features.
		35
		36	It also currently includes everything from F<inttypes.h>.
		37
		38	=head2 ABOUT THIS MANUAL / CONVENTIONS
		39
		40	This manual mainly describes each (public) function available after
		41	including the F<ecb.h> header. The header might define other symbols than
		42	these, but these are not part of the public API, and not supported in any
		43	way.
		44
		45	When the manual mentions a "function" then this could be defined either as
		46	as inline function, a macro, or an external symbol.
		47
		48	When functions use a concrete standard type, such as C<int> or
		49	C<uint32_t>, then the corresponding function works only with that type. If
		50	only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
		51	the corresponding function relies on C to implement the correct types, and
		52	is usually implemented as a macro. Specifically, a "bool" in this manual
		53	refers to any kind of boolean value, not a specific type.
13		54
14	=head2 GCC ATTRIBUTES	55	=head2 GCC ATTRIBUTES
15		56
16	blabla where to put, what others	57	blabla where to put, what others
17		58
18	=over 4	59	=over 4
19		60
20	=item ecb_attribute ((attrs...))	61	=item ecb_attribute ((attrs...))
21		62
22	A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and	63	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.	64	nothing on other compilers, so the effect is that only GCC sees these.
		65
		66	Example: use the C<deprecated> attribute on a function.
		67
		68	ecb_attribute((__deprecated__)) void
		69	do_not_use_me_anymore (void);
24		70
25	=item ecb_unused	71	=item ecb_unused
26		72
27	Marks a function or a variable as "unused", which simply suppresses a	73	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.	74	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:	75	declare a variable but do not always use it:
30		76
31	{	77	{
32	int var ecb_unused;	78	int var ecb_unused;
33		79
34	#ifdef SOMECONDITION	80	#ifdef SOMECONDITION
35	var = ...;	81	var = ...;
36	return var;	82	return var;
37	#else	83	#else
38	return 0;	84	return 0;
39	#endif	85	#endif
40	}	86	}
41		87
42	=item ecb_noinline	88	=item ecb_noinline
43		89
44	Prevent a function from being inlined - it might be optimised away, but	90	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	91	not inlined into other functions. This is useful if you know your function
61		107
62	=head2 OPTIMISATION HINTS	108	=head2 OPTIMISATION HINTS
63		109
64	=over 4	110	=over 4
65		111
66	=item bool ecb_is_constant(expr) [MACRO]	112	=item bool ecb_is_constant(expr)
67		113
68	Returns true iff the expression can be deduced to be a compile-time	114	Returns true iff the expression can be deduced to be a compile-time
69	constant, and false otherwise.	115	constant, and false otherwise.
70		116
71	For example, when you have a C<rndm16> function that returns a 16 bit	117	For example, when you have a C<rndm16> function that returns a 16 bit
…		…
89	return is_constant (n) && !(n & (n - 1))	135	return is_constant (n) && !(n & (n - 1))
90	? rndm16 () & (num - 1)	136	? rndm16 () & (num - 1)
91	: (n * (uint32_t)rndm16 ()) >> 16;	137	: (n * (uint32_t)rndm16 ()) >> 16;
92	}	138	}
93		139
94	=item bool ecb_expect (expr, value) [MACRO]	140	=item bool ecb_expect (expr, value)
95		141
96	Evaluates C<expr> and returns it. In addition, it tells the compiler that	142	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	143	the C<expr> evaluates to C<value> a lot, which can be used for static
98	branch optimisations.	144	branch optimisations.
99		145
100	Usually, you want to use the more intuitive C<ecb_likely> and	146	Usually, you want to use the more intuitive C<ecb_likely> and
101	C<ecb_unlikely> functions instead.	147	C<ecb_unlikely> functions instead.
102		148
103	=item bool ecb_likely (bool) [MACRO]	149	=item bool ecb_likely (cond)
104		150
105	=item bool ecb_unlikely (bool) [MACRO]	151	=item bool ecb_unlikely (cond)
106		152
107	These two functions expect a expression that is true or false and return	153	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	154	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:	155	other conditional statement, it will not change the program:
110		156
…		…
140	{	186	{
141	if (ecb_unlikely (current + size > end))	187	if (ecb_unlikely (current + size > end))
142	real_reserve_method (size); /* presumably noinline */	188	real_reserve_method (size); /* presumably noinline */
143	}	189	}
144		190
145	=item bool ecb_assume (cond) [MACRO]	191	=item bool ecb_assume (cond)
146		192
147	Try to tell the compiler that some condition is true, even if it's not	193	Try to tell the compiler that some condition is true, even if it's not
148	obvious.	194	obvious.
149		195
150	This can be used to teach the compiler about invariants or other	196	This can be used to teach the compiler about invariants or other
…		…
176		222
177	This function does nothing itself, except tell the compiler that it will	223	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	224	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.	225	function can be used to implement C<ecb_assume> or similar functions.
180		226
181	=item bool ecb_prefetch (addr, rw, locality) [MACRO]	227	=item bool ecb_prefetch (addr, rw, locality)
182		228
183	Tells the compiler to try to prefetch memory at the given C<addr>ess	229	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	230	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	231	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	232	the data will likely be accessed very often, and values in between mean
…		…
234	equivalently the number of bits set to 0 before the least significant	280	equivalently the number of bits set to 0 before the least significant
235	bit set), starting from 0. If C<x> is 0 the result is undefined. A	281	bit set), starting from 0. If C<x> is 0 the result is undefined. A
236	common use case is to compute the integer binary logarithm, i.e.,	282	common use case is to compute the integer binary logarithm, i.e.,
237	floor(log2(n)). For example:	283	floor(log2(n)). For example:
238		284
239	ecb_ctz32(3) = 1	285	ecb_ctz32 (3) = 0
240	ecb_ctz32(6) = 2	286	ecb_ctz32 (6) = 1
241		287
242	=item int ecb_popcount32 (uint32_t x)	288	=item int ecb_popcount32 (uint32_t x)
243		289
244	Returns the number of bits set to 1 in C<x>. For example:	290	Returns the number of bits set to 1 in C<x>. For example:
245		291
246	ecb_popcount32(7) = 3	292	ecb_popcount32 (7) = 3
247	ecb_popcount32(255) = 8	293	ecb_popcount32 (255) = 8
248		294
249	=item uint32_t ecb_bswap16 (uint32_t x)	295	=item uint32_t ecb_bswap16 (uint32_t x)
250		296
251	=item uint32_t ecb_bswap32 (uint32_t x)	297	=item uint32_t ecb_bswap32 (uint32_t x)
		298
		299	These two functions return the value of the 16-bit (32-bit) variable
		300	C<x> after reversing the order of bytes.
252		301
253	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	302	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
254		303
255	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	304	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
256		305
…		…
261		310
262	=head2 ARITHMETIC	311	=head2 ARITHMETIC
263		312
264	=over 4	313	=over 4
265		314
266	=item x = ecb_mod (m, n) [MACRO]	315	=item x = ecb_mod (m, n)
267		316
268	Returns the positive remainder of the modulo operation between C<m>	317	Returns the positive remainder of the modulo operation between C<m> and
269	and C<n>.	318	C<n>. Unlike the C modulo operator C<%>, this function ensures that the
		319	return value is always positive).
		320
		321	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
		323	type.
270		324
271	=back	325	=back
272		326
273	=head2 UTILITY	327	=head2 UTILITY
274		328
275	=over 4	329	=over 4
276		330
277	=item element_count = ecb_array_length (name) [MACRO]	331	=item element_count = ecb_array_length (name) [MACRO]
278		332
279	=back	333	Returns the number of elements in the array C<name>. For example:
280		334
		335	int primes[] = { 2, 3, 5, 7, 11 };
		336	int sum = 0;
281		337
		338	for (i = 0; i < ecb_array_length (primes); i++)
		339	sum += primes [i];
		340
		341	=back
		342
		343

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.16 by sf-exg, Thu May 26 23:32:41 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.16 by sf-exg, Thu May 26 23:32:41 2011 UTC