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

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.17 by root, Thu May 26 23:55:58 2011 UTC vs.
Revision 1.47 by root, Tue May 29 16:51:24 2012 UTC

…		…
15	It mainly provides a number of wrappers around GCC built-ins, together	15	It mainly provides a number of wrappers around GCC built-ins, together
16	with replacement functions for other compilers. In addition to this,	16	with replacement functions for other compilers. In addition to this,
17	it provides a number of other lowlevel C utilities, such as endianness	17	it provides a number of other lowlevel C utilities, such as endianness
18	detection, byte swapping or bit rotations.	18	detection, byte swapping or bit rotations.
19		19
20	Or in other words, things that should be built-in into any standard C	20	Or in other words, things that should be built into any standard C system,
21	system, but isn't.	21	but aren't, implemented as efficient as possible with GCC, and still
		22	correct with other compilers.
22		23
23	More might come.	24	More might come.
24		25
25	=head2 ABOUT THE HEADER	26	=head2 ABOUT THE HEADER
26		27
…		…
53	only a generic name is used (C<expr>, C<cond>, C<value> and so on), then	54	only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
54	the corresponding function relies on C to implement the correct types, and	55	the corresponding function relies on C to implement the correct types, and
55	is usually implemented as a macro. Specifically, a "bool" in this manual	56	is usually implemented as a macro. Specifically, a "bool" in this manual
56	refers to any kind of boolean value, not a specific type.	57	refers to any kind of boolean value, not a specific type.
57		58
		59	=head2 TYPES / TYPE SUPPORT
		60
		61	ecb.h makes sure that the following types are defined (in the expected way):
		62
		63	int8_t uint8_t int16_t uint16_t
		64	int32_t uint32_t int64_t uint64_t
		65	intptr_t uintptr_t ptrdiff_t
		66
		67	The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
		68	platform (currently C<4> or C<8>) and can be used in preprocessor
		69	expressions.
		70
		71	=head2 LANGUAGE/COMPILER VERSIONS
		72
		73	All the following symbols expand to an expression that can be tested in
		74	preprocessor instructions as well as treated as a boolean (use C<!!> to
		75	ensure it's either C<0> or C<1> if you need that).
		76
		77	=over 4
		78
		79	=item ECB_C
		80
		81	True if the implementation defines the C<__STDC__> macro to a true value,
		82	which is typically true for both C and C++ compilers.
		83
		84	=item ECB_C99
		85
		86	True if the implementation claims to be compliant to C99 (ISO/IEC
		87	9899:1999) or any later version.
		88
		89	Note that later versions (ECB_C11) remove core features again (for
		90	example, variable length arrays).
		91
		92	=item ECB_C11
		93
		94	True if the implementation claims to be compliant to C11 (ISO/IEC
		95	9899:2011) or any later version.
		96
		97	=item ECB_CPP
		98
		99	True if the implementation defines the C<__cplusplus__> macro to a true
		100	value, which is typically true for C++ compilers.
		101
		102	=item ECB_CPP98
		103
		104	True if the implementation claims to be compliant to ISO/IEC 14882:1998
		105	(the first C++ ISO standard) or any later version. Typically true for all
		106	C++ compilers.
		107
		108	=item ECB_CPP11
		109
		110	True if the implementation claims to be compliant to ISO/IEC 14882:2011
		111	(C++11) or any later version.
		112
		113	=item ECB_GCC_VERSION(major,minor)
		114
		115	Expands to a true value (suitable for testing in by the preprocessor)
		116	if the compiler used is GNU C and the version is the given version, or
		117	higher.
		118
		119	This macro tries to return false on compilers that claim to be GCC
		120	compatible but aren't.
		121
		122	=back
		123
58	=head2 GCC ATTRIBUTES	124	=head2 GCC ATTRIBUTES
59		125
60	blabla where to put, what others	126	A major part of libecb deals with GCC attributes. These are additional
		127	attributes that you can assign to functions, variables and sometimes even
		128	types - much like C<const> or C<volatile> in C.
		129
		130	While GCC allows declarations to show up in many surprising places,
		131	but not in many expected places, the safest way is to put attribute
		132	declarations before the whole declaration:
		133
		134	ecb_const int mysqrt (int a);
		135	ecb_unused int i;
		136
		137	For variables, it is often nicer to put the attribute after the name, and
		138	avoid multiple declarations using commas:
		139
		140	int i ecb_unused;
61		141
62	=over 4	142	=over 4
63		143
64	=item ecb_attribute ((attrs...))	144	=item ecb_attribute ((attrs...))
65		145
…		…
86	#else	166	#else
87	return 0;	167	return 0;
88	#endif	168	#endif
89	}	169	}
90		170
		171	=item ecb_inline
		172
		173	This is not actually an attribute, but you use it like one. It expands
		174	either to C<static inline> or to just C<static>, if inline isn't
		175	supported. It should be used to declare functions that should be inlined,
		176	for code size or speed reasons.
		177
		178	Example: inline this function, it surely will reduce codesize.
		179
		180	ecb_inline int
		181	negmul (int a, int b)
		182	{
		183	return - (a * b);
		184	}
		185
