Merge XtraDB 8 into MariaDB.

1 files changed, 183 insertions, 126 deletions

diff --git a/storage/xtradb/include/ut0ut.h b/storage/xtradb/include/ut0ut.h
index 3ca14acd2ef..80094321041 100644
--- a/storage/xtradb/include/ut0ut.h
+++ b/storage/xtradb/include/ut0ut.h
@@ -1,6 +1,13 @@
 /*****************************************************************************
 
 Copyright (c) 1994, 2009, Innobase Oy. All Rights Reserved.
+Copyright (c) 2009, Sun Microsystems, Inc.
+
+Portions of this file contain modifications contributed and copyrighted by
+Sun Microsystems, Inc. Those modifications are gratefully acknowledged and
+are described briefly in the InnoDB documentation. The contributions by
+Sun Microsystems are incorporated with their permission, and subject to the
+conditions contained in the file COPYING.Sun_Microsystems.
 
 This program is free software; you can redistribute it and/or modify it under
 the terms of the GNU General Public License as published by the Free Software
@@ -16,7 +23,8 @@ Place, Suite 330, Boston, MA 02111-1307 USA
 
 *****************************************************************************/
 
-/**********************************************************************
+/******************************************************************//**
+@file include/ut0ut.h
 Various utilities
 
 Created 1/20/1994 Heikki Tuuri
@@ -31,15 +39,41 @@ Created 1/20/1994 Heikki Tuuri
 #include <ctype.h>
 #endif
 
-#define	TEMP_INDEX_PREFIX	'\377'	/* Index name prefix in fast index
-					creation */
+/** Index name prefix in fast index creation */
+#define	TEMP_INDEX_PREFIX	'\377'
+/** Index name prefix in fast index creation, as a string constant */
+#define TEMP_INDEX_PREFIX_STR	"\377"
 
+/** Time stamp */
 typedef time_t	ib_time_t;
 
-/*************************************************************************
-Delays execution for at most max_wait_us microseconds or returns earlier
-if cond becomes true; cond is evaluated every 2 ms. */
+#if defined(IB_HAVE_PAUSE_INSTRUCTION)
+#  ifdef WIN32
+     /* In the Win32 API, the x86 PAUSE instruction is executed by calling
+     the YieldProcessor macro defined in WinNT.h. It is a CPU architecture-
+     independent way by using YieldProcessor.*/
+#    define UT_RELAX_CPU() YieldProcessor()
+#  else
+     /* According to the gcc info page, asm volatile means that the
+     instruction has important side-effects and must not be removed.
+     Also asm volatile may trigger a memory barrier (spilling all registers
+     to memory). */
+#    define UT_RELAX_CPU() __asm__ __volatile__ ("pause")
+#  endif
+#elif defined(HAVE_ATOMIC_BUILTINS)
+#  define UT_RELAX_CPU() do { \
+     volatile lint	volatile_var; \
+     os_compare_and_swap_lint(&volatile_var, 0, 1); \
+   } while (0)
+#else
+#  define UT_RELAX_CPU() ((void)0) /* avoid warning for an empty statement */
+#endif
 
+/*********************************************************************//**
+Delays execution for at most max_wait_us microseconds or returns earlier
+if cond becomes true.
+@param cond		in: condition to wait for; evaluated every 2 ms
+@param max_wait_us	in: maximum delay to wait, in microseconds */
 #define UT_WAIT_FOR(cond, max_wait_us)				\
 do {								\
 	ullint	start_us;					\
@@ -51,218 +85,237 @@ do {								\
 	}							\
 } while (0)
 
