Архитектура плагинов MySQL Native Driver

В секции рассматривается архитектура плагинов драйвера mysqlnd.

Обзор MySQL Native Driver

Перед началом разработки плагинов для драйвера mysqlnd полезно узнать, как организован сам драйвер mysqlnd. Mysqlnd состоит из следующих модулей:

Объектно-ориентированная парадигма C

На уровне кода, mysqlnd использует паттерн C для реализации объектно-ориентированного подхода.

В C объекты описывают используя struct. Члены структуры являются свойствами объекта. Члены структуры, указывающие на функции, являются методами.

В отличие от таких языков как C++ или Java, в C нет фиксированных правил наследования. Однако существуют некоторые договорённости, которым необходимо следовать, но это мы обсудим позже.

Жизненный цикл PHP

При рассмотрении жизненного цикла PHP существует два основных цикла:

• Цикл старта и остановки движка PHP
• Цикл обработки запроса

При старте движка PHP, первым делом вызывается функция инициализации модулей (MINIT) для каждого зарегистрированного модуля. Это позволяет каждому модулю установить переменные и выделить ресурсы, которые будут задействованы все время жизни процесса движка PHP. Когда движок PHP выключается, он вызывает функцию остановки модулей (MSHUTDOWN) для каждого модуля.

На протяжении жизненного цикла движка PHP, он принимает некоторое количество запросов. Каждый запрос порождает новый жизненный цикл. На каждый запрос, движок PHP вызывает функцию инициализации для каждого модуля. Модуль может предпринять выставление переменных и выделение ресурсов, требуемых для обслуживания запроса. По окончании жизни запроса, движок вызывает функцию остановки запроса (RSHUTDOWN) для каждого модуля, что позволяет им произвести необходимые чистки.

Как работает плагин

Плагин mysqlnd работает перехватывая вызовы модулей, использующих mysqlnd, к mysqlnd. Это достигается подменой таблицы функций mysqlnd на созданную плагином.

Следующий код демонстрирует замену таблицы функций mysqlnd:

/* хранилище оригинальной таблицы */
struct st_mysqlnd_conn_methods org_methods;