91	=item ecb_noinline	186	=item ecb_noinline
92		187
93	Prevent a function from being inlined - it might be optimised away, but	188	Prevent a function from being inlined - it might be optimised away, but
94	not inlined into other functions. This is useful if you know your function	189	not inlined into other functions. This is useful if you know your function
95	is rarely called and large enough for inlining not to be helpful.	190	is rarely called and large enough for inlining not to be helpful.
…		…
105	{	200	{
106	puts (errline);	201	puts (errline);
107	abort ();	202	abort ();
108	}	203	}
109		204
110	In this case, the compiler would probbaly be smart enough to decude it on	205	In this case, the compiler would probably be smart enough to deduce it on
111	it's own, so this is mainly useful for declarations.	206	its own, so this is mainly useful for declarations.
112		207
113	=item ecb_const	208	=item ecb_const
114		209
115	Declares that the function only depends on the values of it's arguments,	210	Declares that the function only depends on the values of its arguments,
116	much like a mathematical function. It specifically does not read or write	211	much like a mathematical function. It specifically does not read or write
117	any memory any arguments might point to, global variables, or call any	212	any memory any arguments might point to, global variables, or call any
118	non-const functions. It also must not have any side effects.	213	non-const functions. It also must not have any side effects.
119		214
120	Such a function can be optimised much more aggressively by the compiler -	215	Such a function can be optimised much more aggressively by the compiler -
121	for example, multiple calls with the same arguments can be optimised into	216	for example, multiple calls with the same arguments can be optimised into
122	a single call, which wouldn't be possible if the compiler would have to	217	a single call, which wouldn't be possible if the compiler would have to
123	expect any side effects.	218	expect any side effects.
124		219
125	It is best suited for functions in the sense of mathematical functions,	220	It is best suited for functions in the sense of mathematical functions,
126	such as a function return the square root of its input argument.	221	such as a function returning the square root of its input argument.
127		222
128	Not suited would be a function that calculates the hash of some memory	223	Not suited would be a function that calculates the hash of some memory
129	area you pass in, prints some messages or looks at a global variable to	224	area you pass in, prints some messages or looks at a global variable to
130	decide on rounding.	225	decide on rounding.
131		226
…		…
154	possible.	249	possible.
155		250
156	The compiler reacts by trying to place hot functions near to each other in	251	The compiler reacts by trying to place hot functions near to each other in
157	memory.	252	memory.
158		253
159	Whether a function is hot or not often depend son the whole program,	254	Whether a function is hot or not often depends on the whole program,
160	and less on the function itself. C<ecb_cold> is likely more useful in	255	and less on the function itself. C<ecb_cold> is likely more useful in
161	practise.	256	practise.
162		257
163	=item ecb_cold	258	=item ecb_cold
164		259
…		…
169		264
170	In addition to placing cold functions together (or at least away from hot	265	In addition to placing cold functions together (or at least away from hot
171	functions), this knowledge can be used in other ways, for example, the	266	functions), this knowledge can be used in other ways, for example, the
172	function will be optimised for size, as opposed to speed, and codepaths	267	function will be optimised for size, as opposed to speed, and codepaths
173	leading to calls to those functions can automatically be marked as if	268	leading to calls to those functions can automatically be marked as if
174	C<ecb_unlikel> had been used to reach them.	269	C<ecb_expect_false> had been used to reach them.
175		270
176	Good examples for such functions would be error reporting functions, or	271	Good examples for such functions would be error reporting functions, or
177	functions only called in exceptional or rare cases.	272	functions only called in exceptional or rare cases.
178		273
179	=item ecb_artificial	274	=item ecb_artificial
…		…
241		336
242	Evaluates C<expr> and returns it. In addition, it tells the compiler that	337	Evaluates C<expr> and returns it. In addition, it tells the compiler that
243	the C<expr> evaluates to C<value> a lot, which can be used for static	338	the C<expr> evaluates to C<value> a lot, which can be used for static
244	branch optimisations.	339	branch optimisations.
245		340
246	Usually, you want to use the more intuitive C<ecb_likely> and	341	Usually, you want to use the more intuitive C<ecb_expect_true> and
247	C<ecb_unlikely> functions instead.	342	C<ecb_expect_false> functions instead.
248		343
		344	=item bool ecb_expect_true (cond)
		345
