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

Comparing libecb/ecb.pod (file contents):
Revision 1.16 by sf-exg, Thu May 26 23:32:41 2011 UTC vs.
Revision 1.21 by root, Fri May 27 00:14:10 2011 UTC

…		…
14		14
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
		20	Or in other words, things that should be built-in into any standard C
		21	system, but aren't.
19		22
20	More might come.	23	More might come.
21		24
22	=head2 ABOUT THE HEADER	25	=head2 ABOUT THE HEADER
23		26
…		…
52	is usually implemented as a macro. Specifically, a "bool" in this manual	55	is usually implemented as a macro. Specifically, a "bool" in this manual
53	refers to any kind of boolean value, not a specific type.	56	refers to any kind of boolean value, not a specific type.
54		57
55	=head2 GCC ATTRIBUTES	58	=head2 GCC ATTRIBUTES
56		59
57	blabla where to put, what others	60	A major part of libecb deals with GCC attributes. These are additional
		61	attributes that you cna assign to functions, variables and sometimes even
		62	types - much like C<const> or C<volatile> in C.
		63
		64	While GCC allows declarations to show up in many surprising places,
		65	but not in many expeted places, the safest way is to put attribute
		66	declarations before the whole declaration:
		67
		68	ecb_const int mysqrt (int a);
		69	ecb_unused int i;
		70
		71	For variables, it is often nicer to put the attribute after the name, and
		72	avoid multiple declarations using commas:
		73
		74	int i ecb_unused;
58		75
59	=over 4	76	=over 4
60		77
61	=item ecb_attribute ((attrs...))	78	=item ecb_attribute ((attrs...))
62		79
…		…
91	not inlined into other functions. This is useful if you know your function	108	not inlined into other functions. This is useful if you know your function
92	is rarely called and large enough for inlining not to be helpful.	109	is rarely called and large enough for inlining not to be helpful.
93		110
94	=item ecb_noreturn	111	=item ecb_noreturn
95		112
		113	Marks a function as "not returning, ever". Some typical functions that
		114	don't return are C<exit> or C<abort> (which really works hard to not
		115	return), and now you can make your own:
		116
		117	ecb_noreturn void
		118	my_abort (const char *errline)
		119	{
		120	puts (errline);
		121	abort ();
		122	}
		123
		124	In this case, the compiler would probably be smart enough to deduce it on
		125	its own, so this is mainly useful for declarations.
		126
96	=item ecb_const	127	=item ecb_const
97		128
		129	Declares that the function only depends on the values of its arguments,
		130	much like a mathematical function. It specifically does not read or write
		131	any memory any arguments might point to, global variables, or call any
		132	non-const functions. It also must not have any side effects.
		133
		134	Such a function can be optimised much more aggressively by the compiler -
		135	for example, multiple calls with the same arguments can be optimised into
		136	a single call, which wouldn't be possible if the compiler would have to
		137	expect any side effects.
		138
		139	It is best suited for functions in the sense of mathematical functions,
		140	such as a function returning the square root of its input argument.
		141
		142	Not suited would be a function that calculates the hash of some memory
		143	area you pass in, prints some messages or looks at a global variable to
		144	decide on rounding.
		145
		146	See C<ecb_pure> for a slightly less restrictive class of functions.
		147
98	=item ecb_pure	148	=item ecb_pure
99		149
		150	Similar to C<ecb_const>, declares a function that has no side
		151	effects. Unlike C<ecb_const>, the function is allowed to examine global
		152	variables and any other memory areas (such as the ones passed to it via
		153	pointers).
		154
		155	While these functions cannot be optimised as aggressively as C<ecb_const>
		156	functions, they can still be optimised away in many occasions, and the
		157	compiler has more freedom in moving calls to them around.
		158
		159	Typical examples for such functions would be C<strlen> or C<memcmp>. A
		160	function that calculates the MD5 sum of some input and updates some MD5
		161	state passed as argument would I<NOT> be pure, however, as it would modify
		162	some memory area that is not the return value.
		163
100	=item ecb_hot	164	=item ecb_hot
101		165
		166	This declares a function as "hot" with regards to the cache - the function
		167	is used so often, that it is very beneficial to keep it in the cache if
		168	possible.
		169
		170	The compiler reacts by trying to place hot functions near to each other in
		171	memory.
		172
		173	Whether a function is hot or not often depends on the whole program,
		174	and less on the function itself. C<ecb_cold> is likely more useful in
		175	practise.
		176
