MySQL  8.0.20
Source Code Documentation
ut0ut.h File Reference

Various utilities. More...

#include <string.h>
#include <algorithm>
#include <cmath>
#include <iomanip>
#include <iterator>
#include <ostream>
#include <sstream>
#include <type_traits>
#include "db0err.h"
#include "os0atomic.h"
#include <time.h>
#include <ctype.h>
#include <stdarg.h>
#include "ut/ut.h"
#include "ut0dbg.h"
#include "mysql/components/services/log_builtins.h"
#include "mysqld_error.h"
#include "sql/derror.h"
#include "ut0ut.ic"

Go to the source code of this file.

Classes

struct  ut_strcmp_functor
 Functor that compares two C strings. More...
 
struct  ib::hex
 This is a wrapper class, used to print any unsigned integer type in hexadecimal format. More...
 
class  ib::logger
 The class logger is the base class of all the error log related classes. More...
 
class  ib::info
 The class info is used to emit informational log messages. More...
 
class  ib::warn
 The class warn is used to emit warnings. More...
 
class  ib::error
 The class error is used to emit error messages. More...
 
class  ib::fatal
 The class fatal is used to emit an error message and stop the server by crashing it. More...
 
class  ib::error_or_warn
 Emit an error message if the given predicate is true, otherwise emit a warning message. More...
 
class  ib::fatal_or_error
 Emit a fatal message if the given predicate is true, otherwise emit a error message. More...
 
struct  Wait_stats
 

Namespaces

 ut
 
 ib
 

Macros

#define TEMP_INDEX_PREFIX_STR   "\377"
 Index name prefix in fast index creation, as a string constant. More...
 
#define UT_RELAX_CPU()   __asm__ __volatile__("pause")
 
#define UT_LOW_PRIORITY_CPU()   ((void)0)
 
#define UT_RESUME_PRIORITY_CPU()   ((void)0)
 
#define UT_WAIT_FOR(cond, max_wait_us)
 Delays execution for at most max_wait_us microseconds or returns earlier if cond becomes true. More...
 
#define ut_max   std::max
 
#define ut_min   std::min
 
#define ut_2pow_remainder(n, m)   ((n) & ((m)-1))
 Calculates fast the remainder of n/m when m is a power of two. More...
 
#define ut_2pow_round(n, m)   ((n) & ~((m)-1))
 Calculates the biggest multiple of m that is not bigger than n when m is a power of two. More...
 
#define ut_calc_align_down(n, m)   ut_2pow_round(n, m)
 Align a number down to a multiple of a power of two. More...
 
#define ut_calc_align(n, m)   (((n) + ((m)-1)) & ~((m)-1))
 Calculates the smallest multiple of m that is not smaller than n when m is a power of two. More...
 
#define UT_BITS_IN_BYTES(b)   (((b) + 7) / 8)
 Determine how many bytes (groups of 8 bits) are needed to store the given number of bits. More...
 
#define ut_is_2pow(n)   UNIV_LIKELY(!((n) & ((n)-1)))
 Determines if a number is zero or a power of two. More...
 
#define ut_vsnprintf(buf, size, fmt, ap)   ((void)vsnprintf(buf, size, fmt, ap))
 A wrapper for vsnprintf(3), formatted output conversion into a limited buffer. More...
 

Typedefs

typedef time_t ib_time_t
 Time stamp. More...
 
typedef int64_t ib_time_monotonic_t
 Time stamp read from the monotonic clock (returned by ut_time_monotonic()). More...
 
typedef int64_t ib_time_monotonic_ms_t
 Number of milliseconds read from the monotonic clock (returned by ut_time_monotonic_ms()). More...
 
typedef int64_t ib_time_monotonic_us_t
 Number of microseconds read from the monotonic clock (returned by ut_time_monotonic_us()). More...
 

Functions

const char * srv_get_server_errmsgs (int errcode)
 Get the format string for the logger. More...
 
UNIV_INLINE void ut_pair_min (ulint *min_hi, ulint *min_lo, ulint a_hi, ulint a_lo, ulint b_hi, ulint b_lo)
 Calculate the minimum of two pairs. More...
 
UNIV_INLINE int ut_ulint_cmp (ulint a, ulint b)
 Compares two ulints. More...
 
