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

Comparing libecb/ecb.pod (file contents):
Revision 1.2 by root, Thu May 26 19:49:21 2011 UTC vs.
Revision 1.32 by sf-exg, Fri Jun 17 15:55:41 2011 UTC

		1	=head1 LIBECB - e-C-Builtins
		2
		3	=head2 ABOUT LIBECB
		4
		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	Or in other words, things that should be built into any standard C system,
		21	but aren't, implemented as efficient as possible with GCC, and still
		22	correct with other compilers.
		23
		24	More might come.
		25
		26	=head2 ABOUT THE HEADER
		27
		28	At the moment, all you have to do is copy F<ecb.h> somewhere where your
		29	compiler can find it and include it:
		30
		31	#include <ecb.h>
		32
		33	The header should work fine for both C and C++ compilation, and gives you
		34	all of F<inttypes.h> in addition to the ECB symbols.
		35
		36	There are currently no object files to link to - future versions might
		37	come with an (optional) object code library to link against, to reduce
		38	code size or gain access to additional features.
		39
		40	It also currently includes everything from F<inttypes.h>.
		41
		42	=head2 ABOUT THIS MANUAL / CONVENTIONS
		43
		44	This manual mainly describes each (public) function available after
		45	including the F<ecb.h> header. The header might define other symbols than
		46	these, but these are not part of the public API, and not supported in any
		47	way.
		48
		49	When the manual mentions a "function" then this could be defined either as
		50	as inline function, a macro, or an external symbol.
		51
		52	When functions use a concrete standard type, such as C<int> or
		53	C<uint32_t>, then the corresponding function works only with that type. If
		54	only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
		55	the corresponding function relies on C to implement the correct types, and
		56	is usually implemented as a macro. Specifically, a "bool" in this manual
		57	refers to any kind of boolean value, not a specific type.
1		58
2	=head2 GCC ATTRIBUTES	59	=head2 GCC ATTRIBUTES
3		60
		61	A major part of libecb deals with GCC attributes. These are additional
		62	attributes that you can assign to functions, variables and sometimes even
		63	types - much like C<const> or C<volatile> in C.
		64
		65	While GCC allows declarations to show up in many surprising places,
		66	but not in many expected places, the safest way is to put attribute
		67	declarations before the whole declaration:
		68
		69	ecb_const int mysqrt (int a);
		70	ecb_unused int i;
		71
		72	For variables, it is often nicer to put the attribute after the name, and
		73	avoid multiple declarations using commas:
		74
		75	int i ecb_unused;
		76
4	=over 4	77	=over 4
5		78
6	=item ecb_attribute ((attrs...))	79	=item ecb_attribute ((attrs...))
7		80
8	A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and	81	A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
9	to nothing on other compilers, so the effect is that only GCC sees these.	82	nothing on other compilers, so the effect is that only GCC sees these.
		83
		84	Example: use the C<deprecated> attribute on a function.
		85
		86	ecb_attribute((__deprecated__)) void
		87	do_not_use_me_anymore (void);
		88
		89	=item ecb_unused
		90
		91	Marks a function or a variable as "unused", which simply suppresses a
		92	warning by GCC when it detects it as unused. This is useful when you e.g.
		93	declare a variable but do not always use it:
		94
		95	{
		96	int var ecb_unused;
		97
		98	#ifdef SOMECONDITION
		99	var = ...;
		100	return var;
		101	#else
		102	return 0;
		103	#endif
		104	}
		105
		106	=item ecb_inline
		107
		108	This is not actually an attribute, but you use it like one. It expands
		109	either to C<static inline> or to just C<static>, if inline isn't
		110	supported. It should be used to declare functions that should be inlined,
		111	for code size or speed reasons.
		112
		113	Example: inline this function, it surely will reduce codesize.
		114
		115	ecb_inline int
		116	negmul (int a, int b)
		117	{
		118	return - (a * b);
		119	}
10		120
11	=item ecb_noinline	121	=item ecb_noinline
12		122
		123	Prevent a function from being inlined - it might be optimised away, but
		124	not inlined into other functions. This is useful if you know your function
		125	is rarely called and large enough for inlining not to be helpful.
		126
13	=item ecb_noreturn	127	=item ecb_noreturn
14		128
15	=item ecb_unused	129	Marks a function as "not returning, ever". Some typical functions that
		130	don't return are C<exit> or C<abort> (which really works hard to not
		131	return), and now you can make your own:
		132
		133	ecb_noreturn void
		134	my_abort (const char *errline)
		135	{
		136	puts (errline);
		137	abort ();
		138	}
		139
		140	In this case, the compiler would probably be smart enough to deduce it on
		141	its own, so this is mainly useful for declarations.