102	=item ecb_cold	177	=item ecb_cold
103		178
		179	The opposite of C<ecb_hot> - declares a function as "cold" with regards to
		180	the cache, or in other words, this function is not called often, or not at
		181	speed-critical times, and keeping it in the cache might be a waste of said
		182	cache.
		183
		184	In addition to placing cold functions together (or at least away from hot
		185	functions), this knowledge can be used in other ways, for example, the
		186	function will be optimised for size, as opposed to speed, and codepaths
		187	leading to calls to those functions can automatically be marked as if
		188	C<ecb_unlikely> had been used to reach them.
		189
		190	Good examples for such functions would be error reporting functions, or
		191	functions only called in exceptional or rare cases.
		192
104	=item ecb_artificial	193	=item ecb_artificial
		194
		195	Declares the function as "artificial", in this case meaning that this
		196	function is not really mean to be a function, but more like an accessor
		197	- many methods in C++ classes are mere accessor functions, and having a
		198	crash reported in such a method, or single-stepping through them, is not
		199	usually so helpful, especially when it's inlined to just a few instructions.
		200
		201	Marking them as artificial will instruct the debugger about just this,
		202	leading to happier debugging and thus happier lives.
		203
		204	Example: in some kind of smart-pointer class, mark the pointer accessor as
		205	artificial, so that the whole class acts more like a pointer and less like
		206	some C++ abstraction monster.
		207
		208	template<typename T>
		209	struct my_smart_ptr
		210	{
		211	T *value;
		212
		213	ecb_artificial
		214	operator T *()
		215	{
		216	return value;
		217	}
		218	};
105		219
106	=back	220	=back
107		221
108	=head2 OPTIMISATION HINTS	222	=head2 OPTIMISATION HINTS
109		223
…		…
294		408
295	=item uint32_t ecb_bswap16 (uint32_t x)	409	=item uint32_t ecb_bswap16 (uint32_t x)
296		410
297	=item uint32_t ecb_bswap32 (uint32_t x)	411	=item uint32_t ecb_bswap32 (uint32_t x)
298		412
299	These two functions return the value of the 16-bit (32-bit) variable	413	These two functions return the value of the 16-bit (32-bit) value C<x>
300	C<x> after reversing the order of bytes.	414	after reversing the order of bytes (0x11223344 becomes 0x44332211).
301		415
302	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	416	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
303		417
304	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	418	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
305		419
306	These two functions return the value of C<x> after shifting all the bits	420	These two functions return the value of C<x> after shifting all the bits
307	by C<count> positions to the right or left respectively.	421	by C<count> positions to the right or left respectively.
308		422
		423	Current GCC versions understand these functions and usually compile them
		424	to "optimal" code (e.g. a single C<roll> on x86).
		425
309	=back	426	=back
310		427
311	=head2 ARITHMETIC	428	=head2 ARITHMETIC
312		429
313	=over 4	430	=over 4
314		431
315	=item x = ecb_mod (m, n)	432	=item x = ecb_mod (m, n)
316		433
317	Returns the positive remainder of the modulo operation between C<m> and	434	Returns the positive remainder of the modulo operation between C<m> and
318	C<n>. Unlike the C modulo operator C<%>, this function ensures that the	435	C<n>. Unlike the C modulo operator C<%>, this function ensures that the
319	return value is always positive).	436	return value is always positive - ISO C guarantees very little when
		437	negative numbers are used with C<%>.
320		438
321	C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be	439	C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be
322	negatable, that is, both C<m> and C<-m> must be representable in its	440	negatable, that is, both C<m> and C<-m> must be representable in its
323	type.	441	type.
324		442

Diff Legend

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

Comparing libecb/ecb.pod (file contents): Revision 1.16 by sf-exg, Thu May 26 23:32:41 2011 UTC vs. Revision 1.21 by root, Fri May 27 00:14:10 2011 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.16 by sf-exg, Thu May 26 23:32:41 2011 UTC vs.
Revision 1.21 by root, Fri May 27 00:14:10 2011 UTC