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

Comparing libecb/ecb.pod (file contents):
Revision 1.1 by root, Thu May 26 19:39:40 2011 UTC vs.
Revision 1.39 by root, Sat Dec 10 11:58:38 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(attrlist)	79	=item ecb_attribute ((attrs...))
7	=item ecb_noinline ecb_attribute ((noinline))
8	=item ecb_noreturn ecb_attribute ((noreturn))
9	=item ecb_unused ecb_attribute ((unused))
10	=item ecb_const ecb_attribute ((const))
11	=item ecb_pure ecb_attribute ((pure))
12	=item ecb_hot ecb_attribute ((hot)) /* 4.3 */
13	=item ecb_cold ecb_attribute ((cold)) /* 4.3 */
14		80
		81	A simple wrapper that expands to C<__attribute__((attrs))> on GCC, and to
		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	}
		120
		121	=item ecb_noinline
		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
		127	=item ecb_noreturn
		128
		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.
		142
		143	=item ecb_const
		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
		164	=item ecb_pure
		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
		180	=item ecb_hot
		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
		193	=item ecb_cold
		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
		209	=item ecb_artificial
		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
15	=back	236	=back
16		237
17	=head2 OPTIMISATION HINTS	238	=head2 OPTIMISATION HINTS
18		239
19	=over 4	240	=over 4
20		241
21	=item bool ecb_is_constant(expr)	242	=item bool ecb_is_constant(expr)
22		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
23	=item bool ecb_expect(expr,value)	270	=item bool ecb_expect (expr, value)
24		271
25	=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.
26		275
27	=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.
28		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
29	=item bool ecb_assume(cond)	327	=item bool ecb_assume (cond)
30		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
31	=item bool ecb_unreachable()	357	=item bool ecb_unreachable ()
32		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
33	=item bool ecb_prefetch(addr,rw,locality)	363	=item bool ecb_prefetch (addr, rw, locality)
34		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.
		398
35	=back	399	=back
36		400
37	=head2 BIT FIDDLING / BITSTUFFS	401	=head2 BIT FIDDLING / BIT WIZARDRY
38		402
		403	=over 4
		404
39	bool ecb_big_endian ();	405	=item bool ecb_big_endian ()
		406
40	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
41	int ecb_ctz32 (uint32_t x);	415	=item int ecb_ctz32 (uint32_t x)
		416
		417	=item int ecb_ctz64 (uint64_t x)
		418
		419	Returns the index of the least significant bit set in C<x> (or
		420	equivalently the number of bits set to 0 before the least significant bit
		421	set), starting from 0. If C<x> is 0 the result is undefined.
		422
		423	For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
		424
		425	For example:
		426
		427	ecb_ctz32 (3) = 0
		428	ecb_ctz32 (6) = 1
		429
		430	=item int ecb_ld32 (uint32_t x)
		431
		432	=item int ecb_ld64 (uint64_t x)
		433
		434	Returns the index of the most significant bit set in C<x>, or the number
		435	of digits the number requires in binary (so that C<< 2**ld <= x <
		436	2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
		437	to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
		438	example to see how many bits a certain number requires to be encoded.
		439
		440	This function is similar to the "count leading zero bits" function, except
		441	that that one returns how many zero bits are "in front" of the number (in
		442	the given data type), while C<ecb_ld> returns how many bits the number
		443	itself requires.
		444
		445	For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
		446
42	int ecb_popcount32 (uint32_t x);	447	=item int ecb_popcount32 (uint32_t x)
		448
		449	=item int ecb_popcount64 (uint64_t x)
		450
		451	Returns the number of bits set to 1 in C<x>.
		452
		453	For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
		454
		455	For example:
		456
		457	ecb_popcount32 (7) = 3
		458	ecb_popcount32 (255) = 8
		459
		460	=item uint8_t ecb_bitrev8 (uint8_t x)
		461
		462	=item uint16_t ecb_bitrev16 (uint16_t x)
		463
43	uint32_t ecb_bswap32 (uint32_t x);	464	=item uint32_t ecb_bitrev32 (uint32_t x)
		465
		466	Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
		467	and so on.
		468
		469	Example:
		470
		471	ecb_bitrev8 (0xa7) = 0xea
		472	ecb_bitrev32 (0xffcc4411) = 0x882233ff
		473
44	uint32_t ecb_bswap16 (uint32_t x);	474	=item uint32_t ecb_bswap16 (uint32_t x)
		475
		476	=item uint32_t ecb_bswap32 (uint32_t x)
		477
		478	=item uint64_t ecb_bswap64 (uint64_t x)
		479
		480	These functions return the value of the 16-bit (32-bit, 64-bit) value
		481	C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
		482	C<ecb_bswap32>).
		483
