[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.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>
		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 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.
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
16	=over 4	59	=over 4
17		60
18	=item ecb_attribute ((attrs...))	61	=item ecb_attribute ((attrs...))
19		62
20	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
21	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);
22		70
23	=item ecb_unused	71	=item ecb_unused
24		72
25	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
26	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.
27	declare a variable but do not always use it:	75	declare a variable but do not always use it:
28		76
29	{	77	{
30	int var ecb_unused;	78	int var ecb_unused;
31		79
32	#ifdef SOMECONDITION	80	#ifdef SOMECONDITION
33	var = ...;	81	var = ...;
34	return var;	82	return var;
35	#else	83	#else
36	return 0;	84	return 0;
37	#endif	85	#endif
38	}	86	}
39		87
40	=item ecb_noinline	88	=item ecb_noinline
41		89
42	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
43	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
44	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.
45		93
46	=item ecb_noreturn	94	=item ecb_noreturn
47		95
66	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
67	constant, and false otherwise.	115	constant, and false otherwise.
68		116
69	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
70	random number, and you have a function that maps this to a range from	118	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:	119	0..n-1, then you could use this inline function in a header file:
72		120
73	ecb_inline uint32_t	121	ecb_inline uint32_t
74	rndm (uint32_t n)	122	rndm (uint32_t n)
75	{	123	{
76	return n * (uint32_t)rndm16 ()) >> 16;	124	return (n * (uint32_t)rndm16 ()) >> 16;
77	}	125	}
78		126
79	However, for powers of two, you could use a normal mask, but that is only	127	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	128	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 -	129	when the passed number is a constant and also a power of two (C<n & (n -
…		…
84	ecb_inline uint32_t	132	ecb_inline uint32_t
85	rndm (uint32_t n)	133	rndm (uint32_t n)
86	{	134	{
87	return is_constant (n) && !(n & (n - 1))	135	return is_constant (n) && !(n & (n - 1))
88	? rndm16 () & (num - 1)	136	? rndm16 () & (num - 1)
89	: (uint32_t)rndm16 ()) >> 16;	137	: (n * (uint32_t)rndm16 ()) >> 16;
90	}
91
92		138	}
93		139
94	=item bool ecb_expect(expr,value)	140	=item bool ecb_expect (expr, value)
95		141
		142	Evaluates C<expr> and returns it. In addition, it tells the compiler that
		143	the C<expr> evaluates to C<value> a lot, which can be used for static
		144	branch optimisations.
		145
		146	Usually, you want to use the more intuitive C<ecb_likely> and
		147	C<ecb_unlikely> functions instead.
		148
		149	=item bool ecb_likely (cond)
		150
96	=item bool ecb_unlikely(bool)	151	=item bool ecb_unlikely (cond)
97		152
98	=item bool ecb_likely(bool)	153	These two functions expect a expression that is true or false and return
		154	C<1> or C<0>, respectively, so when used in the condition of an C<if> or
		155	other conditional statement, it will not change the program:
99		156
		157	/* these two do the same thing */
		158	if (some_condition) ...;
		159	if (ecb_likely (some_condition)) ...;
		160
		161	However, by using C<ecb_likely>, you tell the compiler that the condition
		162	is likely to be true (and for C<ecb_unlikely>, that it is unlikely to be
		163	true).
		164
		165	For example, when you check for a null pointer and expect this to be a
		166	rare, exceptional, case, then use C<ecb_unlikely>:
		167
		168	void my_free (void *ptr)
		169	{
		170	if (ecb_unlikely (ptr == 0))
		171	return;
		172	}
		173
		174	Consequent use of these functions to mark away exceptional cases or to
		175	tell the compiler what the hot path through a function is can increase
		176	performance considerably.
		177
		178	A very good example is in a function that reserves more space for some
		179	memory block (for example, inside an implementation of a string stream) -
		180	each time something is added, you have to check for a buffer overrun, but
		181	you expect that most checks will turn out to be false:
		182
		183	/* make sure we have "size" extra room in our buffer */
		184	ecb_inline void
		185	reserve (int size)
		186	{
		187	if (ecb_unlikely (current + size > end))
		188	real_reserve_method (size); /* presumably noinline */
		189	}
		190
100	=item bool ecb_assume(cond)	191	=item bool ecb_assume (cond)
101		192
		193	Try to tell the compiler that some condition is true, even if it's not
		194	obvious.
		195
		196	This can be used to teach the compiler about invariants or other
		197	conditions that might improve code generation, but which are impossible to
		198	deduce form the code itself.
		199
		200	For example, the example reservation function from the C<ecb_unlikely>
		201	description could be written thus (only C<ecb_assume> was added):
		202
		203	ecb_inline void
		204	reserve (int size)
		205	{
		206	if (ecb_unlikely (current + size > end))
		207	real_reserve_method (size); /* presumably noinline */
		208
		209	ecb_assume (current + size <= end);
		210	}
		211
		212	If you then call this function twice, like this:
		213
		214	reserve (10);
		215	reserve (1);
		216
		217	Then the compiler I<might> be able to optimise out the second call
		218	completely, as it knows that C<< current + 1 > end >> is false and the
		219	call will never be executed.
		220
102	=item bool ecb_unreachable()	221	=item bool ecb_unreachable ()
103		222
		223	This function does nothing itself, except tell the compiler that it will
		224	never be executed. Apart from suppressing a warning in some cases, this
		225	function can be used to implement C<ecb_assume> or similar functions.
		226
104	=item bool ecb_prefetch(addr,rw,locality)	227	=item bool ecb_prefetch (addr, rw, locality)
		228
		229	Tells the compiler to try to prefetch memory at the given C<addr>ess
		230	for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
		231	C<0> means that there will only be one access later, C<3> means that
		232	the data will likely be accessed very often, and values in between mean
		233	something... in between. The memory pointed to by the address does not
		234	need to be accessible (it could be a null pointer for example), but C<rw>
		235	and C<locality> must be compile-time constants.
		236
		237	An obvious way to use this is to prefetch some data far away, in a big
		238	array you loop over. This prefetches memory some 128 array elements later,
		239	in the hope that it will be ready when the CPU arrives at that location.
		240
		241	int sum = 0;
		242
		243	for (i = 0; i < N; ++i)
		244	{
		245	sum += arr [i]
		246	ecb_prefetch (arr + i + 128, 0, 0);
		247	}
		248
		249	It's hard to predict how far to prefetch, and most CPUs that can prefetch
		250	are often good enough to predict this kind of behaviour themselves. It
		251	gets more interesting with linked lists, especially when you do some fair
		252	processing on each list element:
		253
		254	for (node *n = start; n; n = n->next)
		255	{
		256	ecb_prefetch (n->next, 0, 0);
		257	... do medium amount of work with *n
		258	}
		259
		260	After processing the node, (part of) the next node might already be in
		261	cache.
105		262
106	=back	263	=back
107		264
108	=head2 BIT FIDDLING / BITSTUFFS	265	=head2 BIT FIDDLING / BITSTUFFS
109		266
		267	=over 4
		268
110	=item bool ecb_big_endian ()	269	=item bool ecb_big_endian ()
111		270
112	=item bool ecb_little_endian ()	271	=item bool ecb_little_endian ()
113		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
114	=item int ecb_ctz32 (uint32_t x)	277	=item int ecb_ctz32 (uint32_t x)
115		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
116	=item int ecb_popcount32 (uint32_t x)	288	=item int ecb_popcount32 (uint32_t x)
117		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
118	=item uint32_t ecb_bswap32 (uint32_t x)	297	=item uint32_t ecb_bswap32 (uint32_t x)
119		298
120	=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.
121		301
122	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	302	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
123		303
124	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	304	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
125		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
126	=back	309	=back
127		310
128	=head2 ARITHMETIC	311	=head2 ARITHMETIC
129		312
130	=over 4	313	=over 4
131		314
132	=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 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.
133		324
134	=back	325	=back
135		326
136	=head2 UTILITY	327	=head2 UTILITY
137		328
138	=over 4	329	=over 4
139		330
140	=item ecb_array_length (name) [MACRO]	331	=item element_count = ecb_array_length (name) [MACRO]
141		332
142	=back	333	Returns the number of elements in the array C<name>. For example:
143		334
		335	int primes[] = { 2, 3, 5, 7, 11 };
		336	int sum = 0;
144		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.3 by root, Thu May 26 20:04:38 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.3 by root, Thu May 26 20:04:38 2011 UTC vs.
Revision 1.16 by sf-exg, Thu May 26 23:32:41 2011 UTC