249	=item bool ecb_likely (cond)	346	=item bool ecb_expect_false (cond)
250
251	=item bool ecb_unlikely (cond)
252		347
253	These two functions expect a expression that is true or false and return	348	These two functions expect a expression that is true or false and return
254	C<1> or C<0>, respectively, so when used in the condition of an C<if> or	349	C<1> or C<0>, respectively, so when used in the condition of an C<if> or
255	other conditional statement, it will not change the program:	350	other conditional statement, it will not change the program:
256		351
257	/* these two do the same thing */	352	/* these two do the same thing */
258	if (some_condition) ...;	353	if (some_condition) ...;
259	if (ecb_likely (some_condition)) ...;	354	if (ecb_expect_true (some_condition)) ...;
260		355
261	However, by using C<ecb_likely>, you tell the compiler that the condition	356	However, by using C<ecb_expect_true>, you tell the compiler that the
262	is likely to be true (and for C<ecb_unlikely>, that it is unlikely to be	357	condition is likely to be true (and for C<ecb_expect_false>, that it is
263	true).	358	unlikely to be true).
264		359
265	For example, when you check for a null pointer and expect this to be a	360	For example, when you check for a null pointer and expect this to be a
266	rare, exceptional, case, then use C<ecb_unlikely>:	361	rare, exceptional, case, then use C<ecb_expect_false>:
267		362
268	void my_free (void *ptr)	363	void my_free (void *ptr)
269	{	364	{
270	if (ecb_unlikely (ptr == 0))	365	if (ecb_expect_false (ptr == 0))
271	return;	366	return;
272	}	367	}
273		368
274	Consequent use of these functions to mark away exceptional cases or to	369	Consequent use of these functions to mark away exceptional cases or to
275	tell the compiler what the hot path through a function is can increase	370	tell the compiler what the hot path through a function is can increase
276	performance considerably.	371	performance considerably.
		372
		373	You might know these functions under the name C<likely> and C<unlikely>
		374	- while these are common aliases, we find that the expect name is easier
		375	to understand when quickly skimming code. If you wish, you can use
		376	C<ecb_likely> instead of C<ecb_expect_true> and C<ecb_unlikely> instead of
		377	C<ecb_expect_false> - these are simply aliases.
277		378
278	A very good example is in a function that reserves more space for some	379	A very good example is in a function that reserves more space for some
279	memory block (for example, inside an implementation of a string stream) -	380	memory block (for example, inside an implementation of a string stream) -
280	each time something is added, you have to check for a buffer overrun, but	381	each time something is added, you have to check for a buffer overrun, but
281	you expect that most checks will turn out to be false:	382	you expect that most checks will turn out to be false:
282		383
283	/* make sure we have "size" extra room in our buffer */	384	/* make sure we have "size" extra room in our buffer */
284	ecb_inline void	385	ecb_inline void
285	reserve (int size)	386	reserve (int size)
286	{	387	{
287	if (ecb_unlikely (current + size > end))	388	if (ecb_expect_false (current + size > end))
288	real_reserve_method (size); /* presumably noinline */	389	real_reserve_method (size); /* presumably noinline */
289	}	390	}
290		391
291	=item bool ecb_assume (cond)	392	=item bool ecb_assume (cond)
292		393
…		…
295		396
296	This can be used to teach the compiler about invariants or other	397	This can be used to teach the compiler about invariants or other
297	conditions that might improve code generation, but which are impossible to	398	conditions that might improve code generation, but which are impossible to
298	deduce form the code itself.	399	deduce form the code itself.
299		400
300	For example, the example reservation function from the C<ecb_unlikely>	401	For example, the example reservation function from the C<ecb_expect_false>
301	description could be written thus (only C<ecb_assume> was added):	402	description could be written thus (only C<ecb_assume> was added):
302		403
303	ecb_inline void	404	ecb_inline void
304	reserve (int size)	405	reserve (int size)
305	{	406	{
306	if (ecb_unlikely (current + size > end))	407	if (ecb_expect_false (current + size > end))
307	real_reserve_method (size); /* presumably noinline */	408	real_reserve_method (size); /* presumably noinline */
308		409
309	ecb_assume (current + size <= end);	410	ecb_assume (current + size <= end);
310	}	411	}
311		412
…		…
360	After processing the node, (part of) the next node might already be in	461	After processing the node, (part of) the next node might already be in
361	cache.	462	cache.
362		463
363	=back	464	=back
364		465
365	=head2 BIT FIDDLING / BITSTUFFS	466	=head2 BIT FIDDLING / BIT WIZARDRY
366		467
367	=over 4	468	=over 4
368		469
369	=item bool ecb_big_endian ()	470	=item bool ecb_big_endian ()
370		471
…		…
372		473
373	These two functions return true if the byte order is big endian	474	These two functions return true if the byte order is big endian
374	(most-significant byte first) or little endian (least-significant byte	475	(most-significant byte first) or little endian (least-significant byte
375	first) respectively.	476	first) respectively.
376		477
		478	On systems that are neither, their return values are unspecified.
		479