-/************************************************************
+/********************************************************//**
 Gets the high 32 bits in a ulint. That is makes a shift >> 32,
 but since there seem to be compiler bugs in both gcc and Visual C++,
-we do this by a special conversion. */
+we do this by a special conversion.
+@return	a >> 32 */
 UNIV_INTERN
 ulint
 ut_get_high32(
 /*==========*/
-			/* out: a >> 32 */
-	ulint	a);	/* in: ulint */
-/**********************************************************
-Calculates the minimum of two ulints. */
+	ulint	a);	/*!< in: ulint */
+/******************************************************//**
+Calculates the minimum of two ulints.
+@return	minimum */
 UNIV_INLINE
 ulint
 ut_min(
 /*===*/
-			/* out: minimum */
-	ulint	 n1,	/* in: first number */
-	ulint	 n2);	/* in: second number */
-/**********************************************************
-Calculates the maximum of two ulints. */
+	ulint	 n1,	/*!< in: first number */
+	ulint	 n2);	/*!< in: second number */
+/******************************************************//**
+Calculates the maximum of two ulints.
+@return	maximum */
 UNIV_INLINE
 ulint
 ut_max(
 /*===*/
-			/* out: maximum */
-	ulint	 n1,	/* in: first number */
-	ulint	 n2);	/* in: second number */
-/********************************************************************
+	ulint	 n1,	/*!< in: first number */
+	ulint	 n2);	/*!< in: second number */
+/****************************************************************//**
 Calculates minimum of two ulint-pairs. */
 UNIV_INLINE
 void
 ut_pair_min(
 /*========*/
-	ulint*	a,	/* out: more significant part of minimum */
-	ulint*	b,	/* out: less significant part of minimum */
-	ulint	a1,	/* in: more significant part of first pair */
-	ulint	b1,	/* in: less significant part of first pair */
-	ulint	a2,	/* in: more significant part of second pair */
-	ulint	b2);	/* in: less significant part of second pair */
-/**********************************************************
-Compares two ulints. */
+	ulint*	a,	/*!< out: more significant part of minimum */
+	ulint*	b,	/*!< out: less significant part of minimum */
+	ulint	a1,	/*!< in: more significant part of first pair */
+	ulint	b1,	/*!< in: less significant part of first pair */
+	ulint	a2,	/*!< in: more significant part of second pair */
+	ulint	b2);	/*!< in: less significant part of second pair */
+/******************************************************//**
+Compares two ulints.
+@return	1 if a > b, 0 if a == b, -1 if a < b */
 UNIV_INLINE
 int
 ut_ulint_cmp(
 /*=========*/
-			/* out: 1 if a > b, 0 if a == b, -1 if a < b */
-	ulint	a,	/* in: ulint */
-	ulint	b);	/* in: ulint */
-/***********************************************************
-Compares two pairs of ulints. */
+	ulint	a,	/*!< in: ulint */
+	ulint	b);	/*!< in: ulint */
+/*******************************************************//**
+Compares two pairs of ulints.
+@return	-1 if a < b, 0 if a == b, 1 if a > b */
 UNIV_INLINE
 int
 ut_pair_cmp(
 /*========*/
-			/* out: -1 if a < b, 0 if a == b,
-			1 if a > b */
-	ulint	a1,	/* in: more significant part of first pair */
-	ulint	a2,	/* in: less significant part of first pair */
-	ulint	b1,	/* in: more significant part of second pair */
-	ulint	b2);	/* in: less significant part of second pair */
-/*****************************************************************
-Determines if a number is zero or a power of two. */
+	ulint	a1,	/*!< in: more significant part of first pair */
+	ulint	a2,	/*!< in: less significant part of first pair */
+	ulint	b1,	/*!< in: more significant part of second pair */
+	ulint	b2);	/*!< in: less significant part of second pair */
+/*************************************************************//**
+Determines if a number is zero or a power of two.
+@param n	in: number
+@return		nonzero if n is zero or a power of two; zero otherwise */
 #define ut_is_2pow(n) UNIV_LIKELY(!((n) & ((n) - 1)))
