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

Comparing libecb/ecb.pod (file contents):
Revision 1.18 by root, Fri May 27 00:01:28 2011 UTC vs.
Revision 1.49 by root, Thu Jun 28 14:50:01 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 aren'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
		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
58	=head2 GCC ATTRIBUTES	120	=head2 GCC ATTRIBUTES
59		121
60	blabla where to put, what others	122	A major part of libecb deals with GCC attributes. These are additional
		123	attributes that you can assign to functions, variables and sometimes even
		124	types - much like C<const> or C<volatile> in C.
		125
		126	While GCC allows declarations to show up in many surprising places,
		127	but not in many expected places, the safest way is to put attribute
		128	declarations before the whole declaration:
		129
		130	ecb_const int mysqrt (int a);
		131	ecb_unused int i;
		132
		133	For variables, it is often nicer to put the attribute after the name, and
		134	avoid multiple declarations using commas:
		135
		136	int i ecb_unused;
61		137
62	=over 4	138	=over 4
63		139
64	=item ecb_attribute ((attrs...))	140	=item ecb_attribute ((attrs...))
65		141
…		…
86	#else	162	#else
87	return 0;	163	return 0;
88	#endif	164	#endif
89	}	165	}
90		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
91	=item ecb_noinline	182	=item ecb_noinline
92		183
93	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
94	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
95	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.
…		…
105	{	196	{
106	puts (errline);	197	puts (errline);
107	abort ();	198	abort ();
108	}	199	}
109		200
110	In this case, the compiler would probbaly be smart enough to decude it on	201	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.	202	its own, so this is mainly useful for declarations.
112		203
113	=item ecb_const	204	=item ecb_const
114		205
115	Declares that the function only depends on the values of it's arguments,	206	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	207	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	208	any memory any arguments might point to, global variables, or call any
118	non-const functions. It also must not have any side effects.	209	non-const functions. It also must not have any side effects.
119		210
120	Such a function can be optimised much more aggressively by the compiler -	211	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	212	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	213	a single call, which wouldn't be possible if the compiler would have to
123	expect any side effects.	214	expect any side effects.
124		215
125	It is best suited for functions in the sense of mathematical functions,	216	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.	217	such as a function returning the square root of its input argument.
127		218
128	Not suited would be a function that calculates the hash of some memory	219	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	220	area you pass in, prints some messages or looks at a global variable to
130	decide on rounding.	221	decide on rounding.
131		222
…		…
154	possible.	245	possible.
155		246
156	The compiler reacts by trying to place hot functions near to each other in	247	The compiler reacts by trying to place hot functions near to each other in
157	memory.	248	memory.
158		249
159	Whether a function is hot or not often depend son the whole program,	250	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	251	and less on the function itself. C<ecb_cold> is likely more useful in
161	practise.	252	practise.
162		253
163	=item ecb_cold	254	=item ecb_cold
164		255
…		…
169		260
170	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
171	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
172	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
173	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
174	C<ecb_unlikel> had been used to reach them.	265	C<ecb_expect_false> had been used to reach them.
175		266
176	Good examples for such functions would be error reporting functions, or	267	Good examples for such functions would be error reporting functions, or
177	functions only called in exceptional or rare cases.	268	functions only called in exceptional or rare cases.
178		269
179	=item ecb_artificial	270	=item ecb_artificial
…		…
241		332
242	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
243	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
244	branch optimisations.	335	branch optimisations.
245		336
246	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
247	C<ecb_unlikely> functions instead.	338	C<ecb_expect_false> functions instead.
248		339
		340	=item bool ecb_expect_true (cond)
		341
249	=item bool ecb_likely (cond)	342	=item bool ecb_expect_false (cond)
250
251	=item bool ecb_unlikely (cond)
252		343
253	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
254	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
255	other conditional statement, it will not change the program:	346	other conditional statement, it will not change the program:
256		347
257	/* these two do the same thing */	348	/* these two do the same thing */
258	if (some_condition) ...;	349	if (some_condition) ...;
259	if (ecb_likely (some_condition)) ...;	350	if (ecb_expect_true (some_condition)) ...;
260		351
261	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
262	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
263	true).	354	unlikely to be true).
264		355
265	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
266	rare, exceptional, case, then use C<ecb_unlikely>:	357	rare, exceptional, case, then use C<ecb_expect_false>:
267		358
268	void my_free (void *ptr)	359	void my_free (void *ptr)
269	{	360	{
270	if (ecb_unlikely (ptr == 0))	361	if (ecb_expect_false (ptr == 0))
271	return;	362	return;
272	}	363	}
273		364
274	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
275	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
276	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.
277		374
278	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
279	memory block (for example, inside an implementation of a string stream) -	376	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	377	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:	378	you expect that most checks will turn out to be false:
282		379
283	/* make sure we have "size" extra room in our buffer */	380	/* make sure we have "size" extra room in our buffer */
284	ecb_inline void	381	ecb_inline void
285	reserve (int size)	382	reserve (int size)
286	{	383	{
287	if (ecb_unlikely (current + size > end))	384	if (ecb_expect_false (current + size > end))
288	real_reserve_method (size); /* presumably noinline */	385	real_reserve_method (size); /* presumably noinline */
289	}	386	}
290		387
291	=item bool ecb_assume (cond)	388	=item bool ecb_assume (cond)
292		389
…		…
295		392
296	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
297	conditions that might improve code generation, but which are impossible to	394	conditions that might improve code generation, but which are impossible to
298	deduce form the code itself.	395	deduce form the code itself.
299		396
300	For example, the example reservation function from the C<ecb_unlikely>	397	For example, the example reservation function from the C<ecb_expect_false>
301	description could be written thus (only C<ecb_assume> was added):	398	description could be written thus (only C<ecb_assume> was added):
302		399
303	ecb_inline void	400	ecb_inline void
304	reserve (int size)	401	reserve (int size)
305	{	402	{
306	if (ecb_unlikely (current + size > end))	403	if (ecb_expect_false (current + size > end))
307	real_reserve_method (size); /* presumably noinline */	404	real_reserve_method (size); /* presumably noinline */
308		405
309	ecb_assume (current + size <= end);	406	ecb_assume (current + size <= end);
310	}	407	}
311		408
…		…
360	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
361	cache.	458	cache.
362		459
363	=back	460	=back
364		461
365	=head2 BIT FIDDLING / BITSTUFFS	462	=head2 BIT FIDDLING / BIT WIZARDRY
366		463
367	=over 4	464	=over 4
368		465
369	=item bool ecb_big_endian ()	466	=item bool ecb_big_endian ()
370		467
…		…
372		469
373	These two functions return true if the byte order is big endian	470	These two functions return true if the byte order is big endian
374	(most-significant byte first) or little endian (least-significant byte	471	(most-significant byte first) or little endian (least-significant byte
375	first) respectively.	472	first) respectively.
376		473
		474	On systems that are neither, their return values are unspecified.
		475