UNIV_INLINE int ut_pair_cmp (ulint a_h, ulint a_l, ulint b_h, ulint b_l)
 Compare two pairs of integers. More...
 
UNIV_INLINE ulint ut_2_log (ulint n)
 Calculates fast the 2-logarithm of a number, rounded upward to an integer. More...
 
UNIV_INLINE uint32_t ut_2_exp (uint32_t n)
 Calculates 2 to power n. More...
 
ulint ut_2_power_up (ulint n)
 Calculates fast the number rounded up to the nearest power of 2. More...
 
ib_time_t ut_time (void)
 Returns system time. More...
 
ib_time_monotonic_us_t ut_time_monotonic_us (void)
 Returns the number of microseconds since epoch. More...
 
ib_time_monotonic_ms_t ut_time_monotonic_ms (void)
 Returns the number of milliseconds since epoch. More...
 
ib_time_monotonic_t ut_time_monotonic (void)
 Returns the number of seconds since epoch. More...
 
double ut_difftime (ib_time_t time2, ib_time_t time1)
 Returns the difference of two times in seconds. More...
 
ulint ut_delay (ulint delay)
 Runs an idle loop on CPU. More...
 
std::string ut_get_name (const trx_t *trx, const char *name)
 Get a fixed-length string, quoted as an SQL identifier. More...
 
void ut_print_name (FILE *f, const trx_t *trx, const char *name)
 Outputs a fixed-length string, quoted as an SQL identifier. More...
 
char * ut_format_name (const char *name, char *formatted, ulint formatted_size)
 Format a table name, quoted as an SQL identifier. More...
 
void ut_copy_file (FILE *dest, FILE *src)
 Catenate files. More...
 
void ut_format_byte_value (uint64_t data_bytes, std::string &data_str)
 Convert byte value to string with unit. More...
 
const char * ut_strerr (dberr_t num)
 Convert an error number to a human readable text message. More...
 
static const char * ib::get_first_format (const char *fmt)
 Finds the first format specifier in fmt format string. More...
 
static bool ib::verify_fmt_match (const char *fmt)
 Verifies that the fmt format string does not require any arguments. More...
 
template<typename Head , typename... Tail>
static bool ib::verify_fmt_match (const char *fmt, Head &&head, Tail &&... tail)
 Verifies that the fmt format string contains format specifiers which match the type and order of the arguments. More...
 
std::ostream & ib::operator<< (std::ostream &lhs, const hex &rhs)
 This is an overload of the global operator<< for the user defined type ib::hex. More...
 

Variables

ulong ut::spin_wait_pause_multiplier = 50
 The current value of @innodb_spin_wait_pause_multiplier. More...
 

Detailed Description

Various utilities.

Created 1/20/1994 Heikki Tuuri

Macro Definition Documentation

◆ TEMP_INDEX_PREFIX_STR

#define TEMP_INDEX_PREFIX_STR   "\377"

Index name prefix in fast index creation, as a string constant.

◆ ut_2pow_remainder

#define ut_2pow_remainder (   n,
 
)    ((n) & ((m)-1))

Calculates fast the remainder of n/m when m is a power of two.

Parameters
nin: numerator
min: denominator, must be a power of two
Returns
the remainder of n/m

◆ ut_2pow_round

#define ut_2pow_round (   n,
 
)    ((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.

Parameters
nin: number to round down
min: alignment, must be a power of two
Returns
n rounded down to the biggest possible integer multiple of m

◆ UT_BITS_IN_BYTES

#define UT_BITS_IN_BYTES (   b)    (((b) + 7) / 8)

Determine how many bytes (groups of 8 bits) are needed to store the given number of bits.

Parameters
bin: bits
Returns
number of bytes (octets) needed to represent b

◆ ut_calc_align

#define ut_calc_align (   n,
 
)    (((n) + ((m)-1)) & ~((m)-1))

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.

Parameters
nin: number to round up
min: alignment, must be a power of two
Returns
n rounded up to the smallest possible integer multiple of m

◆ ut_calc_align_down

#define ut_calc_align_down (   n,
 
)    ut_2pow_round(n, m)

Align a number down to a multiple of a power of two.

Parameters
nin: number to round down
min: alignment, must be a power of two
Returns
n rounded down to the biggest possible integer multiple of m

◆ ut_is_2pow

