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

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.7 by root, Thu May 26 20:49:40 2011 UTC vs.
Revision 1.15 by root, Thu May 26 23:26:29 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
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 optimsied 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
46	is rarely called and large enough for inlining not to be helpful.	92	is rarely called and large enough for inlining not to be helpful.
47		93
48	=item ecb_noreturn	94	=item ecb_noreturn
49		95
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)	149	=item bool ecb_likely (cond)
104		150
105	=item bool ecb_unlikely (bool)	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
111	/* these two do the same thing */	157	/* these two do the same thing */
112	if (some_condition) ...;	158	if (some_condition) ...;
113	if (ecb_likely (some_condition)) ...;	159	if (ecb_likely (some_condition)) ...;
114		160
115	However, by using C<ecb_likely>, you tell the compiler that the condition	161	However, by using C<ecb_likely>, you tell the compiler that the condition
116	is likely to be true (and for C<ecb_unlikel>, that it is unlikely to be	162	is likely to be true (and for C<ecb_unlikely>, that it is unlikely to be
117	true).	163	true).
118		164
119	For example, when you check for a 0-ptr and expect this to be a rare,	165	For example, when you check for a null pointer and expect this to be a
120	exceptional, case, then use C<ecb_unlikely>:	166	rare, exceptional, case, then use C<ecb_unlikely>:
121		167
122	void my_free (void *ptr)	168	void my_free (void *ptr)
123	{	169	{
124	if (ecb_unlikely (ptr == 0))	170	if (ecb_unlikely (ptr == 0))
125	return;	171	return;
…		…
129	tell the compiler what the hot path through a function is can increase	175	tell the compiler what the hot path through a function is can increase
130	performance considerably.	176	performance considerably.
131		177
132	A very good example is in a function that reserves more space for some	178	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) -	179	memory block (for example, inside an implementation of a string stream) -
134	eahc time something is added, you have to check for a buffer overrun, but	180	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:	181	you expect that most checks will turn out to be false:
136		182
137	/* make sure we have "size" extra room in our buffer */	183	/* make sure we have "size" extra room in our buffer */
138	ecb_inline void	184	ecb_inline void
139	reserve (int size)	185	reserve (int size)
…		…
173	call will never be executed.	219	call will never be executed.
174		220
175	=item bool ecb_unreachable ()	221	=item bool ecb_unreachable ()
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 supressing 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)	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
187	something... in between. The memory pointed to by the address does not	233	something... in between. The memory pointed to by the address does not
188	need to be accessible (it could be a null pointer for example), but C<rw>	234	need to be accessible (it could be a null pointer for example), but C<rw>
189	and C<locality> must be compile-time constants.	235	and C<locality> must be compile-time constants.
190		236
191	An obvious way to use this is to prefetch some data far away, in a big	237	An obvious way to use this is to prefetch some data far away, in a big
192	array you loop over. This prefethces memory some 128 array elements later,	238	array you loop over. This prefetches memory some 128 array elements later,
193	in the hope that it will be ready when the CPU arrives at that location.	239	in the hope that it will be ready when the CPU arrives at that location.
194		240
195	int sum = 0;	241	int sum = 0;
196		242
197	for (i = 0; i < N; ++i)	243	for (i = 0; i < N; ++i)
…		…
222		268
223	=item bool ecb_big_endian ()	269	=item bool ecb_big_endian ()
224		270
225	=item bool ecb_little_endian ()	271	=item bool ecb_little_endian ()
226		272
		273	These two functions return true if the byte order is big endian
		274	(most-significant byte first) or little endian (least-significant byte
		275	first) respectively.
		276
227	=item int ecb_ctz32 (uint32_t x)	277	=item int ecb_ctz32 (uint32_t x)
228		278
		279	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
		281	bit set), starting from 0. If C<x> is 0 the result is undefined. A
		282	common use case is to compute the integer binary logarithm, i.e.,
		283	floor(log2(n)). For example:
		284
		285	ecb_ctz32 (3) = 0
		286	ecb_ctz32 (6) = 1
		287
229	=item int ecb_popcount32 (uint32_t x)	288	=item int ecb_popcount32 (uint32_t x)
230		289
		290	Returns the number of bits set to 1 in C<x>. For example:
		291
		292	ecb_popcount32 (7) = 3
		293	ecb_popcount32 (255) = 8
		294
		295	=item uint32_t ecb_bswap16 (uint32_t x)
		296
231	=item uint32_t ecb_bswap32 (uint32_t x)	297	=item uint32_t ecb_bswap32 (uint32_t x)
232		298
233	=item uint32_t ecb_bswap16 (uint32_t x)	299	These two functions return the value of the 16-bit (32-bit) variable
		300	C<x> after reversing the order of bytes.
234		301
235	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	302	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
236		303
237	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	304	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
238		305
		306	These two functions return the value of C<x> after shifting all the bits
		307	by C<count> positions to the right or left respectively.
		308
239	=back	309	=back
240		310
241	=head2 ARITHMETIC	311	=head2 ARITHMETIC
242		312
243	=over 4	313	=over 4
244		314
245	=item x = ecb_mod (m, n) [MACRO]	315	=item x = ecb_mod (m, n)
		316
		317	Returns the positive remainder of the modulo operation between C<m> and
		318	C<n>. Unlike the C moduloe 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.
246		324
247	=back	325	=back
248		326
249	=head2 UTILITY	327	=head2 UTILITY
250		328
251	=over 4	329	=over 4
252		330
253	=item ecb_array_length (name) [MACRO]	331	=item element_count = ecb_array_length (name) [MACRO]
254		332
255	=back	333	Returns the number of elements in the array C<name>. For example:
256		334
		335	int primes[] = { 2, 3, 5, 7, 11 };
		336	int sum = 0;
257		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 cvsroot/libecb/ecb.pod (file contents): Revision 1.7 by root, Thu May 26 20:49:40 2011 UTC vs. Revision 1.15 by root, Thu May 26 23:26:29 2011 UTC

Diff Legend

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.7 by root, Thu May 26 20:49:40 2011 UTC vs.
Revision 1.15 by root, Thu May 26 23:26:29 2011 UTC