Author: YuanZhen
在MySQL的开发过程中为了验证某个需要多线程之间配合的功能时，就需要有一种机制使开发人员能够控制每个线程的执行流程，完成多个线程之间的配合，验证特殊并发逻辑下代码处理的正确性。MySQL 提供了DEBUG_SYNC 功能，就是让开发者可以在MySQL服务器代码中通过DEBUG_SYNC宏定义同步点的。你可以在代码中加入你希望定义的同步点。
DEBUG_SYNC的功能，默认是关闭的。除非在启动的时候指定了–debug-sync-timeout[=N] 选项，N是可选的，可以指定也可以不指定。不指定的话，默认是300秒。
#define DEBUG_SYNC_DEFAULT_WAIT_TIMEOUT 300
这个选项是启动时变量，为了能在测试中使用DEBUG_SYNC功能，必须在启动的时候指定–debug-sync-timeout[=N] 选项。这个参数有两个作用： 1) 其一是指定wait_for一个同步点的最大等待时间（单位：秒），若超过这个时间就会timeout； 2) 另一个是打开／关闭DEBUG_SYNC功能的选项，当其后的参数N为0时，就关闭了DEBUG_SYNC功能。
其核心代码主要通过定义的宏DEBUG_SYNC做为入口，其定义如下：
#define DEBUG_SYNC(_thd_, _sync_point_name_) \
do { \
if (unlikely(opt_debug_sync_timeout)) \
debug_sync(_thd_, STRING_WITH_LEN(_sync_point_name_)); \
} while (0)
这个宏的源码实现，主要是通过定义一个同步点（这个同步点是通过这里定义的名字来表示的_sync_point_name_），线程就会在这个同步点执行定义的行为动作，比如是在这个同步点发信号给等在其他同步点的线程、还是等在某个定义的事件上。在DEBUG_SYNC目前同步点的行为只定义了给其它同步点发信号、和等在某个信号上。其实现的主要数据结构如下：
struct st_debug_sync_action {
ulong activation_count = 0; /* max(hit_limit, execute) */
ulong hit_limit = 0; /* hits before kill query */
ulong execute = 0; /* executes before self-clear */
ulong timeout = 0; /* wait_for timeout */
String signal; /* signal to emit */
String wait_for; /* signal to wait for */
String sync_point; /* sync point name */
bool need_sort = false; /* if new action, array needs sort */
bool clear_event = false; /* do not clear signal if false */
};
而其功能的实现主要就是通过debug_sync_execute函数来实现的。以下是在debug_sync中调用debug_sync_find和debug_sync_execute的代码片段。
if (ds_control->ds_active &&
(action = debug_sync_find(ds_control->ds_action, ds_control->ds_active,
sync_point_name, name_len)) &&
action->activation_count) {
/* Sync point is active (action exists). */
debug_sync_execute(thd, action);
/* Statistics. */
ds_control->dsp_executed++;
/* If action became inactive, remove it to shrink the search array. */
if (!action->activation_count) debug_sync_remove_action(ds_control, action);
}
首先在debug_sync_find里通过二分查找是否有同步点的要执行的行为动作，若是找到的话，就通过debug_sync_execute函数去执行。在debug_sync_execute根据定义的同步点执行次数，去判断是否达到了执行的次数，若没有达到执行的次数，则会在每次都会等这个event的信号。
if (action->execute) {
…
action->execute--;
…
/** 如果本线程也需要等待某个信号，它首先把自己在processlist表里的状态设置成等待状态，为了能让其它线程能及时的看到*/
if (action->wait_for.length()) {
…
debug_sync_thd_proc_info(thd, ds_control->ds_proc_info);
}
/* 如果定义了需要唤醒的同步点，就需要把这些唤醒的同步点设置成signaled，加入到全局变量中，然后唤醒其它等待线程*/
if (action->signal.length()) {
…
/**把这些唤醒的同步点设置成signaled，加入到全局变量中*/
if (!s.empty()) add_signal_event(&s);
/* 唤醒等待同步点读线程*/
mysql_cond_broadcast(&debug_sync_global.ds_cond);
}
/* 然后自己再等待在自己定义的事件上，等待被唤醒*/
if (action->wait_for.length()) {
…
while (!is_signalled(&wait_for) && !thd->killed &&
opt_debug_sync_timeout) {
error = mysql_cond_timedwait(&debug_sync_global.ds_cond,
&debug_sync_global.ds_mutex, &abstime);
…
}
/* 如果定义了 CLAER行为则清除等待事件，以后再执行到此不必再等待该事件 */
if (action->clear_event) clear_signal_event(&wait_for);
}
/* 如果定义了 HIT_LIMIT行为，则达到了指定的次数，会返回错误消息，并kill这个线程 */
if (action->hit_limit) {
if (!--action->hit_limit) {
thd->killed = THD::KILL_QUERY;
my_error(ER_DEBUG_SYNC_HIT_LIMIT, MYF(0));
}
。。。
}
…
}
在源码中使用的例子如下所示，开发者可以在任意的位置加入同步点，并给同步点命名，这样这个同步点就可以在接下来的测试案例中使用了。
open_tables(...)
DEBUG_SYNC(thd, "after_open_tables");
lock_tables(...)
测试场景使用的语法，可以参考 https://dev.mysql.com/doc/internals/en/syntax-debug-sync-values.html。在测试场景中，同步点的使用主要有以下几种情况： 1）SET DEBUG_SYNC=‘sync point name SIGNAL signal name WAIT_FOR signal name 是最常用的方法。 比如： SET DEBUG_SYNC= ‘after_open_tables SIGNAL opened WAIT_FOR flushed’; 大部分情况下同步点都是未激活状态，当对整个同步点请求某个行为时就激活了这个同步点。比如上面这个例子，当执行到同步点after_open_tables后会向等待opened事件发送信号同时等在flushed时间上时，就激活了after_open_tables同步点。
2）SET DEBUG_SYNC= ‘after_open_tables SIGNAL a,b,c WAIT_FOR flushed’; 这中用法和1）的主要区别就是一次唤醒多个事件a、b、c，其它和1）相同
3）SET DEBUG_SYNC= ‘WAIT_FOR flushed NO_CLEAR_EVENT’; 默认情况下, 当等待线程收到唤醒的信号后，就会从全局信号中把这个信号清除。但如果等待这个信号的线程有多个的时候，就不能其中一个线程被唤醒后马上清除它，这样就需要在等待线程，在等待信号上指定NO_CLEAR_EVENT。直到所有的等待线程都唤醒了，然后再通过SET DEBUG_SYNC= ‘RESET’; 去清除这个event的唤醒信号。
4）SET DEBUG_SYNC= ‘name SIGNAL sig EXECUTE 3’; 一般情况下，等待线程被激活执行完后，马上就清除唤醒等待线程的信号。为了不立马清除激活信号，我们可以通过关键字EXECUTE指定执行的次数，执行完指定的次数后，才清除激活信号。比如这个例子指定了执行3次、每执行完一次这个数字就会减1，直到减到0为止。
5） SET DEBUG_SYNC= ‘name WAIT_FOR sig TIMEOUT 10 EXECUTE 2’; 在MySQL启动的时候，可以通过参数debug-sync-timeout指定一个等待事件的超时时间，也可以通过TIMEOUT 关键字为每个等待事件单独指定超时时间。这个例子就是等待线程最长等待10秒，若超过10秒还没收到唤醒等待事件的信号，就会超时不再等待了。
6）SET DEBUG_SYNC= ‘name SIGNAL sig EXECUTE 2 HIT_LIMIT 3’; 如果你想在执行完指定的次数后，返回一个错误消息并且中断这个线程的话，可以通过HIT_LIMIT来指定。这个例子中就是在执行完3次后，会返回一个错误消息并且中断这个查询。
7）SET DEBUG_SYNC= ‘name CLEAR’; 这个是可以在任何时候都清除name指定的同步点，不管它执行了还是没执行。
https://dev.mysql.com/doc/internals/en/debug-sync-facility.html