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

Comparing libecb/ecb.pod (file contents):
Revision 1.25 by root, Tue May 31 21:52:31 2011 UTC vs.
Revision 1.49 by root, Thu Jun 28 14:50:01 2012 UTC

…		…
54	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
55	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
56	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
57	refers to any kind of boolean value, not a specific type.	57	refers to any kind of boolean value, not a specific type.
58		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
		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	For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
		72
		73	=head2 LANGUAGE/COMPILER VERSIONS
		74
		75	All the following symbols expand to an expression that can be tested in
		76	preprocessor instructions as well as treated as a boolean (use C<!!> to
		77	ensure it's either C<0> or C<1> if you need that).
		78
		79	=over 4
		80
		81	=item ECB_C
		82
		83	True if the implementation defines the C<__STDC__> macro to a true value,
		84	which is typically true for both C and C++ compilers.
		85
		86	=item ECB_C99
		87
		88	True if the implementation claims to be compliant to C99 (ISO/IEC
		89	9899:1999) or any later version.
		90
		91	Note that later versions (ECB_C11) remove core features again (for
		92	example, variable length arrays).
		93
		94	=item ECB_C11
		95
		96	True if the implementation claims to be compliant to C11 (ISO/IEC
		97	9899:2011) or any later version.
		98
		99	=item ECB_CPP
		100
		101	True if the implementation defines the C<__cplusplus__> macro to a true
		102	value, which is typically true for C++ compilers.
		103
		104	=item ECB_CPP11
		105
		106	True if the implementation claims to be compliant to ISO/IEC 14882:2011
		107	(C++11) or any later version.
		108
		109	=item ECB_GCC_VERSION(major,minor)
		110
		111	Expands to a true value (suitable for testing in by the preprocessor)
		112	if the compiler used is GNU C and the version is the given version, or
		113	higher.
		114
		115	This macro tries to return false on compilers that claim to be GCC
		116	compatible but aren't.
		117
		118	=back
		119
59	=head2 GCC ATTRIBUTES	120	=head2 GCC ATTRIBUTES
60		121
61	A major part of libecb deals with GCC attributes. These are additional	122	A major part of libecb deals with GCC attributes. These are additional
62	attributes that you cna assign to functions, variables and sometimes even	123	attributes that you can assign to functions, variables and sometimes even
63	types - much like C<const> or C<volatile> in C.	124	types - much like C<const> or C<volatile> in C.
64		125
65	While GCC allows declarations to show up in many surprising places,	126	While GCC allows declarations to show up in many surprising places,
66	but not in many expeted places, the safest way is to put attribute	127	but not in many expected places, the safest way is to put attribute
67	declarations before the whole declaration:	128	declarations before the whole declaration:
68		129
69	ecb_const int mysqrt (int a);	130	ecb_const int mysqrt (int a);
70	ecb_unused int i;	131	ecb_unused int i;
71		132
…		…
101	#else	162	#else
102	return 0;	163	return 0;
103	#endif	164	#endif
104	}	165	}
105		166
		167	=item ecb_inline
		168
		169	This is not actually an attribute, but you use it like one. It expands
		170	either to C<static inline> or to just C<static>, if inline isn't
		171	supported. It should be used to declare functions that should be inlined,
		172	for code size or speed reasons.
		173
		174	Example: inline this function, it surely will reduce codesize.
		175
		176	ecb_inline int
		177	negmul (int a, int b)
		178	{
		179	return - (a * b);
		180	}
		181
106	=item ecb_noinline	182	=item ecb_noinline
107		183
108	Prevent a function from being inlined - it might be optimised away, but	184	Prevent a function from being inlined - it might be optimised away, but
109	not inlined into other functions. This is useful if you know your function	185	not inlined into other functions. This is useful if you know your function
110	is rarely called and large enough for inlining not to be helpful.	186	is rarely called and large enough for inlining not to be helpful.
…		…
184		260
185	In addition to placing cold functions together (or at least away from hot	261	In addition to placing cold functions together (or at least away from hot
186	functions), this knowledge can be used in other ways, for example, the	262	functions), this knowledge can be used in other ways, for example, the
187	function will be optimised for size, as opposed to speed, and codepaths	263	function will be optimised for size, as opposed to speed, and codepaths
188	leading to calls to those functions can automatically be marked as if	264	leading to calls to those functions can automatically be marked as if
189	C<ecb_unlikely> had been used to reach them.	265	C<ecb_expect_false> had been used to reach them.
190		266
191	Good examples for such functions would be error reporting functions, or	267	Good examples for such functions would be error reporting functions, or
192	functions only called in exceptional or rare cases.	268	functions only called in exceptional or rare cases.
193		269
194	=item ecb_artificial	270	=item ecb_artificial
…		…
256		332
257	Evaluates C<expr> and returns it. In addition, it tells the compiler that	333	Evaluates C<expr> and returns it. In addition, it tells the compiler that
258	the C<expr> evaluates to C<value> a lot, which can be used for static	334	the C<expr> evaluates to C<value> a lot, which can be used for static
259	branch optimisations.	335	branch optimisations.
260		336
261	Usually, you want to use the more intuitive C<ecb_likely> and	337	Usually, you want to use the more intuitive C<ecb_expect_true> and
262	C<ecb_unlikely> functions instead.	338	C<ecb_expect_false> functions instead.
263		339
		340	=item bool ecb_expect_true (cond)
		341
