perlmroapi

СОДЕРЖАНИЕ

• ИМЯ
• ОПИСАНИЕ
• Обработчики
• Кэширование
• Примеры
• АВТОРЫ

ИМЯ

perlmroapi - интерфейс плагина Perl для обработки порядка разрешения методов

ОПИСАНИЕ

Начиная с Perl 5.10.1, появился новый интерфейс для подключения и использования порядков разрешения методов, отличных от стандартного (линейный поиск по глубине). Порядок разрешения методов C3, добавленный в 5.10.0, был повторно реализован как плагин без изменения интерфейса в пространстве Perl.

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

struct mro_alg {
    AV *(*resolve)(pTHX_ HV *stash, U32 level);
    const char *name;
    U16 length;
    U16 kflags;
    U32 hash;
};

и вызвав Perl_mro_register:

Perl_mro_register(aTHX_ &my_mro_alg);

resolve

Указатель на функцию линейной функции, описанную ниже.

name

Имя MRO, либо в ISO-8859-1, либо в UTF-8.

length

Длина имени.

kflags

Если имя указано в UTF-8, установите это значение в HVhek_UTF8. Значение передаётся напрямую как параметр kflags в hv_common().

hash

Предварительно вычисленное значение хеша для имени MRO или 0.

Обработчики

Функция resolve вызывается для генерации линейного ISA для данного хранилища, используя данный MRO. Она вызывается с указателем на хранилище и уровнем level 0. Ядро всегда устанавливает level в 0, когда вызывает вашу функцию. Параметр предоставлен, чтобы позволить вашей реализации отслеживать глубину, если это необходимо для рекурсии.

Функция должна вернуть ссылку на массив, содержащий строковые SV, указывающие имена родительских классов в порядке. Имена классов должны быть результатом вызова HvENAME() для хранилища. В тех случаях, когда HvENAME() возвращает null, следует использовать HvNAME().

Вызывающая сторона отвечает за увеличение счётчика ссылок массива, возвращённого, если она хочет сохранить структуру. Таким образом, если вы создали временное значение, на которое у вас нет указателя, используйте sv_2mortal(), чтобы гарантировать его правильное удаление. Если вы кэшировали возвращаемое значение, то верните указатель на него без изменения счётчика ссылок.

Кэширование

Вычисление MRO может быть дорогостоящим. Реализация предоставляет кэш, в котором вы можете сохранить одно SV *, или любой тип, который может быть приведён к SV *, например, AV *. Для чтения своего частного значения используйте макрос MRO_GET_PRIVATE_DATA(), передав ему структуру mro_meta из хранилища и указатель на вашу структуру mro_alg:

meta = HvMROMETA(stash);
private_sv = MRO_GET_PRIVATE_DATA(meta, &my_mro_alg);

Для установки вашего частного значения вызовите Perl_mro_set_private_data():

Perl_mro_set_private_data(aTHX_ meta, &c3_alg, private_sv);

Кэш частных данных перенимает управление ссылкой на private_sv, аналогично тому, как hv_store() перенимает управление ссылкой на значение, которое вы ему передаёте.

Примеры

Примеры реализации MRO см. в S_mro_get_linear_isa_c3() и разделе BOOT: файла ext/mro/mro.xs, а также S_mro_get_linear_isa_dfs() в mro_core.c

АВТОРЫ

Реализацию C3 MRO и переключаемых MRO в ядре Perl написал Брэндон Л. Блэк. Николас Кларк создал интерфейс плагинов, переработал реализацию Брэндона, чтобы она работала с ним, и написал этот документ.