-/*****************************************************************
-Calculates fast the remainder of n/m when m is a power of two. */
+/*************************************************************//**
+Calculates fast the remainder of n/m when m is a power of two.
+@param n	in: numerator
+@param m	in: denominator, must be a power of two
+@return		the remainder of n/m */
 #define ut_2pow_remainder(n, m) ((n) & ((m) - 1))
-/*****************************************************************
+/*************************************************************//**
 Calculates the biggest multiple of m that is not bigger than n
-when m is a power of two.  In other words, rounds n down to m * k. */
+when m is a power of two.  In other words, rounds n down to m * k.
+@param n	in: number to round down
+@param m	in: alignment, must be a power of two
+@return		n rounded down to the biggest possible integer multiple of m */
 #define ut_2pow_round(n, m) ((n) & ~((m) - 1))
+/** Align a number down to a multiple of a power of two.
+@param n	in: number to round down
+@param m	in: alignment, must be a power of two
+@return		n rounded down to the biggest possible integer multiple of m */
 #define ut_calc_align_down(n, m) ut_2pow_round(n, m)
-/************************************************************
+/********************************************************//**
 Calculates the smallest multiple of m that is not smaller than n
-when m is a power of two.  In other words, rounds n up to m * k. */
+when m is a power of two.  In other words, rounds n up to m * k.
+@param n	in: number to round up
+@param m	in: alignment, must be a power of two
+@return		n rounded up to the smallest possible integer multiple of m */
 #define ut_calc_align(n, m) (((n) + ((m) - 1)) & ~((m) - 1))
-/*****************************************************************
+/*************************************************************//**
 Calculates fast the 2-logarithm of a number, rounded upward to an
-integer. */
+integer.
+@return	logarithm in the base 2, rounded upward */
 UNIV_INLINE
 ulint
 ut_2_log(
 /*=====*/
-			/* out: logarithm in the base 2, rounded upward */
-	ulint	n);	/* in: number */
-/*****************************************************************
-Calculates 2 to power n. */
+	ulint	n);	/*!< in: number */
+/*************************************************************//**
+Calculates 2 to power n.
+@return	2 to power n */
 UNIV_INLINE
 ulint
 ut_2_exp(
 /*=====*/
-			/* out: 2 to power n */
-	ulint	n);	/* in: number */
-/*****************************************************************
-Calculates fast the number rounded up to the nearest power of 2. */
+	ulint	n);	/*!< in: number */
+/*************************************************************//**
+Calculates fast the number rounded up to the nearest power of 2.
+@return	first power of 2 which is >= n */
 UNIV_INTERN
 ulint
 ut_2_power_up(
 /*==========*/
-			/* out: first power of 2 which is >= n */
-	ulint	n)	/* in: number != 0 */
+	ulint	n)	/*!< in: number != 0 */
 	__attribute__((const));
 
-/* Determine how many bytes (groups of 8 bits) are needed to
-store the given number of bits. */
+/** Determine how many bytes (groups of 8 bits) are needed to
+store the given number of bits.
+@param b	in: bits
+@return		number of bytes (octets) needed to represent b */
 #define UT_BITS_IN_BYTES(b) (((b) + 7) / 8)
 
-/**************************************************************
+/**********************************************************//**
 Returns system time. We do not specify the format of the time returned:
-the only way to manipulate it is to use the function ut_difftime. */
+the only way to manipulate it is to use the function ut_difftime.
+@return	system time */
 UNIV_INTERN
 ib_time_t
 ut_time(void);
 /*=========*/
-/**************************************************************
+/**********************************************************//**
 Returns system time.
 Upon successful completion, the value 0 is returned; otherwise the
 value -1 is returned and the global variable errno is set to indicate the
-error. */
+error.
+@return	0 on success, -1 otherwise */
 UNIV_INTERN
 int
 ut_usectime(
 /*========*/
-			/* out: 0 on success, -1 otherwise */
-	ulint*	sec,	/* out: seconds since the Epoch */
-	ulint*	ms);	/* out: microseconds since the Epoch+*sec */
+	ulint*	sec,	/*!< out: seconds since the Epoch */
+	ulint*	ms);	/*!< out: microseconds since the Epoch+*sec */
 