#define ut_is_2pow (   n)    UNIV_LIKELY(!((n) & ((n)-1)))

Determines if a number is zero or a power of two.

Parameters
[in]nnumber
Returns
nonzero if n is zero or a power of two; zero otherwise

◆ UT_LOW_PRIORITY_CPU

#define UT_LOW_PRIORITY_CPU ( )    ((void)0)

◆ ut_max

#define ut_max   std::max

◆ ut_min

#define ut_min   std::min

◆ UT_RELAX_CPU

#define UT_RELAX_CPU ( )    __asm__ __volatile__("pause")

◆ UT_RESUME_PRIORITY_CPU

#define UT_RESUME_PRIORITY_CPU ( )    ((void)0)

◆ ut_vsnprintf

#define ut_vsnprintf (   buf,
  size,
  fmt,
  ap 
)    ((void)vsnprintf(buf, size, fmt, ap))

A wrapper for vsnprintf(3), formatted output conversion into a limited buffer.

Note: this function DOES NOT return the number of characters that would have been printed if the buffer was unlimited because VC's _vsnprintf() returns -1 in this case and we would need to call _vscprintf() in addition to estimate that but we would need another copy of "ap" for that and VC does not provide va_copy().

◆ UT_WAIT_FOR

#define UT_WAIT_FOR (   cond,
  max_wait_us 
)
Value:
do { \
const auto start_us = ut_time_monotonic_us(); \
while (!(cond)) { \
const auto diff = ut_time_monotonic_us() - start_us; \
const auto limit = max_wait_us; \
if (limit <= 0 || (diff > 0 && ((uint64_t)diff) > ((uint64_t)limit))) { \
break; \
} \
os_thread_sleep(2000 /* 2 ms */); \
} \
} while (0)
static Bigint * diff(Bigint *a, Bigint *b, Stack_alloc *alloc)
Definition: dtoa.cc:1089
ib_time_monotonic_us_t ut_time_monotonic_us(void)
Returns the number of microseconds since epoch.
Definition: ut0ut.cc:73

Delays execution for at most max_wait_us microseconds or returns earlier if cond becomes true.

Parameters
condin: condition to wait for; evaluated every 2 ms
max_wait_usin: maximum delay to wait, in microseconds

Typedef Documentation

◆ ib_time_monotonic_ms_t

typedef int64_t ib_time_monotonic_ms_t

Number of milliseconds read from the monotonic clock (returned by ut_time_monotonic_ms()).

◆ ib_time_monotonic_t

typedef int64_t ib_time_monotonic_t

Time stamp read from the monotonic clock (returned by ut_time_monotonic()).

◆ ib_time_monotonic_us_t

typedef int64_t ib_time_monotonic_us_t

Number of microseconds read from the monotonic clock (returned by ut_time_monotonic_us()).

◆ ib_time_t

typedef time_t ib_time_t

Time stamp.

Function Documentation

◆ srv_get_server_errmsgs()

const char* srv_get_server_errmsgs ( int  errcode)

Get the format string for the logger.

Parameters
[in]errcodeThe error code from share/errmsg-*.txt
Returns
the message string or nullptr

◆ ut_2_exp()

UNIV_INLINE uint32_t ut_2_exp ( uint32_t  n)

Calculates 2 to power n.

Parameters
[in]npower of 2
Returns
2 to power n

◆ ut_2_log()

UNIV_INLINE ulint ut_2_log ( ulint  n)

Calculates fast the 2-logarithm of a number, rounded upward to an integer.

Returns
logarithm in the base 2, rounded upward in: number

◆ ut_2_power_up()

ulint ut_2_power_up ( ulint  n)

Calculates fast the number rounded up to the nearest power of 2.

Returns
first power of 2 which is >= n
Parameters
nin: number != 0

◆ ut_copy_file()

void ut_copy_file ( FILE *  dest,
FILE *  src 
)

Catenate files.

in: input file to be appended to output

Parameters
destin: output file
srcin: input file to be appended to output

◆ ut_delay()

ulint ut_delay ( ulint  delay)

Runs an idle loop on CPU.

The argument gives the desired delay in microseconds on 100 MHz Pentium + Visual C++. The actual duration depends on a product of delay and the current value of @innodb_spin_wait_pause_multiplier.

