24.2.5 プラグインのための MySQL サービス

MySQL サーバープラグインは、サーバーの「サービス」にアクセスできます。サービスインタフェースは、プラグインが呼び出すことができるサーバー機能を公開します。これはプラグイン API を補完し、次の特徴があります。

• サービスによって、プラグインは通常の関数呼び出しを使用して、サーバー内部のコードにアクセスできます。

• サービスには移植性があり、複数のプラットフォームで動作します。

• インタフェースにはバージョン管理メカニズムがあるため、サーバーによってサポートされるサービスバージョンを、プラグインバージョンに対してロード時にチェックできます。バージョン管理により、サーバーが提供するサービスのバージョン、およびプラグインが予期または必要とするサービスのバージョンの間の互換性の問題が防止されます。

現在のサービスには次のものが含まれており、ほかのサービスも実装できます。

• my_plugin_log_service: プラグインがエラーの報告およびエラーメッセージの指定を行うことができるサービス。サーバーはエラーログにメッセージを書き込みます。

• my_snprintf: プラットフォーム間で一貫性のある結果を生成する、文字列の書式設定サービス。

• my_thd_scheduler: プラグインがスレッドスケジューラを選択するためのサービス。

• mysql_string: 文字列操作のためのサービス。

• thd_alloc: メモリー割り当てサービス。

• thd_wait: プラグインがスリープまたは停止することを報告するためのサービス。

プラグインサービスインタフェースとプラグイン API の違いは次のとおりです。

• プラグイン API では、サーバーからプラグインを使用できます。呼び出しを開始するのは、プラグインを呼び出すサーバーです。これにより、サーバー機能の拡張、またはサーバーの処理に関する通知を受け取るための登録をプラグインで行うことができます。

• プラグインサービスインタフェースでは、プラグインはサーバー内部のコードを呼び出すことができます。呼び出しを開始するのは、サービス関数を呼び出すプラグインです。これにより、多くのプラグインがサーバーにすでに実装されている機能を使用できるようになり、プラグインに個別に機能を実装する必要がなくなります。

サーバーを変更して新しいサービスを追加する開発者は、プラグインのための MySQL サービスを参照してください。

このセクションの残りの部分では、サービスとして使用可能なサーバー機能をプラグインで使用する方法について説明します。my_snprintf サービスを使用する「デーモン」プラグインの例のソースも参照してください。このプラグインは、MySQL ソース配布の plugin/daemon_example ディレクトリにあります。

存在するサービスおよびサービスが提供する関数を確認するには、MySQL ソース配布の include/mysql ディレクトリ内を参照してください。関連するファイルは次のとおりです。

• plugin.h は services.h をインクルードします。

• services.h は、使用可能なすべてのサービス固有のヘッダーファイルをインクルードする「包括的な」ヘッダーです。

• サービス固有のヘッダーには、service_my_snprintf.h または service_thd_alloc.h のような名前が付いています。

各サービス固有ヘッダーには、対象となるサービスの完全な使用法を示すドキュメントを提供するコメントがあり、使用可能なサービス関数、それらの呼び出しシーケンス、および戻り値が含まれています。

プラグイン内からサービスを使用するには、サービス関連の情報にアクセスするための plugin.h ヘッダーファイルをプラグインのソースファイルでインクルードする必要があります。

#include <mysql/plugin.h>

これによってセットアップのコストが増えるわけではありません。このファイルにはすべてのプラグインで必要となる定義および構造体が含まれているため、プラグインはいずれにしてもこのファイルをインクルードする必要があります。

サービスにアクセスするために、プラグインはほかの関数と同様にサービス関数を呼び出します。たとえば、出力のために文字列を書式設定してバッファーに入れるには、同じ名前のサービスによって提供されている my_snprintf() 関数を呼び出します。

char buffer[BUFFER_SIZE];

my_snprintf(buffer, sizeof(buffer), format_string, argument_to_format, ...);

サーバーがエラーログに書き込むエラーを報告するには、最初にエラーレベルを選択します。mysql/service_my_plugin_log.h はこれらのレベルを定義しています。

enum plugin_log_level
{
  MY_ERROR_LEVEL,
  MY_WARNING_LEVEL,
  MY_INFORMATION_LEVEL
};

次に、my_plugin_log_message() を呼び出します。

int my_plugin_log_message(MYSQL_PLUGIN *plugin, enum plugin_log_level level,
                          const char *format, ...);

例:

my_plugin_log_message(plugin_ptr, MY_ERROR_LEVEL, "Cannot initialize plugin");

プラグインをビルドするときに、libmysqlservices ライブラリでリンクする必要があります。リンク時には -lmysqlservices フラグを使用します。たとえば CMake の場合、最上位レベルの CMakeLists.txt ファイルに次の内容を指定します。

FIND_LIBRARY(MYSQLSERVICES_LIB mysqlservices 
 PATHS "${MYSQL_SRCDIR}/libservices" NO_DEFAULT_PATH)

プラグインのソースが格納されているディレクトリの CMakeLists.txt ファイルに次の内容を指定します。

# the plugin needs the mysql services library for error logging
TARGET_LINK_LIBRARIES (your_plugin_library_name ${MYSQLSERVICES_LIB})