377	=item int ecb_ctz32 (uint32_t x)	480	=item int ecb_ctz32 (uint32_t x)
378		481
		482	=item int ecb_ctz64 (uint64_t x)
		483
379	Returns the index of the least significant bit set in C<x> (or	484	Returns the index of the least significant bit set in C<x> (or
380	equivalently the number of bits set to 0 before the least significant	485	equivalently the number of bits set to 0 before the least significant bit
381	bit set), starting from 0. If C<x> is 0 the result is undefined. A	486	set), starting from 0. If C<x> is 0 the result is undefined.
382	common use case is to compute the integer binary logarithm, i.e.,	487
383	floor(log2(n)). For example:	488	For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
		489
		490	For example:
384		491
385	ecb_ctz32 (3) = 0	492	ecb_ctz32 (3) = 0
386	ecb_ctz32 (6) = 1	493	ecb_ctz32 (6) = 1
387		494
		495	=item bool ecb_is_pot32 (uint32_t x)
		496
		497	=item bool ecb_is_pot64 (uint32_t x)
		498
		499	Return true iff C<x> is a power of two or C<x == 0>.
		500
		501	For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
		502
		503	=item int ecb_ld32 (uint32_t x)
		504
		505	=item int ecb_ld64 (uint64_t x)
		506
		507	Returns the index of the most significant bit set in C<x>, or the number
		508	of digits the number requires in binary (so that C<< 2**ld <= x <
		509	2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
		510	to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
		511	example to see how many bits a certain number requires to be encoded.
		512
		513	This function is similar to the "count leading zero bits" function, except
		514	that that one returns how many zero bits are "in front" of the number (in
		515	the given data type), while C<ecb_ld> returns how many bits the number
		516	itself requires.
		517
		518	For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
		519
388	=item int ecb_popcount32 (uint32_t x)	520	=item int ecb_popcount32 (uint32_t x)
389		521
		522	=item int ecb_popcount64 (uint64_t x)
		523
390	Returns the number of bits set to 1 in C<x>. For example:	524	Returns the number of bits set to 1 in C<x>.
		525
		526	For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
		527
		528	For example:
391		529
392	ecb_popcount32 (7) = 3	530	ecb_popcount32 (7) = 3
393	ecb_popcount32 (255) = 8	531	ecb_popcount32 (255) = 8
394		532
		533	=item uint8_t ecb_bitrev8 (uint8_t x)
		534
		535	=item uint16_t ecb_bitrev16 (uint16_t x)
		536
		537	=item uint32_t ecb_bitrev32 (uint32_t x)
		538
		539	Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
		540	and so on.
		541
		542	Example:
		543
		544	ecb_bitrev8 (0xa7) = 0xea
		545	ecb_bitrev32 (0xffcc4411) = 0x882233ff
		546
395	=item uint32_t ecb_bswap16 (uint32_t x)	547	=item uint32_t ecb_bswap16 (uint32_t x)
396		548
397	=item uint32_t ecb_bswap32 (uint32_t x)	549	=item uint32_t ecb_bswap32 (uint32_t x)
398		550
		551	=item uint64_t ecb_bswap64 (uint64_t x)
		552
399	These two functions return the value of the 16-bit (32-bit) variable	553	These functions return the value of the 16-bit (32-bit, 64-bit) value
400	C<x> after reversing the order of bytes.	554	C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
		555	C<ecb_bswap32>).
		556
		557	=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
		558
		559	=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
		560
		561	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
		562
		563	=item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
		564
		565	=item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
		566
		567	=item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