Parameters
[in]delaydelay in microseconds on 100 MHz Pentium, assuming spin_wait_pause_multiplier is 50 (default).
Returns
dummy value

◆ ut_difftime()

double ut_difftime ( ib_time_t  time2,
ib_time_t  time1 
)

Returns the difference of two times in seconds.

Returns
time2 - time1 expressed in seconds in: time
time2 - time1 expressed in seconds
Parameters
time2in: time
time1in: time

◆ ut_format_byte_value()

void ut_format_byte_value ( uint64_t  data_bytes,
std::string &  data_str 
)

Convert byte value to string with unit.

Parameters
[in]data_bytesbyte value
[out]data_strformatted string

◆ ut_format_name()

char* ut_format_name ( const char *  name,
char *  formatted,
ulint  formatted_size 
)

Format a table name, quoted as an SQL identifier.

If the name contains a slash '/', the result will contain two identifiers separated by a period (.), as in SQL database_name.table_name.

See also
table_name_t
Parameters
[in]nametable or index name
[out]formattedformatted result, will be NUL-terminated
[in]formatted_sizesize of the buffer in bytes
Returns
pointer to 'formatted'

◆ ut_get_name()

std::string ut_get_name ( const trx_t trx,
const char *  name 
)

Get 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 (.), as in SQL database_name.identifier.

Parameters
[in]trxtransaction (NULL=no quotes).
[in]nametable name.
Return values
Stringquoted as an SQL identifier.

◆ ut_pair_cmp()

UNIV_INLINE int ut_pair_cmp ( ulint  a_h,
ulint  a_l,
ulint  b_h,
ulint  b_l 
)

Compare two pairs of integers.

Parameters
[in]a_hmore significant part of first pair
[in]a_lless significant part of first pair
[in]b_hmore significant part of second pair
[in]b_lless significant part of second pair
Returns
comparison result of (a_h,a_l) and (b_h,b_l)
Return values
-1if (a_h,a_l) is less than (b_h,b_l)
0if (a_h,a_l) is equal to (b_h,b_l)
1if (a_h,a_l) is greater than (b_h,b_l)

◆ ut_pair_min()

UNIV_INLINE void ut_pair_min ( ulint *  min_hi,
ulint *  min_lo,
ulint  a_hi,
ulint  a_lo,
ulint  b_hi,
ulint  b_lo 
)

Calculate the minimum of two pairs.

Parameters
[out]min_hiMSB of the minimum pair
[out]min_loLSB of the minimum pair
[in]a_hiMSB of the first pair
[in]a_loLSB of the first pair
[in]b_hiMSB of the second pair
[in]b_loLSB of the second pair

◆ ut_print_name()

void ut_print_name ( FILE *  f,
const trx_t trx,
const char *  name 
)

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 (.), as in SQL database_name.identifier. in: table name to print

If the string contains a slash '/', the string will be output as two identifiers separated by a period (.), as in SQL database_name.identifier.

Parameters
fin: output stream
trxin: transaction
namein: name to print

◆ ut_strerr()

const char* ut_strerr ( dberr_t  num)

Convert an error number to a human readable text message.

The returned string is static and should not be freed or modified.

Returns
string, describing the error in: error number

The returned string is static and should not be freed or modified.

Parameters
[in]numInnoDB internal error number
Returns
string, describing the error

◆ ut_time()

ib_time_t ut_time ( void  )

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.

Returns
system time

◆ ut_time_monotonic()

ib_time_monotonic_t ut_time_monotonic ( void  )

Returns the number of seconds since epoch.

Uses the monotonic clock.

Returns
us since epoch or 0 if failed to retrieve

◆ ut_time_monotonic_ms()

ib_time_monotonic_ms_t ut_time_monotonic_ms ( void  )

Returns the number of milliseconds since epoch.

Uses the monotonic clock.

Returns
ms since epoch

◆ ut_time_monotonic_us()

ib_time_monotonic_us_t ut_time_monotonic_us ( void  )

Returns the number of microseconds since epoch.

Uses the monotonic clock.

Returns
us since epoch or 0 if failed to retrieve

◆ ut_ulint_cmp()

UNIV_INLINE int ut_ulint_cmp ( ulint  a,
ulint  b 
)

Compares two ulints.

Parameters
[in]aulint
[in]bulint
Returns
1 if a > b, 0 if a == b, -1 if a < b