В этой секции рассмотрена архитектура плагинов
mysqlnd
.
Обзор MySQL Native Driver
Перед началом разработки плагинов
mysqlnd
, полезно ознакомиться, как сам по
себе организован mysqlnd
.
Mysqlnd
состоит из следующих модулей:
Модули статистики | mysqlnd_statistics.c |
---|---|
Соединение | mysqlnd.c |
Результирующий набор | mysqlnd_result.c |
Метаданные результирующего набора | mysqlnd_result_meta.c |
Оператор | mysqlnd_ps.c |
Сеть | mysqlnd_net.c |
Протокол обмена | mysqlnd_wireprotocol.c |
Объектно-ориентированная парадигма 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 *
указателя на плагин.
В следующей таблице показано, как вычислить положение указателя для конкретного плагина:
Адрес памяти | Содержимое |
---|---|
0 | Начало объекта mysqlnd (C struct) |
n | Конец объекта mysqlnd (C struct) |
n + (m x sizeof(void*)) | void* для данных объекта плагина номер m |
Если вы планируете делать подкласс от одного из конструкторов объекта
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
имеет
ряд полезных свойств, таких как использование отладочного
модуля управления памятью в неотладочных сборках.
Когда создавать подкласс? | Каждый экземпляр имеет свою собственную таблицу функций? | Как создавать подкласс? | |
---|---|---|---|
Соединение (MYSQLND) | MINIT | Нет | mysqlnd_conn_get_methods() |
Результирующий набор (MYSQLND_RES) | MINIT or later | Да | mysqlnd_result_get_methods() или методом объекта, манипулирующим таблицей функций |
Результирующий набор (MYSQLND_RES_METADATA) | MINIT | Нет | mysqlnd_result_metadata_get_methods() |
Оператор (MYSQLND_STMT) | MINIT | Нет | mysqlnd_stmt_get_methods() |
Сеть (MYSQLND_NET) | MINIT или позже | Да | mysqlnd_net_get_methods() или методом объекта, манипулирующим таблицей функций |
Протокол обмена (MYSQLND_PROTOCOL) | MINIT или позже | Да | mysqlnd_protocol_get_methods() или методом объекта, манипулирующим таблицей функций |
Вы не должны манипулировать таблицей функций после MINIT, если это прямо не разрешено в таблице выше.
Некоторые классы содержат указатель на таблицу функций методов. Все экземпляры подобных классов должны делить одну и ту же таблицу функций. Для того, чтобы избежать хаоса, особенно в многопоточном окружении, управлять такими таблицами функций стоит только во время MINIT.
Прочие классы используют копии глобально разделённых таблиц функций. Таблица функций создаётся одновременно с объектом. Каждый объект использует свою таблицу. Это даёт вам две возможности: вы можете управлять таблицей функций по умолчанию для объекта во время MINIT, а также вы можете изменять методы объекта не затрагивая другие экземпляры этого же класса.
Преимущество разделяемой таблицы функций в производительности, так как нет нужды копировать таблицу функций отдельно для каждого объекта.
Тип | Размещение, создание, сброс | Может быть изменено? | Вызывающий |
---|---|---|---|
Connection (MYSQLND) | mysqlnd_init() | Нет | mysqlnd_connect() |
Результирующий набор (MYSQLND_RES) | Размещение:
Сброс и повторная инициализация во время:
|
Да, но вызовите родителя! |
|
Метаданные результирующего набора (MYSQLND_RES_METADATA) | Connection::result_meta_init() | Да, но вызовите родителя! | Result::read_result_metadata() |
Оператор (MYSQLND_STMT) | Connection::stmt_init() | Да, но вызовите родителя! | Connection::stmt_init() |
Сеть (MYSQLND_NET) | mysqlnd_net_init() | Нет | Connection::init() |
Протокол обмена (MYSQLND_PROTOCOL) | mysqlnd_protocol_init() | Нет | Connection::init() |
Настоятельно рекомендуется не заменять конструктор
целиком. Конструкторы производят выделение памяти.
Выделение памяти жизненно необходимо для API плагинов
mysqlnd
и для логики объекта
mysqlnd
. Если вам не страшны
предупреждения и хотите сильно поменять конструктор, то
хотя бы вызовите родительский конструктор прежде, чем что-либо делать.
Несмотря на предупреждения, это бывает полезным для конструктора подкласса. Конструкторы — отличное место для изменения таблицы функций для объектов, которые не работают с разделённой таблицу, например, результирующий набор, сеть, протокол обмена.
Производный метод должен вызвать родительский? | Деструктор | |
---|---|---|
Соединение | да, после выполнения метода | free_contents(), end_psession() |
Результирующий набор | да, после выполнения метода | free_result() |
Метаданные результирующего набора | да, после выполнения метода | free() |
Оператор | да, после выполнения метода | dtor(), free_stmt_content() |
Сеть | да, после выполнения метода | free() |
Протокол обмена | да, после выполнения метода | free() |
Деструкторы являются подходящим местом, чтобы освободить ресурсы, занимаемые
свойствами
mysqlnd_plugin_get_plugin_<object>_data()
.
Перечисленные деструкторы могут не совпадать с актуальными методами
mysqlnd
для очистки самого объекта. Однако они являются самым лучшим
местом, куда вы можете вклиниться для очистки данных своего плагина. Так же как и
с конструкторами, вы можете полностью переопределить эти методы, но делать это не
рекомендуется. Если вам необходимо вставить в каждый из перечисленных методов
очистку данных своего плагина, то необходимо обеспечить запуск родительских
методов mysqlnd
.
Для плагинов рекомендуют метод — выполнить код очистки данных плагина и сразу после этого вызывать родительский метод.