264	=item bool ecb_likely (cond)	342	=item bool ecb_expect_false (cond)
265
266	=item bool ecb_unlikely (cond)
267		343
268	These two functions expect a expression that is true or false and return	344	These two functions expect a expression that is true or false and return
269	C<1> or C<0>, respectively, so when used in the condition of an C<if> or	345	C<1> or C<0>, respectively, so when used in the condition of an C<if> or
270	other conditional statement, it will not change the program:	346	other conditional statement, it will not change the program:
271		347
272	/* these two do the same thing */	348	/* these two do the same thing */
273	if (some_condition) ...;	349	if (some_condition) ...;
274	if (ecb_likely (some_condition)) ...;	350	if (ecb_expect_true (some_condition)) ...;
275		351
276	However, by using C<ecb_likely>, you tell the compiler that the condition	352	However, by using C<ecb_expect_true>, you tell the compiler that the
277	is likely to be true (and for C<ecb_unlikely>, that it is unlikely to be	353	condition is likely to be true (and for C<ecb_expect_false>, that it is
278	true).	354	unlikely to be true).
279		355
280	For example, when you check for a null pointer and expect this to be a	356	For example, when you check for a null pointer and expect this to be a
281	rare, exceptional, case, then use C<ecb_unlikely>:	357	rare, exceptional, case, then use C<ecb_expect_false>:
282		358
283	void my_free (void *ptr)	359	void my_free (void *ptr)
284	{	360	{
285	if (ecb_unlikely (ptr == 0))	361	if (ecb_expect_false (ptr == 0))
286	return;	362	return;
287	}	363	}
288		364
289	Consequent use of these functions to mark away exceptional cases or to	365	Consequent use of these functions to mark away exceptional cases or to
290	tell the compiler what the hot path through a function is can increase	366	tell the compiler what the hot path through a function is can increase
291	performance considerably.	367	performance considerably.
		368
		369	You might know these functions under the name C<likely> and C<unlikely>
		370	- while these are common aliases, we find that the expect name is easier
		371	to understand when quickly skimming code. If you wish, you can use
		372	C<ecb_likely> instead of C<ecb_expect_true> and C<ecb_unlikely> instead of
		373	C<ecb_expect_false> - these are simply aliases.