377	=item int ecb_ctz32 (uint32_t x)	476	=item int ecb_ctz32 (uint32_t x)
378		477
		478	=item int ecb_ctz64 (uint64_t x)
		479
379	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
380	equivalently the number of bits set to 0 before the least significant	481	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	482	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.,	483
383	floor(log2(n)). For example:	484	For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
		485
		486	For example:
384		487
385	ecb_ctz32 (3) = 0	488	ecb_ctz32 (3) = 0
386	ecb_ctz32 (6) = 1	489	ecb_ctz32 (6) = 1
387		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
388	=item int ecb_popcount32 (uint32_t x)	516	=item int ecb_popcount32 (uint32_t x)
389		517
		518	=item int ecb_popcount64 (uint64_t x)
		519
390	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:
391		525
392	ecb_popcount32 (7) = 3	526	ecb_popcount32 (7) = 3
393	ecb_popcount32 (255) = 8	527	ecb_popcount32 (255) = 8
394		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
395	=item uint32_t ecb_bswap16 (uint32_t x)	543	=item uint32_t ecb_bswap16 (uint32_t x)
396		544
397	=item uint32_t ecb_bswap32 (uint32_t x)	545	=item uint32_t ecb_bswap32 (uint32_t x)
398		546
		547	=item uint64_t ecb_bswap64 (uint64_t x)
		548
399	These two functions return the value of the 16-bit (32-bit) variable	549	These functions return the value of the 16-bit (32-bit, 64-bit) value
400	C<x> after reversing the order of bytes.	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)
401		564
402	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	565	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
403		566
404	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	567	=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
405		568
406	These two functions return the value of C<x> after shifting all the bits	569	These two families of functions return the value of C<x> after rotating
407	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>).
		572
		573	Current GCC versions understand these functions and usually compile them
		574	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
		575	x86).
408		576
409	=back	577	=back
410		578
411	=head2 ARITHMETIC	579	=head2 ARITHMETIC
412		580
413	=over 4	581	=over 4
414		582
415	=item x = ecb_mod (m, n)	583	=item x = ecb_mod (m, n)
416		584
417	Returns the positive remainder of the modulo operation between C<m> and	585	Returns C<m> modulo C<n>, which is the same as the positive remainder
		586	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	587	division. Unlike the C remainder operator C<%>, this function ensures that
419	return value is always positive).	588	the return value is always positive and that the two numbers I<m> and
		589	I<m' = m + i * n> result in the same value modulo I<n> - in other words,
		590	C<ecb_mod> implements the mathematical modulo operation, which is missing
		591	in the language.
420		592
421	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
422	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
423	type.	595	type (this typically excludes the minimum signed integer value, the same
		596	limitation as for C</> and C<%> in C).
		597
		598	Current GCC versions compile this into an efficient branchless sequence on
		599	almost all CPUs.
		600
		601	For example, when you want to rotate forward through the members of an
		602	array for increasing C<m> (which might be negative), then you should use
		603	C<ecb_mod>, as the C<%> operator might give either negative results, or
		604	change direction for negative values:
		605
		606	for (m = -100; m <= 100; ++m)
		607	int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
		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++.
424		617
425	=back	618	=back
426		619
427	=head2 UTILITY	620	=head2 UTILITY
428		621
429	=over 4	622	=over 4
430		623
431	=item element_count = ecb_array_length (name) [MACRO]	624	=item element_count = ecb_array_length (name)
432		625
433	Returns the number of elements in the array C<name>. For example:	626	Returns the number of elements in the array C<name>. For example:
434		627
435	int primes[] = { 2, 3, 5, 7, 11 };	628	int primes[] = { 2, 3, 5, 7, 11 };
436	int sum = 0;	629	int sum = 0;
…		…
438	for (i = 0; i < ecb_array_length (primes); i++)	631	for (i = 0; i < ecb_array_length (primes); i++)
439	sum += primes [i];	632	sum += primes [i];
440		633
441	=back	634	=back
442		635
		636	=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
443		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.18 by root, Fri May 27 00:01:28 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.18 by root, Fri May 27 00:01:28 2011 UTC vs.
Revision 1.49 by root, Thu Jun 28 14:50:01 2012 UTC