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 при вызове вашей функции – параметр предоставляется, чтобы ваша реализация могла отслеживать глубину, если это необходимо.

Функция должна вернуть ссылку на массив, содержащий родительские классы в порядке. Имена классов должны быть результатом вызова 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 написал Брэндон Л. Блэк. Николас Кларк разработал интерфейс подключения, переработал реализацию Брэндона, чтобы она работала с ним, и написал этот документ.