-/**************************************************************
+/**********************************************************//**
 Returns the number of microseconds since epoch. Similar to
 time(3), the return value is also stored in *tloc, provided
-that tloc is non-NULL. */
+that tloc is non-NULL.
+@return	us since epoch */
 UNIV_INTERN
 ullint
 ut_time_us(
 /*=======*/
-			/* out: us since epoch */
-	ullint*	tloc);	/* out: us since epoch, if non-NULL */
+	ullint*	tloc);	/*!< out: us since epoch, if non-NULL */
 
-/**************************************************************
-Returns the difference of two times in seconds. */
+/**********************************************************//**
+Returns the difference of two times in seconds.
+@return	time2 - time1 expressed in seconds */
 UNIV_INTERN
 double
 ut_difftime(
 /*========*/
-				/* out: time2 - time1 expressed in seconds */
-	ib_time_t	time2,	/* in: time */
-	ib_time_t	time1);	/* in: time */
-/**************************************************************
+	ib_time_t	time2,	/*!< in: time */
+	ib_time_t	time1);	/*!< in: time */
+/**********************************************************//**
 Prints a timestamp to a file. */
 UNIV_INTERN
 void
 ut_print_timestamp(
 /*===============*/
-	FILE*  file); /* in: file where to print */
-/**************************************************************
+	FILE*  file); /*!< in: file where to print */
+/**********************************************************//**
 Sprintfs a timestamp to a buffer, 13..14 chars plus terminating NUL. */
 UNIV_INTERN
 void
 ut_sprintf_timestamp(
 /*=================*/
-	char*	buf); /* in: buffer where to sprintf */
+	char*	buf); /*!< in: buffer where to sprintf */
 #ifdef UNIV_HOTBACKUP
-/**************************************************************
+/**********************************************************//**
 Sprintfs a timestamp to a buffer with no spaces and with ':' characters
 replaced by '_'. */
 UNIV_INTERN
 void
 ut_sprintf_timestamp_without_extra_chars(
 /*=====================================*/
-	char*	buf); /* in: buffer where to sprintf */
-/**************************************************************
+	char*	buf); /*!< in: buffer where to sprintf */
+/**********************************************************//**
 Returns current year, month, day. */
 UNIV_INTERN
 void
 ut_get_year_month_day(
 /*==================*/
-	ulint*	year,	/* out: current year */
-	ulint*	month,	/* out: month */
-	ulint*	day);	/* out: day */
-#endif /* UNIV_HOTBACKUP */
-/*****************************************************************
+	ulint*	year,	/*!< out: current year */
+	ulint*	month,	/*!< out: month */
+	ulint*	day);	/*!< out: day */
+#else /* UNIV_HOTBACKUP */
+/*************************************************************//**
 Runs an idle loop on CPU. The argument gives the desired delay
-in microseconds on 100 MHz Pentium + Visual C++. */
+in microseconds on 100 MHz Pentium + Visual C++.
+@return	dummy value */
 UNIV_INTERN
 ulint
 ut_delay(
 /*=====*/
-			/* out: dummy value */
-	ulint	delay);	/* in: delay in microseconds on 100 MHz Pentium */
-/*****************************************************************
+	ulint	delay);	/*!< in: delay in microseconds on 100 MHz Pentium */
+#endif /* UNIV_HOTBACKUP */
+/*************************************************************//**
 Prints the contents of a memory buffer in hex and ascii. */
 UNIV_INTERN
 void
 ut_print_buf(
 /*=========*/
-	FILE*		file,	/* in: file where to print */
-	const void*	buf,	/* in: memory buffer */
-	ulint		len);	/* in: length of the buffer */
+	FILE*		file,	/*!< in: file where to print */
+	const void*	buf,	/*!< in: memory buffer */
+	ulint		len);	/*!< in: length of the buffer */
 
