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

Comparing libecb/ecb.pod (file contents):
Revision 1.3 by root, Thu May 26 20:04:38 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>
		28
		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.
11		54
12	=head2 GCC ATTRIBUTES	55	=head2 GCC ATTRIBUTES
13		56
14	blabla where to put, what others	57	blabla where to put, what others
15		58
37	#endif	80	#endif
38	}	81	}
39		82
40	=item ecb_noinline	83	=item ecb_noinline
41		84
42	Prevent a function from being inlined - it might be optimsied away, but	85	Prevent a function from being inlined - it might be optimised away, but
43	not inlined into other functions. This is useful if you know your function	86	not inlined into other functions. This is useful if you know your function
44	is rarely called and large enough for inlining not to be helpful.	87	is rarely called and large enough for inlining not to be helpful.
45		88
46	=item ecb_noreturn	89	=item ecb_noreturn
47		90
…		…
66	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
67	constant, and false otherwise.	110	constant, and false otherwise.
68		111
69	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
70	random number, and you have a function that maps this to a range from	113	random number, and you have a function that maps this to a range from
71	0..n-1, then you could use this inline fucntion in a header file:	114	0..n-1, then you could use this inline function in a header file:
72		115
73	ecb_inline uint32_t	116	ecb_inline uint32_t
74	rndm (uint32_t n)	117	rndm (uint32_t n)
75	{	118	{
76	return n * (uint32_t)rndm16 ()) >> 16;	119	return (n * (uint32_t)rndm16 ()) >> 16;
77	}	120	}
78		121
79	However, for powers of two, you could use a normal mask, but that is only	122	However, for powers of two, you could use a normal mask, but that is only
80	worth it if, at compile time, you can detect this case. This is the case	123	worth it if, at compile time, you can detect this case. This is the case
81	when the passed number is a constant and also a power of two (C<n & (n -	124	when the passed number is a constant and also a power of two (C<n & (n -
…		…
84	ecb_inline uint32_t	127	ecb_inline uint32_t
85	rndm (uint32_t n)	128	rndm (uint32_t n)
86	{	129	{
87	return is_constant (n) && !(n & (n - 1))	130	return is_constant (n) && !(n & (n - 1))
88	? rndm16 () & (num - 1)	131	? rndm16 () & (num - 1)
89	: (uint32_t)rndm16 ()) >> 16;	132	: (n * (uint32_t)rndm16 ()) >> 16;
90	}
91
92		133	}
93		134
94	=item bool ecb_expect(expr,value)	135	=item bool ecb_expect (expr, value)
95		136
		137	Evaluates C<expr> and returns it. In addition, it tells the compiler that
		138	the C<expr> evaluates to C<value> a lot, which can be used for static
		139	branch optimisations.
		140
		141	Usually, you want to use the more intuitive C<ecb_likely> and
		142	C<ecb_unlikely> functions instead.
		143
		144	=item bool ecb_likely (bool)
		145
96	=item bool ecb_unlikely(bool)	146	=item bool ecb_unlikely (bool)
97		147
98	=item bool ecb_likely(bool)	148	These two functions expect a expression that is true or false and return
		149	C<1> or C<0>, respectively, so when used in the condition of an C<if> or
		150	other conditional statement, it will not change the program:
99		151
		152	/* these two do the same thing */
		153	if (some_condition) ...;
		154	if (ecb_likely (some_condition)) ...;
		155
		156	However, by using C<ecb_likely>, you tell the compiler that the condition
		157	is likely to be true (and for C<ecb_unlikely>, that it is unlikely to be
		158	true).
		159
		160	For example, when you check for a null pointer and expect this to be a
		161	rare, exceptional, case, then use C<ecb_unlikely>:
		162
		163	void my_free (void *ptr)
		164	{
		165	if (ecb_unlikely (ptr == 0))
		166	return;
		167	}
		168
		169	Consequent use of these functions to mark away exceptional cases or to
		170	tell the compiler what the hot path through a function is can increase
		171	performance considerably.
		172
		173	A very good example is in a function that reserves more space for some
		174	memory block (for example, inside an implementation of a string stream) -
		175	each time something is added, you have to check for a buffer overrun, but
		176	you expect that most checks will turn out to be false:
		177
		178	/* make sure we have "size" extra room in our buffer */
		179	ecb_inline void
		180	reserve (int size)
		181	{
		182	if (ecb_unlikely (current + size > end))
		183	real_reserve_method (size); /* presumably noinline */
		184	}
		185
100	=item bool ecb_assume(cond)	186	=item bool ecb_assume (cond)
101		187
		188	Try to tell the compiler that some condition is true, even if it's not
		189	obvious.
		190
		191	This can be used to teach the compiler about invariants or other
		192	conditions that might improve code generation, but which are impossible to
		193	deduce form the code itself.
		194
		195	For example, the example reservation function from the C<ecb_unlikely>
		196	description could be written thus (only C<ecb_assume> was added):
		197
		198	ecb_inline void
		199	reserve (int size)
		200	{
		201	if (ecb_unlikely (current + size > end))
		202	real_reserve_method (size); /* presumably noinline */
		203
		204	ecb_assume (current + size <= end);
		205	}
		206
		207	If you then call this function twice, like this:
		208
		209	reserve (10);
		210	reserve (1);
		211
		212	Then the compiler I<might> be able to optimise out the second call
		213	completely, as it knows that C<< current + 1 > end >> is false and the
		214	call will never be executed.
		215
102	=item bool ecb_unreachable()	216	=item bool ecb_unreachable ()
103		217
		218	This function does nothing itself, except tell the compiler that it will
		219	never be executed. Apart from suppressing a warning in some cases, this
		220	function can be used to implement C<ecb_assume> or similar functions.
		221
104	=item bool ecb_prefetch(addr,rw,locality)	222	=item bool ecb_prefetch (addr, rw, locality)
		223
		224	Tells the compiler to try to prefetch memory at the given C<addr>ess
		225	for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
		226	C<0> means that there will only be one access later, C<3> means that
		227	the data will likely be accessed very often, and values in between mean
		228	something... in between. The memory pointed to by the address does not
		229	need to be accessible (it could be a null pointer for example), but C<rw>
		230	and C<locality> must be compile-time constants.
		231
		232	An obvious way to use this is to prefetch some data far away, in a big
		233	array you loop over. This prefetches memory some 128 array elements later,
		234	in the hope that it will be ready when the CPU arrives at that location.
		235
		236	int sum = 0;
		237
		238	for (i = 0; i < N; ++i)
		239	{
		240	sum += arr [i]
		241	ecb_prefetch (arr + i + 128, 0, 0);
		242	}
		243
		244	It's hard to predict how far to prefetch, and most CPUs that can prefetch
		245	are often good enough to predict this kind of behaviour themselves. It
		246	gets more interesting with linked lists, especially when you do some fair
		247	processing on each list element:
		248
		249	for (node *n = start; n; n = n->next)
		250	{
		251	ecb_prefetch (n->next, 0, 0);
		252	... do medium amount of work with *n
		253	}
		254
		255	After processing the node, (part of) the next node might already be in
		256	cache.
105		257
106	=back	258	=back
107		259
108	=head2 BIT FIDDLING / BITSTUFFS	260	=head2 BIT FIDDLING / BITSTUFFS
109		261
		262	=over 4
		263
110	=item bool ecb_big_endian ()	264	=item bool ecb_big_endian ()
111		265
112	=item bool ecb_little_endian ()	266	=item bool ecb_little_endian ()
113		267
		268	These two functions return true if the byte order is big endian
		269	(most-significant byte first) or little endian (least-significant byte
		270	first) respectively.
		271
114	=item int ecb_ctz32 (uint32_t x)	272	=item int ecb_ctz32 (uint32_t x)
115		273
		274	Returns the index of the least significant bit set in C<x> (or
		275	equivalently the number of bits set to 0 before the least significant
		276	bit set), starting from 0. If C<x> is 0 the result is undefined. A
		277	common use case is to compute the integer binary logarithm, i.e.,
		278	floor(log2(n)). For example:
		279
		280	ecb_ctz32(3) = 0
		281	ecb_ctz32(6) = 1
		282
116	=item int ecb_popcount32 (uint32_t x)	283	=item int ecb_popcount32 (uint32_t x)
117		284
		285	Returns the number of bits set to 1 in C<x>. For example:
		286
		287	ecb_popcount32(7) = 3
		288	ecb_popcount32(255) = 8
		289
		290	=item uint32_t ecb_bswap16 (uint32_t x)
		291
118	=item uint32_t ecb_bswap32 (uint32_t x)	292	=item uint32_t ecb_bswap32 (uint32_t x)
119		293
120	=item uint32_t ecb_bswap16 (uint32_t x)	294	These two functions return the value of the 16-bit (32-bit) variable
		295	C<x> after reversing the order of bytes.
121		296
122	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	297	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
123		298
124	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	299	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
125		300
		301	These two functions return the value of C<x> after shifting all the bits
		302	by C<count> positions to the right or left respectively.
		303
126	=back	304	=back
127		305
128	=head2 ARITHMETIC	306	=head2 ARITHMETIC
129		307
130	=over 4	308	=over 4
131		309
132	=item x = ecb_mod (m, n) [MACRO]	310	=item x = ecb_mod (m, n)
		311
		312	Returns the positive remainder of the modulo operation between C<m> and
		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.
133		319
134	=back	320	=back
135		321
136	=head2 UTILITY	322	=head2 UTILITY
137		323
138	=over 4	324	=over 4
139		325
140	=item ecb_array_length (name) [MACRO]	326	=item element_count = ecb_array_length (name) [MACRO]
141		327
142	=back	328	Returns the number of elements in the array C<name>. For example:
143		329
		330	int primes[] = { 2, 3, 5, 7, 11 };
		331	int sum = 0;
144		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.3 by root, Thu May 26 20:04:38 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.3 by root, Thu May 26 20:04:38 2011 UTC vs.
Revision 1.14 by root, Thu May 26 23:23:08 2011 UTC