Introduction

The Debug Sync Facility allows placement of synchronization points in the server code by using the DEBUG_SYNC macro:

open_tables(...)

DEBUG_SYNC(thd, "after_open_tables");

lock_tables(...)

When activated, a sync point can

Emit a signal(s) and/or
Wait for a signal

Nomenclature:

signal: An event identified by a name that a signal thread uses to notify the wait thread that waits on this event. When the signal thread notifies the wait thread, the signal name is copied into global list and the wait thread is signalled to wake up and proceed with further processing.
emit a signal: Signal thread wakes up wait thread or multiple wait threads that shall wait for the signal identified by a signal name. This signal thread copies the signal name into a global list and broadcasts the event which wakes the threads that wait for this event.
wait for a signal: Wait on a event identified by the signal name until the signal thread signals the event.

By default, all sync points are inactive. They do nothing (except to burn a couple of CPU cycles for checking if they are active).

A sync point becomes active when an action is requested for it. To do so, put a line like this in the test case file:

SET DEBUG_SYNC= 'after_open_tables SIGNAL opened WAIT_FOR flushed';

This activates the sync point 'after_open_tables'. It requests it to emit the signal 'opened' and wait for another thread to emit the signal 'flushed' when the thread's execution runs through the sync point.

For every sync point there can be one action per thread only. Every thread can request multiple actions, but only one per sync point. In other words, a thread can activate multiple sync points.

However a single action can emit several signals, example given:

SET DEBUG_SYNC= 'after_open_tables SIGNAL a,b,c WAIT_FOR flushed';

Suppose we had several connections, and each one could possibly emit signal 'after_latch'. Let assume there is another connection, which waits for the signal being emitted. If the waiting connection wanted to recognize, which connection emitted 'after_latch', then we could decide to always emit two signals: 'after_latch' and 'con$id', where con$id would describe uniquely each connection (con1, con2, ...). Then the waiting connection could simply perform SELECT @DEBUG_SYNC, and search for con* there. To remove such con$id from @DEBUG_SYNC, one could then simply perform SET DEBUG_SYNC= 'now WAIT_FOR con$id'.

Here is an example how to activate and use the sync points:

--connection conn1
SET DEBUG_SYNC= 'after_open_tables SIGNAL opened WAIT_FOR flushed';
send INSERT INTO t1 VALUES(1);
    --connection conn2
    SET DEBUG_SYNC= 'now WAIT_FOR opened';
    SET DEBUG_SYNC= 'after_abort_locks SIGNAL flushed';
    FLUSH TABLE t1;

When conn1 runs through the INSERT statement, it hits the sync point 'after_open_tables'. It notices that it is active and executes its action. It emits the signal 'opened' and waits for another thread to emit the signal 'flushed'.

conn2 waits immediately at the special sync point 'now' for another thread to emit the 'opened' signal.

If conn1 signals 'opened' before conn2 reaches 'now', conn2 will find the 'opened' signal. The wait thread shall not wait in this case.

When conn2 reaches 'after_abort_locks', it signals 'flushed', which lets conn1 awake and clears the 'flushed' signal from the global list. In case the 'flushed' signal is to be notified to multiple wait threads, an attribute NO_CLEAR_EVENT need to be specified with the WAIT_FOR in addition to signal the name as: SET DEBUG_SYNC= 'WAIT_FOR flushed NO_CLEAR_EVENT'; It is up to the user to ensure once when all the wait threads have processed the 'flushed' signal to clear/deactivate the signal using the RESET action of DEBUG_SYNC accordingly.

Normally the activation of a sync point is cleared when it has been executed. Sometimes it is necessary to keep the sync point active for another execution. You can add an execute count to the action:

SET DEBUG_SYNC= 'name SIGNAL sig EXECUTE 3';

This sets the signal point's activation counter to 3. Each execution decrements the counter. After the third execution the sync point becomes inactive.

One of the primary goals of this facility is to eliminate sleeps from the test suite. In most cases it should be possible to rewrite test cases so that they do not need to sleep. (But this facility cannot synchronize multiple processes.) However, to support test development, and as a last resort, sync point waiting times out. There is a default timeout, but it can be overridden:

SET DEBUG_SYNC= 'name WAIT_FOR sig TIMEOUT 10 EXECUTE 2';

TIMEOUT 0 is special: If the signal is not present, the wait times out immediately.

When a wait timed out (even on TIMEOUT 0), a warning is generated so that it shows up in the test result.

You can throw an error message and kill the query when a synchronization point is hit a certain number of times:

SET DEBUG_SYNC= 'name HIT_LIMIT 3';

Or combine it with signal and/or wait:

SET DEBUG_SYNC= 'name SIGNAL sig EXECUTE 2 HIT_LIMIT 3';

Here the first two hits emit the signal, the third hit returns the error message and kills the query.

For cases where you are not sure that an action is taken and thus cleared in any case, you can force to clear (deactivate) a sync point:

SET DEBUG_SYNC= 'name CLEAR';

If you want to clear all actions and clear the global signal, use:

SET DEBUG_SYNC= 'RESET';

This is the only way to reset the global signal to an empty string.

For testing of the facility itself you can execute a sync point just as if it had been hit:

SET DEBUG_SYNC= 'name TEST';

Formal Syntax

The string to "assign" to the DEBUG_SYNC variable can contain:

{RESET |
 <sync point name> TEST |
 <sync point name> CLEAR |
 <sync point name> {{SIGNAL <signal name>[, <signal name>]* |
                     WAIT_FOR <signal name> [TIMEOUT <seconds>]
                     [NO_CLEAR_EVENT]}
                    [EXECUTE <count>] &| HIT_LIMIT <count>}}

Here '&|' means 'and/or'. This means that one of the sections separated by '&|' must be present or both of them.

Activation/Deactivation

The facility is an optional part of the MySQL server. It is enabled in a debug server by default.

The Debug Sync Facility, when compiled in, is disabled by default. It can be enabled by a mysqld command line option:

--debug-sync-timeout[=default_wait_timeout_value_in_seconds]

'default_wait_timeout_value_in_seconds' is the default timeout for the WAIT_FOR action. If set to zero, the facility stays disabled.

The facility is enabled by default in the test suite, but can be disabled with:

mysql-test-run.pl ... --debug-sync-timeout=0 ...

Likewise the default wait timeout can be set:

mysql-test-run.pl ... --debug-sync-timeout=10 ...

The command line option influences the readable value of the system variable 'debug_sync'.

If the facility is not compiled in, the system variable does not exist.

If –debug-sync-timeout=0 the value of the variable reads as "OFF".

Otherwise the value reads as "ON - current signal: " followed by the current signal string, which can be empty.

The readable variable value is the same, regardless if read as global or session value.

Setting the 'debug-sync' system variable requires 'SUPER' privilege. You can never read back the string that you assigned to the variable, unless you assign the value that the variable does already have. But that would give a parse error. A syntactically correct string is parsed into a debug sync action and stored apart from the variable value.

Implementation

Pseudo code for a sync point:

#define DEBUG_SYNC(thd, sync_point_name)
          if (unlikely(opt_debug_sync_timeout))
            debug_sync(thd, STRING_WITH_LEN(sync_point_name))

The sync point performs a binary search in a sorted array of actions for this thread.

The SET DEBUG_SYNC statement adds a requested action to the array or overwrites an existing action for the same sync point. When it adds a new action, the array is sorted again.

A typical synchronization pattern

There are quite a few places in MySQL, where we use a synchronization pattern like this:

  mysql_mutex_lock(&mutex);
  thd->enter_cond(&condition_variable, &mutex, new_message);
  # if defined(ENABLE_DEBUG_SYNC)
  if (!thd->killed && !end_of_wait_condition)
     DEBUG_SYNC(thd, "sync_point_name");
  # endif
  while (!thd->killed && !end_of_wait_condition)
    mysql_cond_wait(&condition_variable, &mutex);
  mysql_mutex_unlock(&mutex);
  thd->exit_cond(old_message);

Here some explanations:

thd->enter_cond() is used to register the condition variable and the mutex in THD::current_cond/current_mutex. This is done to allow the thread to be interrupted (killed) from its sleep. Another thread can find the condition variable to signal and mutex to use for synchronization in this thread's THD.

thd->enter_cond() requires the mutex to be acquired in advance.

thd->exit_cond() unregisters the condition variable and mutex. Requires the mutex to be released in advance.

If you want to have a Debug Sync point with the wait, please place it behind enter_cond(). Only then you can safely decide, if the wait will be taken. Also you will have THD::proc_info correct when the sync point emits a signal. DEBUG_SYNC sets its own proc_info, but restores the previous one before releasing its internal mutex. As soon as another thread sees the signal, it does also see the proc_info from before entering the sync point. In this case it will be "new_message", which is associated with the wait that is to be synchronized.

In the example above, the wait condition is repeated before the sync point. This is done to skip the sync point, if no wait takes place. The sync point is before the loop (not inside the loop) to have it hit once only. It is possible that the condition variable is signaled multiple times without the wait condition to be true.

A bit off-topic: At some places, the loop is taken around the whole synchronization pattern:

  while (!thd->killed && !end_of_wait_condition)
  {
    mysql_mutex_lock(&mutex);
    thd->enter_cond(&condition_variable, &mutex, new_message);
    if (!thd->killed [&& !end_of_wait_condition])
    {
      [DEBUG_SYNC(thd, "sync_point_name");]
      mysql_cond_wait(&condition_variable, &mutex);
    }
    mysql_mutex_unlock(&mutex);
    thd->exit_cond(old_message);
  }

Note that it is important to repeat the test for thd->killed after enter_cond(). Otherwise the killing thread may kill this thread after it tested thd->killed in the loop condition and before it registered the condition variable and mutex in enter_cond(). In this case, the killing thread does not know that this thread is going to wait on a condition variable. It would just set THD::killed. But if we would not test it again, we would go asleep though we are killed. If the killing thread would kill us when we are after the second test, but still before sleeping, we hold the mutex, which is registered in THD. The killing thread would try to acquire the mutex before signaling the condition variable. Since the mutex is only released implicitly in mysql_cond_wait(), the signaling happens at the right place. We have a safe synchronization.

Co-work with the DBUG facility

When running the MySQL test suite with the –debug command line option, the Debug Sync Facility writes trace messages to the DBUG trace. The following shell commands proved very useful in extracting relevant information:

egrep 'query:|debug_sync_exec:' mysql-test/var/log/mysqld.1.trace

It shows all executed SQL statements and all actions executed by synchronization points.