-/**************************************************************************
+/**********************************************************************//**
 Outputs a NUL-terminated file name, quoted with apostrophes. */
 UNIV_INTERN
 void
 ut_print_filename(
 /*==============*/
-	FILE*		f,	/* in: output stream */
-	const char*	name);	/* in: name to print */
+	FILE*		f,	/*!< in: output stream */
+	const char*	name);	/*!< in: name to print */
 
+#ifndef UNIV_HOTBACKUP
 /* Forward declaration of transaction handle */
 struct trx_struct;
 
-/**************************************************************************
+/**********************************************************************//**
 Outputs a fixed-length string, quoted as an SQL identifier.
 If the string contains a slash '/', the string will be
 output as two identifiers separated by a period (.),
@@ -271,13 +324,13 @@ UNIV_INTERN
 void
 ut_print_name(
 /*==========*/
-	FILE*		f,	/* in: output stream */
-	struct trx_struct*trx,	/* in: transaction */
-	ibool		table_id,/* in: TRUE=print a table name,
+	FILE*		f,	/*!< in: output stream */
+	struct trx_struct*trx,	/*!< in: transaction */
+	ibool		table_id,/*!< in: TRUE=print a table name,
 				FALSE=print other identifier */
-	const char*	name);	/* in: name to print */
+	const char*	name);	/*!< in: name to print */
 
-/**************************************************************************
+/**********************************************************************//**
 Outputs a fixed-length string, quoted as an SQL identifier.
 If the string contains a slash '/', the string will be
 output as two identifiers separated by a period (.),
@@ -286,38 +339,42 @@ UNIV_INTERN
 void
 ut_print_namel(
 /*===========*/
-	FILE*		f,	/* in: output stream */
-	struct trx_struct*trx,	/* in: transaction (NULL=no quotes) */
-	ibool		table_id,/* in: TRUE=print a table name,
+	FILE*		f,	/*!< in: output stream */
+	struct trx_struct*trx,	/*!< in: transaction (NULL=no quotes) */
+	ibool		table_id,/*!< in: TRUE=print a table name,
 				FALSE=print other identifier */
-	const char*	name,	/* in: name to print */
-	ulint		namelen);/* in: length of name */
+	const char*	name,	/*!< in: name to print */
+	ulint		namelen);/*!< in: length of name */
 
-/**************************************************************************
+/**********************************************************************//**
 Catenate files. */
 UNIV_INTERN
 void
 ut_copy_file(
 /*=========*/
-	FILE*	dest,	/* in: output file */
-	FILE*	src);	/* in: input file to be appended to output */
-
-/**************************************************************************
-snprintf(). */
+	FILE*	dest,	/*!< in: output file */
+	FILE*	src);	/*!< in: input file to be appended to output */
+#endif /* !UNIV_HOTBACKUP */
 
 #ifdef __WIN__
+/**********************************************************************//**
+A substitute for snprintf(3), formatted output conversion into
+a limited buffer.
+@return number of characters that would have been printed if the size
+were unlimited, not including the terminating '\0'. */
+UNIV_INTERN
 int
 ut_snprintf(
-				/* out: number of characters that would
-				have been printed if the size were
-				unlimited, not including the terminating
-				'\0'. */
-	char*		str,	/* out: string */
-	size_t		size,	/* in: str size */
-	const char*	fmt,	/* in: format */
-	...);			/* in: format values */
+/*========*/
+	char*		str,	/*!< out: string */
+	size_t		size,	/*!< in: str size */
+	const char*	fmt,	/*!< in: format */
+	...);			/*!< in: format values */
 #else
-#define ut_snprintf	snprintf
+/**********************************************************************//**
+A wrapper for snprintf(3), formatted output conversion into
+a limited buffer. */
+# define ut_snprintf	snprintf
 #endif /* __WIN__ */
 
 #ifndef UNIV_NONINL