16		142
17	=item ecb_const	143	=item ecb_const
18		144
		145	Declares that the function only depends on the values of its arguments,
		146	much like a mathematical function. It specifically does not read or write
		147	any memory any arguments might point to, global variables, or call any
		148	non-const functions. It also must not have any side effects.
		149
		150	Such a function can be optimised much more aggressively by the compiler -
		151	for example, multiple calls with the same arguments can be optimised into
		152	a single call, which wouldn't be possible if the compiler would have to
		153	expect any side effects.
		154
		155	It is best suited for functions in the sense of mathematical functions,
		156	such as a function returning the square root of its input argument.
		157
		158	Not suited would be a function that calculates the hash of some memory
		159	area you pass in, prints some messages or looks at a global variable to
		160	decide on rounding.
		161
		162	See C<ecb_pure> for a slightly less restrictive class of functions.
		163
19	=item ecb_pure	164	=item ecb_pure
20		165
		166	Similar to C<ecb_const>, declares a function that has no side
		167	effects. Unlike C<ecb_const>, the function is allowed to examine global
		168	variables and any other memory areas (such as the ones passed to it via
		169	pointers).
		170
		171	While these functions cannot be optimised as aggressively as C<ecb_const>
		172	functions, they can still be optimised away in many occasions, and the
		173	compiler has more freedom in moving calls to them around.
		174
		175	Typical examples for such functions would be C<strlen> or C<memcmp>. A
		176	function that calculates the MD5 sum of some input and updates some MD5
		177	state passed as argument would I<NOT> be pure, however, as it would modify
		178	some memory area that is not the return value.
		179
21	=item ecb_hot	180	=item ecb_hot
22		181
		182	This declares a function as "hot" with regards to the cache - the function
		183	is used so often, that it is very beneficial to keep it in the cache if
		184	possible.
		185
		186	The compiler reacts by trying to place hot functions near to each other in
		187	memory.
		188
		189	Whether a function is hot or not often depends on the whole program,
		190	and less on the function itself. C<ecb_cold> is likely more useful in
		191	practise.
		192
23	=item ecb_cold	193	=item ecb_cold
24		194
		195	The opposite of C<ecb_hot> - declares a function as "cold" with regards to
		196	the cache, or in other words, this function is not called often, or not at
		197	speed-critical times, and keeping it in the cache might be a waste of said
		198	cache.
		199
		200	In addition to placing cold functions together (or at least away from hot
		201	functions), this knowledge can be used in other ways, for example, the
		202	function will be optimised for size, as opposed to speed, and codepaths
		203	leading to calls to those functions can automatically be marked as if
		204	C<ecb_expect_false> had been used to reach them.
		205
		206	Good examples for such functions would be error reporting functions, or
		207	functions only called in exceptional or rare cases.
		208
25	=item ecb_artificial	209	=item ecb_artificial
26		210
		211	Declares the function as "artificial", in this case meaning that this
		212	function is not really mean to be a function, but more like an accessor
		213	- many methods in C++ classes are mere accessor functions, and having a
		214	crash reported in such a method, or single-stepping through them, is not
		215	usually so helpful, especially when it's inlined to just a few instructions.
		216
		217	Marking them as artificial will instruct the debugger about just this,
		218	leading to happier debugging and thus happier lives.
		219
		220	Example: in some kind of smart-pointer class, mark the pointer accessor as
		221	artificial, so that the whole class acts more like a pointer and less like
		222	some C++ abstraction monster.
		223
		224	template<typename T>
		225	struct my_smart_ptr
		226	{
		227	T *value;
		228
		229	ecb_artificial
		230	operator T *()
		231	{
		232	return value;
		233	}
		234	};
		235
27	=back	236	=back
28		237
29	=head2 OPTIMISATION HINTS	238	=head2 OPTIMISATION HINTS
30		239
31	=over 4	240	=over 4
32		241
33	=item bool ecb_is_constant(expr)	242	=item bool ecb_is_constant(expr)
34		243
		244	Returns true iff the expression can be deduced to be a compile-time
		245	constant, and false otherwise.
		246
		247	For example, when you have a C<rndm16> function that returns a 16 bit
		248	random number, and you have a function that maps this to a range from
		249	0..n-1, then you could use this inline function in a header file:
		250
		251	ecb_inline uint32_t
		252	rndm (uint32_t n)
		253	{
		254	return (n * (uint32_t)rndm16 ()) >> 16;
		255	}
		256
		257	However, for powers of two, you could use a normal mask, but that is only
		258	worth it if, at compile time, you can detect this case. This is the case
		259	when the passed number is a constant and also a power of two (C<n & (n -
		260	1) == 0>):
		261
		262	ecb_inline uint32_t
		263	rndm (uint32_t n)
		264	{
		265	return is_constant (n) && !(n & (n - 1))
		266	? rndm16 () & (num - 1)
		267	: (n * (uint32_t)rndm16 ()) >> 16;
		268	}
		269
