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

Comparing libecb/ecb.pod (file contents):
Revision 1.12 by sf-exg, Thu May 26 21:34:16 2011 UTC vs.
Revision 1.14 by root, Thu May 26 23:23:08 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 memembers 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 endienness
		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 objetc 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
61		102
62	=head2 OPTIMISATION HINTS	103	=head2 OPTIMISATION HINTS
63		104
64	=over 4	105	=over 4
65		106
66	=item bool ecb_is_constant(expr) [MACRO]	107	=item bool ecb_is_constant(expr)
67		108
68	Returns true iff the expression can be deduced to be a compile-time	109	Returns true iff the expression can be deduced to be a compile-time
69	constant, and false otherwise.	110	constant, and false otherwise.
70		111
71	For example, when you have a C<rndm16> function that returns a 16 bit	112	For example, when you have a C<rndm16> function that returns a 16 bit
…		…
89	return is_constant (n) && !(n & (n - 1))	130	return is_constant (n) && !(n & (n - 1))
90	? rndm16 () & (num - 1)	131	? rndm16 () & (num - 1)
91	: (n * (uint32_t)rndm16 ()) >> 16;	132	: (n * (uint32_t)rndm16 ()) >> 16;
92	}	133	}
93		134
94	=item bool ecb_expect (expr, value) [MACRO]	135	=item bool ecb_expect (expr, value)
95		136
96	Evaluates C<expr> and returns it. In addition, it tells the compiler that	137	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	138	the C<expr> evaluates to C<value> a lot, which can be used for static
98	branch optimisations.	139	branch optimisations.
99		140
100	Usually, you want to use the more intuitive C<ecb_likely> and	141	Usually, you want to use the more intuitive C<ecb_likely> and
101	C<ecb_unlikely> functions instead.	142	C<ecb_unlikely> functions instead.
102		143
103	=item bool ecb_likely (bool) [MACRO]	144	=item bool ecb_likely (bool)
104		145
105	=item bool ecb_unlikely (bool) [MACRO]	146	=item bool ecb_unlikely (bool)
106		147
107	These two functions expect a expression that is true or false and return	148	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	149	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:	150	other conditional statement, it will not change the program:
110		151
…		…
140	{	181	{
141	if (ecb_unlikely (current + size > end))	182	if (ecb_unlikely (current + size > end))
142	real_reserve_method (size); /* presumably noinline */	183	real_reserve_method (size); /* presumably noinline */
143	}	184	}
144		185
145	=item bool ecb_assume (cond) [MACRO]	186	=item bool ecb_assume (cond)
146		187
147	Try to tell the compiler that some condition is true, even if it's not	188	Try to tell the compiler that some condition is true, even if it's not
148	obvious.	189	obvious.
149		190
150	This can be used to teach the compiler about invariants or other	191	This can be used to teach the compiler about invariants or other
…		…
176		217
177	This function does nothing itself, except tell the compiler that it will	218	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	219	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.	220	function can be used to implement C<ecb_assume> or similar functions.
180		221
181	=item bool ecb_prefetch (addr, rw, locality) [MACRO]	222	=item bool ecb_prefetch (addr, rw, locality)
182		223
183	Tells the compiler to try to prefetch memory at the given C<addr>ess	224	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	225	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	226	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	227	the data will likely be accessed very often, and values in between mean
…		…
248		289
249	=item uint32_t ecb_bswap16 (uint32_t x)	290	=item uint32_t ecb_bswap16 (uint32_t x)
250		291
251	=item uint32_t ecb_bswap32 (uint32_t x)	292	=item uint32_t ecb_bswap32 (uint32_t x)
252		293
		294	These two functions return the value of the 16-bit (32-bit) variable
		295	C<x> after reversing the order of bytes.
		296
253	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	297	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
254		298
255	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	299	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
256		300
257	These two functions return the value of C<x> after shifting all the bits	301	These two functions return the value of C<x> after shifting all the bits
…		…
261		305
262	=head2 ARITHMETIC	306	=head2 ARITHMETIC
263		307
264	=over 4	308	=over 4
265		309
266	=item x = ecb_mod (m, n) [MACRO]	310	=item x = ecb_mod (m, n)
267		311
268	Returns the positive remainder of the modulo operation between C<m>	312	Returns the positive remainder of the modulo operation between C<m> and
269	and C<n>.	313	C<n>. Unlike the C moduloe operator C<%>, this function ensures that the
		314	return value is always positive).
		315
		316	C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be
		317	negatable, that is, both C<m> and C<-m> must be representable in its
		318	type.
270		319
271	=back	320	=back
272		321
273	=head2 UTILITY	322	=head2 UTILITY
274		323
275	=over 4	324	=over 4
276		325
277	=item element_count = ecb_array_length (name) [MACRO]	326	=item element_count = ecb_array_length (name) [MACRO]
278		327
279	=back	328	Returns the number of elements in the array C<name>. For example:
280		329
		330	int primes[] = { 2, 3, 5, 7, 11 };
		331	int sum = 0;
281		332
		333	for (i = 0; i < ecb_array_length (primes); i++)
		334	sum += primes [i];
		335
		336	=back
		337
		338

Diff Legend

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

Comparing libecb/ecb.pod (file contents): Revision 1.12 by sf-exg, Thu May 26 21:34:16 2011 UTC vs. Revision 1.14 by root, Thu May 26 23:23:08 2011 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.12 by sf-exg, Thu May 26 21:34:16 2011 UTC vs.
Revision 1.14 by root, Thu May 26 23:23:08 2011 UTC