45	uint32_t ecb_rotr32 (uint32_t x, unsigned int count);	484	=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
		485
		486	=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
		487
46	uint32_t ecb_rotl32 (uint32_t x, unsigned int count);	488	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
		489
		490	=item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
		491
		492	=item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
		493
		494	=item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
		495
		496	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
		497
		498	=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
		499
		500	These two families of functions return the value of C<x> after rotating
		501	all the bits by C<count> positions to the right (C<ecb_rotr>) or left
		502	(C<ecb_rotl>).
		503
		504	Current GCC versions understand these functions and usually compile them
		505	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
		506	x86).
		507
		508	=back
47		509
48	=head2 ARITHMETIC	510	=head2 ARITHMETIC
49		511
		512	=over 4
		513
50	x = ecb_mod (m, n)	514	=item x = ecb_mod (m, n)
		515
		516	Returns C<m> modulo C<n>, which is the same as the positive remainder
		517	of the division operation between C<m> and C<n>, using floored
		518	division. Unlike the C remainder operator C<%>, this function ensures that
		519	the return value is always positive and that the two numbers I<m> and
		520	I<m' = m + i * n> result in the same value modulo I<n> - in other words,
		521	C<ecb_mod> implements the mathematical modulo operation, which is missing
		522	in the language.
		523
		524	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
		525	negatable, that is, both C<m> and C<-m> must be representable in its
		526	type (this typically excludes the minimum signed integer value, the same
		527	limitation as for C</> and C<%> in C).
		528
		529	Current GCC versions compile this into an efficient branchless sequence on
		530	almost all CPUs.
		531
		532	For example, when you want to rotate forward through the members of an
		533	array for increasing C<m> (which might be negative), then you should use
		534	C<ecb_mod>, as the C<%> operator might give either negative results, or
		535	change direction for negative values:
		536
		537	for (m = -100; m <= 100; ++m)
		538	int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
		539
		540	=item x = ecb_div_rd (val, div)
		541
		542	=item x = ecb_div_ru (val, div)
		543
		544	Returns C<val> divided by C<div> rounded down or up, respectively.
		545	C<val> and C<div> must have integer types and C<div> must be strictly
		546	positive. Note that these functions are implemented with macros in C
		547	and with function templates in C++.
		548
		549	=back
51		550
52	=head2 UTILITY	551	=head2 UTILITY
53		552
54	ecb_array_length (name)	553	=over 4
55		554
		555	=item element_count = ecb_array_length (name)
56		556
		557	Returns the number of elements in the array C<name>. For example:
		558
		559	int primes[] = { 2, 3, 5, 7, 11 };
		560	int sum = 0;
		561
		562	for (i = 0; i < ecb_array_length (primes); i++)
		563	sum += primes [i];
		564
		565	=back
		566
		567

Diff Legend

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

Comparing libecb/ecb.pod (file contents): Revision 1.1 by root, Thu May 26 19:39:40 2011 UTC vs. Revision 1.39 by root, Sat Dec 10 11:58:38 2011 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.1 by root, Thu May 26 19:39:40 2011 UTC vs.
Revision 1.39 by root, Sat Dec 10 11:58:38 2011 UTC