35	=item bool ecb_expect(expr,value)	270	=item bool ecb_expect (expr, value)
36		271
37	=item bool ecb_unlikely(bool)	272	Evaluates C<expr> and returns it. In addition, it tells the compiler that
		273	the C<expr> evaluates to C<value> a lot, which can be used for static
		274	branch optimisations.
38		275
39	=item bool ecb_likely(bool)	276	Usually, you want to use the more intuitive C<ecb_expect_true> and
		277	C<ecb_expect_false> functions instead.
40		278
		279	=item bool ecb_expect_true (cond)
		280
		281	=item bool ecb_expect_false (cond)
		282
		283	These two functions expect a expression that is true or false and return
		284	C<1> or C<0>, respectively, so when used in the condition of an C<if> or
		285	other conditional statement, it will not change the program:
		286
		287	/* these two do the same thing */
		288	if (some_condition) ...;
		289	if (ecb_expect_true (some_condition)) ...;
		290
		291	However, by using C<ecb_expect_true>, you tell the compiler that the
		292	condition is likely to be true (and for C<ecb_expect_false>, that it is
		293	unlikely to be true).
		294
		295	For example, when you check for a null pointer and expect this to be a
		296	rare, exceptional, case, then use C<ecb_expect_false>:
		297
		298	void my_free (void *ptr)
		299	{
		300	if (ecb_expect_false (ptr == 0))
		301	return;
		302	}
		303
		304	Consequent use of these functions to mark away exceptional cases or to
		305	tell the compiler what the hot path through a function is can increase
		306	performance considerably.
		307
		308	You might know these functions under the name C<likely> and C<unlikely>
		309	- while these are common aliases, we find that the expect name is easier
		310	to understand when quickly skimming code. If you wish, you can use
		311	C<ecb_likely> instead of C<ecb_expect_true> and C<ecb_unlikely> instead of
		312	C<ecb_expect_false> - these are simply aliases.
		313
		314	A very good example is in a function that reserves more space for some
		315	memory block (for example, inside an implementation of a string stream) -
		316	each time something is added, you have to check for a buffer overrun, but
		317	you expect that most checks will turn out to be false:
		318
		319	/* make sure we have "size" extra room in our buffer */
		320	ecb_inline void
		321	reserve (int size)
		322	{
		323	if (ecb_expect_false (current + size > end))
		324	real_reserve_method (size); /* presumably noinline */
		325	}
		326
41	=item bool ecb_assume(cond)	327	=item bool ecb_assume (cond)
42		328
		329	Try to tell the compiler that some condition is true, even if it's not
		330	obvious.
		331
		332	This can be used to teach the compiler about invariants or other
		333	conditions that might improve code generation, but which are impossible to
		334	deduce form the code itself.
		335
		336	For example, the example reservation function from the C<ecb_expect_false>
		337	description could be written thus (only C<ecb_assume> was added):
		338
		339	ecb_inline void
		340	reserve (int size)
		341	{
		342	if (ecb_expect_false (current + size > end))
		343	real_reserve_method (size); /* presumably noinline */
		344
		345	ecb_assume (current + size <= end);
		346	}
		347
		348	If you then call this function twice, like this:
		349
		350	reserve (10);
		351	reserve (1);
		352
		353	Then the compiler I<might> be able to optimise out the second call
		354	completely, as it knows that C<< current + 1 > end >> is false and the
		355	call will never be executed.
		356
43	=item bool ecb_unreachable()	357	=item bool ecb_unreachable ()
44		358
		359	This function does nothing itself, except tell the compiler that it will
		360	never be executed. Apart from suppressing a warning in some cases, this
		361	function can be used to implement C<ecb_assume> or similar functions.
		362
45	=item bool ecb_prefetch(addr,rw,locality)	363	=item bool ecb_prefetch (addr, rw, locality)
		364
		365	Tells the compiler to try to prefetch memory at the given C<addr>ess
		366	for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of
		367	C<0> means that there will only be one access later, C<3> means that
		368	the data will likely be accessed very often, and values in between mean
		369	something... in between. The memory pointed to by the address does not
		370	need to be accessible (it could be a null pointer for example), but C<rw>
		371	and C<locality> must be compile-time constants.
		372
		373	An obvious way to use this is to prefetch some data far away, in a big
		374	array you loop over. This prefetches memory some 128 array elements later,
		375	in the hope that it will be ready when the CPU arrives at that location.
		376
		377	int sum = 0;
		378
		379	for (i = 0; i < N; ++i)
		380	{
		381	sum += arr [i]
		382	ecb_prefetch (arr + i + 128, 0, 0);
		383	}
		384
		385	It's hard to predict how far to prefetch, and most CPUs that can prefetch
		386	are often good enough to predict this kind of behaviour themselves. It
		387	gets more interesting with linked lists, especially when you do some fair
		388	processing on each list element:
		389
		390	for (node *n = start; n; n = n->next)
		391	{
		392	ecb_prefetch (n->next, 0, 0);
		393	... do medium amount of work with *n
		394	}
		395
		396	After processing the node, (part of) the next node might already be in
		397	cache.