292		374
293	A very good example is in a function that reserves more space for some	375	A very good example is in a function that reserves more space for some
294	memory block (for example, inside an implementation of a string stream) -	376	memory block (for example, inside an implementation of a string stream) -
295	each time something is added, you have to check for a buffer overrun, but	377	each time something is added, you have to check for a buffer overrun, but
296	you expect that most checks will turn out to be false:	378	you expect that most checks will turn out to be false:
297		379
298	/* make sure we have "size" extra room in our buffer */	380	/* make sure we have "size" extra room in our buffer */
299	ecb_inline void	381	ecb_inline void
300	reserve (int size)	382	reserve (int size)
301	{	383	{
302	if (ecb_unlikely (current + size > end))	384	if (ecb_expect_false (current + size > end))
303	real_reserve_method (size); /* presumably noinline */	385	real_reserve_method (size); /* presumably noinline */
304	}	386	}
305		387
306	=item bool ecb_assume (cond)	388	=item bool ecb_assume (cond)
307		389
…		…
310		392
311	This can be used to teach the compiler about invariants or other	393	This can be used to teach the compiler about invariants or other
312	conditions that might improve code generation, but which are impossible to	394	conditions that might improve code generation, but which are impossible to
313	deduce form the code itself.	395	deduce form the code itself.
314		396
315	For example, the example reservation function from the C<ecb_unlikely>	397	For example, the example reservation function from the C<ecb_expect_false>
316	description could be written thus (only C<ecb_assume> was added):	398	description could be written thus (only C<ecb_assume> was added):
317		399
318	ecb_inline void	400	ecb_inline void
319	reserve (int size)	401	reserve (int size)
320	{	402	{
321	if (ecb_unlikely (current + size > end))	403	if (ecb_expect_false (current + size > end))
322	real_reserve_method (size); /* presumably noinline */	404	real_reserve_method (size); /* presumably noinline */
323		405
324	ecb_assume (current + size <= end);	406	ecb_assume (current + size <= end);
325	}	407	}
326		408
…		…
375	After processing the node, (part of) the next node might already be in	457	After processing the node, (part of) the next node might already be in
376	cache.	458	cache.
377		459
378	=back	460	=back
379		461
380	=head2 BIT FIDDLING / BITSTUFFS	462	=head2 BIT FIDDLING / BIT WIZARDRY
381		463
382	=over 4	464	=over 4
383		465
384	=item bool ecb_big_endian ()	466	=item bool ecb_big_endian ()
385		467
…		…
391		473
392	On systems that are neither, their return values are unspecified.	474	On systems that are neither, their return values are unspecified.
393		475
394	=item int ecb_ctz32 (uint32_t x)	476	=item int ecb_ctz32 (uint32_t x)
395		477
		478	=item int ecb_ctz64 (uint64_t x)
		479
396	Returns the index of the least significant bit set in C<x> (or	480	Returns the index of the least significant bit set in C<x> (or
397	equivalently the number of bits set to 0 before the least significant bit	481	equivalently the number of bits set to 0 before the least significant bit
398	set), starting from 0. If C<x> is 0 the result is undefined. A common use	482	set), starting from 0. If C<x> is 0 the result is undefined.
399	case is to compute the integer binary logarithm, i.e., C<floor (log2	483
		484	For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
		485
400	(n))>. For example:	486	For example:
401		487
402	ecb_ctz32 (3) = 0	488	ecb_ctz32 (3) = 0
403	ecb_ctz32 (6) = 1	489	ecb_ctz32 (6) = 1
404		490
		491	=item bool ecb_is_pot32 (uint32_t x)
		492
		493	=item bool ecb_is_pot64 (uint32_t x)
		494
		495	Return true iff C<x> is a power of two or C<x == 0>.
		496
		497	For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
		498
		499	=item int ecb_ld32 (uint32_t x)
		500
		501	=item int ecb_ld64 (uint64_t x)
		502
		503	Returns the index of the most significant bit set in C<x>, or the number
		504	of digits the number requires in binary (so that C<< 2**ld <= x <
		505	2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
		506	to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
		507	example to see how many bits a certain number requires to be encoded.
		508
		509	This function is similar to the "count leading zero bits" function, except
		510	that that one returns how many zero bits are "in front" of the number (in
		511	the given data type), while C<ecb_ld> returns how many bits the number
		512	itself requires.
		513
		514	For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
		515
405	=item int ecb_popcount32 (uint32_t x)	516	=item int ecb_popcount32 (uint32_t x)
406		517
		518	=item int ecb_popcount64 (uint64_t x)
		519
407	Returns the number of bits set to 1 in C<x>. For example:	520	Returns the number of bits set to 1 in C<x>.
		521
		522	For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
		523
		524	For example:
408		525
409	ecb_popcount32 (7) = 3	526	ecb_popcount32 (7) = 3
410	ecb_popcount32 (255) = 8	527	ecb_popcount32 (255) = 8
411		528
		529	=item uint8_t ecb_bitrev8 (uint8_t x)
		530
		531	=item uint16_t ecb_bitrev16 (uint16_t x)
		532
		533	=item uint32_t ecb_bitrev32 (uint32_t x)
		534
		535	Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
		536	and so on.
		537
		538	Example:
		539
		540	ecb_bitrev8 (0xa7) = 0xea
		541	ecb_bitrev32 (0xffcc4411) = 0x882233ff
		542
412	=item uint32_t ecb_bswap16 (uint32_t x)	543	=item uint32_t ecb_bswap16 (uint32_t x)
413		544
414	=item uint32_t ecb_bswap32 (uint32_t x)	545	=item uint32_t ecb_bswap32 (uint32_t x)
415		546
		547	=item uint64_t ecb_bswap64 (uint64_t x)
		548
416	These two functions return the value of the 16-bit (32-bit) value C<x>	549	These functions return the value of the 16-bit (32-bit, 64-bit) value
417	after reversing the order of bytes (0x11223344 becomes 0x44332211).	550	C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
		551	C<ecb_bswap32>).
		552
		553	=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
		554
		555	=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
		556
		557	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
		558
		559	=item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
		560
		561	=item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
		562
		563	=item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