void minit_register_hooks(TSRMLS_D) {
  /* активная таблица функций */
  struct st_mysqlnd_conn_methods * current_methods
    = mysqlnd_conn_get_methods();

  /* бэкап оригинальной таблицы */
  memcpy(&org_methods, current_methods,
    sizeof(struct st_mysqlnd_conn_methods);

  /* установка новых методов */
  current_methods->query = MYSQLND_METHOD(my_conn_class, query);
}

Манипуляцией с таблицей функций соединения необходимо заниматься на этапе инициализации модуля (MINIT). Таблица функций — глобальный разделяемый ресурс. В многопоточном окружении, со сборкой TSRM, манипуляция глобальным разделяемым ресурсом на этапе обработки запроса вызовет конфликты.

Замечание: Не используйте логику, которая связана с фиксированным размером при манипуляции с таблицей функций mysqlnd. Всегда добавляйте новые методы в конец таблицы, так как сама таблица может в будущем в любой момент измениться.

Вызов родительских методов

Если записи оригинальной таблицы функций сохранились, остаётся возможность вызвать оригинальный метод — родительский.

В отдельных случаях, например, для Connection::stmt_init(), жизненно важно сначала вызвать родительский метод, и только потом делать что-либо в новом методе.

MYSQLND_METHOD(my_conn_class, query)(MYSQLND *conn,
  const char *query, unsigned int query_len TSRMLS_DC) {

  php_printf("my_conn_class::query(query = %s)\n", query);

  query = "SELECT 'query rewritten' FROM DUAL";
  query_len = strlen(query);

  return org_methods.query(conn, query, query_len); /* возврат с вызовом родителя */
}

Расширение свойств

Объекты mysqlnd представлены как C struct. Невозможно добавить члена в C struct во время исполнения. Пользователи объектов mysqlnd не могут просто добавить свойства объекту.

Произвольные данные (свойства) могут быть добавлены к объекту mysqlnd с использованием соответствующей функции из семейства mysqlnd_plugin_get_plugin_<object>_data(). При размещении объекта mysqlnd резервируется место в конце объекта для удержания void * указателя на произвольные данные. mysqlnd резервирует место для одного void * указателя на плагин.

В следующей таблице показано, как вычислить положение указателя для конкретного плагина:

Если вы планируете делать подкласс от одного из конструкторов объекта mysqlnd, которые разрешены, имейте это в виду!

Следующий код демонстрирует расширение свойств:

/* Любые данные, которые мы хотим добавить */
typedef struct my_conn_properties {
  unsigned long query_counter;
} MY_CONN_PROPERTIES;

/* идентификатор плагина */
unsigned int my_plugin_id;

void minit_register_hooks(TSRMLS_D) {
  /* получаем уникальный идентификатор плагина */
  my_plugin_id = mysqlnd_plugin_register();
  /* snip - see Extending Connection: methods */
}

static MY_CONN_PROPERTIES** get_conn_properties(const MYSQLND *conn TSRMLS_DC) {
  MY_CONN_PROPERTIES** props;
  props = (MY_CONN_PROPERTIES**)mysqlnd_plugin_get_plugin_connection_data(
    conn, my_plugin_id);
  if (!props || !(*props)) {
    *props = mnd_pecalloc(1, sizeof(MY_CONN_PROPERTIES), conn->persistent);
    (*props)->query_counter = 0;
  }
  return props;
}

Разработчик плагина отвечает за управление памятью данных плагина.

Рекомендуется использовать управление памятью mysqlnd для данных плагина. Эти функции именуются используя такие соглашения: mnd_*loc(). Управление памятью mysqlnd имеет ряд полезных свойств, таких как использование отладочного модуля управления памятью в неотладочных сборках.

Вы не должны манипулировать таблицей функций после MINIT, если это прямо не разрешено в таблице выше.

Некоторые классы содержат указатель на таблицу функций методов. Все экземпляры подобных классов должны делить одну и ту же таблицу функций. Для того, чтобы избежать хаоса, особенно в многопоточном окружении, управлять такими таблицами функций стоит только во время MINIT.

Прочие классы используют копии глобально разделённых таблиц функций. Таблица функций создаётся одновременно с объектом. Каждый объект использует свою таблицу. Это даёт вам две возможности: вы можете управлять таблицей функций по умолчанию для объекта во время MINIT, а также вы можете изменять методы объекта не затрагивая другие экземпляры этого же класса.

Преимущество разделяемой таблицы функций в производительности, так как нет нужды копировать таблицу функций отдельно для каждого объекта.

Настоятельно рекомендуется не заменять конструктор целиком. Конструкторы производят выделение памяти. Выделение памяти жизненно необходимо для API плагинов mysqlnd и для логики объекта mysqlnd. Если вам не страшны предупреждения и хотите сильно поменять конструктор, то хотя бы вызовите родительский конструктор прежде, чем что-либо делать.

Несмотря на предупреждения, это бывает полезным для конструктора подкласса. Конструкторы — отличное место для изменения таблицы функций для объектов, которые не работают с разделённой таблицу, например, результирующий набор, сеть, протокол обмена.

Деструкторы являются подходящим местом, чтобы освободить ресурсы, занимаемые свойствами mysqlnd_plugin_get_plugin_<object>_data().

Перечисленные деструкторы могут не совпадать с актуальными методами mysqlnd для очистки самого объекта. Однако они являются самым лучшим местом, куда вы можете вклиниться для очистки данных своего плагина. Так же как и с конструкторами, вы можете полностью переопределить эти методы, но делать это не рекомендуется. Если вам необходимо вставить в каждый из перечисленных методов очистку данных своего плагина, то необходимо обеспечить запуск родительских методов mysqlnd.

Для плагинов рекомендуют метод — выполнить код очистки данных плагина и сразу после этого вызывать родительский метод.