46		398
47	=back	399	=back
48		400
49	=head2 BIT FIDDLING / BITSTUFFS	401	=head2 BIT FIDDLING / BITSTUFFS
50		402
		403	=over 4
		404
51	bool ecb_big_endian ();	405	=item bool ecb_big_endian ()
		406
52	bool ecb_little_endian ();	407	=item bool ecb_little_endian ()
		408
		409	These two functions return true if the byte order is big endian
		410	(most-significant byte first) or little endian (least-significant byte
		411	first) respectively.
		412
		413	On systems that are neither, their return values are unspecified.
		414
53	int ecb_ctz32 (uint32_t x);	415	=item int ecb_ctz32 (uint32_t x)
		416
		417	Returns the index of the least significant bit set in C<x> (or
		418	equivalently the number of bits set to 0 before the least significant bit
		419	set), starting from 0. If C<x> is 0 the result is undefined. For example:
		420
		421	ecb_ctz32 (3) = 0
		422	ecb_ctz32 (6) = 1
		423
54	int ecb_popcount32 (uint32_t x);	424	=item int ecb_popcount32 (uint32_t x)
55	uint32_t ecb_bswap32 (uint32_t x);	425
		426	Returns the number of bits set to 1 in C<x>. For example:
		427
		428	ecb_popcount32 (7) = 3
		429	ecb_popcount32 (255) = 8
		430
56	uint32_t ecb_bswap16 (uint32_t x);	431	=item uint32_t ecb_bswap16 (uint32_t x)
		432
		433	=item uint32_t ecb_bswap32 (uint32_t x)
		434
		435	These two functions return the value of the 16-bit (32-bit) value C<x>
		436	after reversing the order of bytes (0x11223344 becomes 0x44332211).
		437
57	uint32_t ecb_rotr32 (uint32_t x, unsigned int count);	438	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
		439
58	uint32_t ecb_rotl32 (uint32_t x, unsigned int count);	440	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
		441
		442	These two functions return the value of C<x> after rotating all the bits
		443	by C<count> positions to the right or left respectively.
		444
		445	Current GCC versions understand these functions and usually compile them
		446	to "optimal" code (e.g. a single C<roll> on x86).
		447
		448	=back
59		449
60	=head2 ARITHMETIC	450	=head2 ARITHMETIC
61		451
		452	=over 4
		453
62	x = ecb_mod (m, n)	454	=item x = ecb_mod (m, n)
		455
		456	Returns C<m> modulo C<n>, which is the same as the positive remainder
		457	of the division operation between C<m> and C<n>, using floored
		458	division. Unlike the C remainder operator C<%>, this function ensures that
		459	the return value is always positive and that the two numbers I<m> and
		460	I<m' = m + i * n> result in the same value modulo I<n> - in other words,
		461	C<ecb_mod> implements the mathematical modulo operation, which is missing
		462	in the language.
		463
		464	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
		465	negatable, that is, both C<m> and C<-m> must be representable in its
		466	type (this typically excludes the minimum signed integer value, the same
		467	limitation as for C</> and C<%> in C).
		468
		469	Current GCC versions compile this into an efficient branchless sequence on
		470	almost all CPUs.
		471
		472	For example, when you want to rotate forward through the members of an
		473	array for increasing C<m> (which might be negative), then you should use
		474	C<ecb_mod>, as the C<%> operator might give either negative results, or
		475	change direction for negative values:
		476
		477	for (m = -100; m <= 100; ++m)
		478	int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
		479
		480	=back
63		481
64	=head2 UTILITY	482	=head2 UTILITY
65		483
66	ecb_array_length (name)	484	=over 4
67		485
		486	=item element_count = ecb_array_length (name)
68		487
		488	Returns the number of elements in the array C<name>. For example:
		489
		490	int primes[] = { 2, 3, 5, 7, 11 };
		491	int sum = 0;
		492
		493	for (i = 0; i < ecb_array_length (primes); i++)
		494	sum += primes [i];
		495
		496	=back
		497
		498

Diff Legend

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

Comparing libecb/ecb.pod (file contents): Revision 1.2 by root, Thu May 26 19:49:21 2011 UTC vs. Revision 1.32 by sf-exg, Fri Jun 17 15:55:41 2011 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.2 by root, Thu May 26 19:49:21 2011 UTC vs.
Revision 1.32 by sf-exg, Fri Jun 17 15:55:41 2011 UTC