MySQL Internals Manual  /  Test Synchronization  /  Error Injection

24.4 Error Injection

Note: The ERROR_INJECT framework has been removed in an early 6.0 version. It is also not available from 5.5 upwards. It might be added back later.

The error injection method is based on the DBUG framework just like the Dbug Sleep method. In the code you can use the following macros:


'keyword' is the debug keyword that you set in the test file with:

 SET SESSION debug='+d,keyword1,keyword2,keyword3';

'value' is an unsigned long integer value. It is stored in THD::error_inject_value by SET_ERROR_INJECT_VALUE(value) and examined by the other *_VALUE* macros.

All of the ERROR_INJECT_* macros can/must be used in an expression. Their value is 0 (zero) in most cases. Exceptions are mentioned below.

Most of the ERROR_INJECT_* macros remove the keyword from the debug keyword list or clear THD::error_inject_value respectively before they executes their action. This means each of them will never execute twice within one SQL statement. But if multiple non-VALUE macros are run through in a statement, each can execute once if they use distinct keywords. There is just one THD::error_inject_value, not a list. So when any *_VALUE* macro clears it, all other *_VALUE* macros are disabled. Unless a new value is set by SET_ERROR_INJECT_VALUE somewhere. Obvious exceptions of keyword/value removal are SET_ERROR_INJECT_VALUE and the CRASH macros.

The ERROR_INJECT_ACTION macro is very similar to the DBUG_EXECUTE_IF macro (see the "Dbug Sleep section). But remember the removal of the keyword/value.

The ERROR_INJECT_VALUE_ACTION is similar to ERROR_INJECT_ACTION. But it is controlled by the thread local value set by SET_ERROR_INJECT_VALUE. Also the action must be written as an expression. You can call a function that returns a value valid in the expression in which ERROR_INJECT_VALUE_ACTION appears. But if you want to open a block "{...}" you need to make an expression from it: "({...}, 0)". Also, if ERROR_INJECT_VALUE_ACTION is executed, it returns the value that the 'action' expression returns, not just 0 (zero) like ERROR_INJECT_ACTION does.

ERROR_INJECT_CRASH and ERROR_INJECT_VALUE_CRASH are pretty self-explanatory.

ERROR_INJECT and ERROR_INJECT_VALUE are for expression evaluation. They return 1 if the keyword is set or the value matches THD::error_inject_value respectively. Otherwise 0.

SET_ERROR_INJECT_VALUE copies the argument to THD::error_inject_value.

Downsides: The error injection method is NOT enabled in the server by default. You need to ./configure --with-error-inject

The method is currently not used in the standard test suite anywhere. So you cannot copy and modify an example, but have to learn it the hard way.

When controlling error injection from the test files, explicit debug keywords are required, which has the same downsides as mentioned under Dbug Sleep.

If not using the ERROR_INJECT macros in an expression, expect the compiler warning "statement has no effect".