418		564
419	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	565	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
420		566
421	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	567	=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
422		568
423	These two functions return the value of C<x> after rotating all the bits	569	These two families of functions return the value of C<x> after rotating
424	by C<count> positions to the right or left respectively.	570	all the bits by C<count> positions to the right (C<ecb_rotr>) or left
		571	(C<ecb_rotl>).
425		572
426	Current GCC versions understand these functions and usually compile them	573	Current GCC versions understand these functions and usually compile them
427	to "optimal" code (e.g. a single C<roll> on x86).	574	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
		575	x86).
428		576
429	=back	577	=back
430		578
431	=head2 ARITHMETIC	579	=head2 ARITHMETIC
432		580
…		…
442	C<ecb_mod> implements the mathematical modulo operation, which is missing	590	C<ecb_mod> implements the mathematical modulo operation, which is missing
443	in the language.	591	in the language.
444		592
445	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be	593	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
446	negatable, that is, both C<m> and C<-m> must be representable in its	594	negatable, that is, both C<m> and C<-m> must be representable in its
447	type (this typically includes the minimum signed integer value, the same	595	type (this typically excludes the minimum signed integer value, the same
448	limitation as for C</> and C<%> in C).	596	limitation as for C</> and C<%> in C).
449		597
450	Current GCC versions compile this into an efficient branchless sequence on	598	Current GCC versions compile this into an efficient branchless sequence on
451	many systems.	599	almost all CPUs.
452		600
453	For example, when you want to rotate forward through the members of an	601	For example, when you want to rotate forward through the members of an
454	array for increasing C<m> (which might be negative), then you should use	602	array for increasing C<m> (which might be negative), then you should use
455	C<ecb_mod>, as the C<%> operator might give either negative results, or	603	C<ecb_mod>, as the C<%> operator might give either negative results, or
456	change direction for negative values:	604	change direction for negative values:
457		605
458	for (m = -100; m <= 100; ++m)	606	for (m = -100; m <= 100; ++m)
459	int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];	607	int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
460		608
		609	=item x = ecb_div_rd (val, div)
		610
		611	=item x = ecb_div_ru (val, div)
		612
		613	Returns C<val> divided by C<div> rounded down or up, respectively.
		614	C<val> and C<div> must have integer types and C<div> must be strictly
		615	positive. Note that these functions are implemented with macros in C
		616	and with function templates in C++.
		617
461	=back	618	=back
462		619
463	=head2 UTILITY	620	=head2 UTILITY
464		621
465	=over 4	622	=over 4
…		…
474	for (i = 0; i < ecb_array_length (primes); i++)	631	for (i = 0; i < ecb_array_length (primes); i++)
475	sum += primes [i];	632	sum += primes [i];
476		633
477	=back	634	=back
478		635
		636	=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
479		637
		638	These symbols need to be defined before including F<ecb.h> the first time.
		639
		640	=over 4
		641
		642	=item ECB_NO_THRADS
		643
		644	If F<ecb.h> is never used from multiple threads, then this symbol can
		645	be defined, in which case memory fences (and similar constructs) are
		646	completely removed, leading to more efficient code and fewer dependencies.
		647
		648	Setting this symbol to a true value implies C<ECB_NO_SMP>.
		649
		650	=item ECB_NO_SMP
		651
		652	The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
		653	multiple threads, but never concurrently (e.g. if the system the program
		654	runs on has only a single CPU with a single core, no hyperthreading and so
		655	on), then this symbol can be defined, leading to more efficient code and
		656	fewer dependencies.
		657
		658	=back
		659
		660

Diff Legend

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

Comparing libecb/ecb.pod (file contents): Revision 1.25 by root, Tue May 31 21:52:31 2011 UTC vs. Revision 1.49 by root, Thu Jun 28 14:50:01 2012 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.25 by root, Tue May 31 21:52:31 2011 UTC vs.
Revision 1.49 by root, Thu Jun 28 14:50:01 2012 UTC