21.8.4.2 Writing C API Threaded Client Programs

The client library is almost thread-safe. The biggest problem is that the subroutines in sql/net_serv.cc that read from sockets are not interrupt-safe. This was done with the thought that you might want to have your own alarm that can break a long read to a server. If you install interrupt handlers for the SIGPIPE interrupt, socket handling should be thread-safe.

To avoid aborting the program when a connection terminates, MySQL blocks SIGPIPE on the first call to mysql_library_init(), mysql_init(), or mysql_connect(). To use your own SIGPIPE handler, first call mysql_library_init(), then install your handler.

Current binary distributions should have both a normal client library, libmysqlclient, and a thread-safe library, libmysqlclient_r. For threaded clients, link against the latter library. If undefined symbol errors occur, in most cases this is because you have not included the thread libraries on the link/compile command.

The thread-safe client library, libmysqlclient_r, is thread-safe per connection. You can let two threads share the same connection with the following caveats:

You need to know the following if you have a thread that did not create the connection to the MySQL database but is calling MySQL functions:

When you call mysql_init(), MySQL creates a thread-specific variable for the thread that is used by the debug library (among other things). If you call a MySQL function before the thread has called mysql_init(), the thread does not have the necessary thread-specific variables in place and you are likely to end up with a core dump sooner or later. To avoid problems, you must do the following:

  1. Call mysql_library_init() before any other MySQL functions. It is not thread-safe, so call it before threads are created, or protect the call with a mutex.

  2. Arrange for mysql_thread_init() to be called early in the thread handler before calling any MySQL function. If you call mysql_init(), it will call mysql_thread_init() for you.

  3. In the thread, call mysql_thread_end() before calling pthread_exit(). This frees the memory used by MySQL thread-specific variables.

The preceding notes regarding mysql_init() also apply to mysql_connect(), which calls mysql_init().