401		568
402	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	569	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
403		570
404	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	571	=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
405		572
406	These two functions return the value of C<x> after shifting all the bits	573	These two families of functions return the value of C<x> after rotating
407	by C<count> positions to the right or left respectively.	574	all the bits by C<count> positions to the right (C<ecb_rotr>) or left
		575	(C<ecb_rotl>).
		576
		577	Current GCC versions understand these functions and usually compile them
		578	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
		579	x86).
408		580
409	=back	581	=back
410		582
411	=head2 ARITHMETIC	583	=head2 ARITHMETIC
412		584
413	=over 4	585	=over 4
414		586
415	=item x = ecb_mod (m, n)	587	=item x = ecb_mod (m, n)
416		588
417	Returns the positive remainder of the modulo operation between C<m> and	589	Returns C<m> modulo C<n>, which is the same as the positive remainder
		590	of the division operation between C<m> and C<n>, using floored
418	C<n>. Unlike the C modulo operator C<%>, this function ensures that the	591	division. Unlike the C remainder operator C<%>, this function ensures that
419	return value is always positive).	592	the return value is always positive and that the two numbers I<m> and
		593	I<m' = m + i * n> result in the same value modulo I<n> - in other words,
		594	C<ecb_mod> implements the mathematical modulo operation, which is missing
		595	in the language.
420		596
421	C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be	597	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
422	negatable, that is, both C<m> and C<-m> must be representable in its	598	negatable, that is, both C<m> and C<-m> must be representable in its
423	type.	599	type (this typically excludes the minimum signed integer value, the same
		600	limitation as for C</> and C<%> in C).
		601
		602	Current GCC versions compile this into an efficient branchless sequence on
		603	almost all CPUs.
		604
		605	For example, when you want to rotate forward through the members of an
		606	array for increasing C<m> (which might be negative), then you should use
		607	C<ecb_mod>, as the C<%> operator might give either negative results, or
		608	change direction for negative values:
		609
		610	for (m = -100; m <= 100; ++m)
		611	int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
		612
		613	=item x = ecb_div_rd (val, div)
		614
		615	=item x = ecb_div_ru (val, div)
		616
		617	Returns C<val> divided by C<div> rounded down or up, respectively.
		618	C<val> and C<div> must have integer types and C<div> must be strictly
		619	positive. Note that these functions are implemented with macros in C
		620	and with function templates in C++.
424		621
425	=back	622	=back
426		623
427	=head2 UTILITY	624	=head2 UTILITY
428		625
429	=over 4	626	=over 4
430		627
431	=item element_count = ecb_array_length (name) [MACRO]	628	=item element_count = ecb_array_length (name)
432		629
433	Returns the number of elements in the array C<name>. For example:	630	Returns the number of elements in the array C<name>. For example:
434		631
435	int primes[] = { 2, 3, 5, 7, 11 };	632	int primes[] = { 2, 3, 5, 7, 11 };
436	int sum = 0;	633	int sum = 0;
…		…
438	for (i = 0; i < ecb_array_length (primes); i++)	635	for (i = 0; i < ecb_array_length (primes); i++)
439	sum += primes [i];	636	sum += primes [i];
440		637
441	=back	638	=back
442		639
		640	=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
443		641
		642	These symbols need to be defined before including F<ecb.h> the first time.
		643
		644	=over 4
		645
		646	=item ECB_NO_THRADS
		647
		648	If F<ecb.h> is never used from multiple threads, then this symbol can
		649	be defined, in which case memory fences (and similar constructs) are
		650	completely removed, leading to more efficient code and fewer dependencies.
		651
		652	Setting this symbol to a true value implies C<ECB_NO_SMP>.
		653
		654	=item ECB_NO_SMP
		655
		656	The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
		657	multiple threads, but never concurrently (e.g. if the system the program
		658	runs on has only a single CPU with a single core, no hyperthreading and so
		659	on), then this symbol can be defined, leading to more efficient code and
		660	fewer dependencies.
		661
		662	=back
		663
		664

Diff Legend

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

Comparing cvsroot/libecb/ecb.pod (file contents): Revision 1.17 by root, Thu May 26 23:55:58 2011 UTC vs. Revision 1.47 by root, Tue May 29 16:51:24 2012 UTC

Diff Legend

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.17 by root, Thu May 26 23:55:58 2011 UTC vs.
Revision 1.47 by root, Tue May 29 16:51:24 2012 UTC