XSLoader

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• ВЕРСИЯ
• СИНОПСИС
• ОПИСАНИЕ
  • Миграция из DynaLoader
  • Обратно совместимый шаблон
• Порядок инициализации: раннее загрузка load()
  • Самый сложный случай
• ДИАГНОСТИКА
• ОГРАНИЧЕНИЯ
• ИЗВЕСТНЫЕ ОШИБКИ
• ОШИБКИ
• СМОТРИТЕ ТАКЖЕ
• АВТОРЫ
• АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИЯ

НАЗВАНИЕ

XSLoader — динамическая загрузка библиотек C в Perl-код

ВЕРСИЯ

Версия 0.30

СИНОПСИС

package YourPackage;
require XSLoader;

XSLoader::load(__PACKAGE__, $VERSION);

ОПИСАНИЕ

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

Для более сложного интерфейса см. DynaLoader. Многие (большинство) функции DynaLoader не реализованы в XSLoader, например, dl_load_flags, не поддерживаемые XSLoader.

Миграция из DynaLoader

Типичный модуль, использующий DynaLoader, начинается так:

package YourPackage;
require DynaLoader;

our @ISA = qw( OnePackage OtherPackage DynaLoader );
our $VERSION = '0.01';
__PACKAGE__->bootstrap($VERSION);

Измените это на

package YourPackage;
use XSLoader;

our @ISA = qw( OnePackage OtherPackage );
our $VERSION = '0.01';
XSLoader::load(__PACKAGE__, $VERSION);

Другими словами: замените require DynaLoader на use XSLoader, удалите DynaLoader из @ISA, измените bootstrap на XSLoader::load. Не забудьте заключить имя вашего пакета в кавычки в строке XSLoader::load, и добавьте запятую (,) перед аргументами ($VERSION выше).

Конечно, если @ISA содержало только DynaLoader, нет необходимости в присваивании @ISA; кроме того, если вместо our используется более обратная совместимая конструкция

use vars qw($VERSION @ISA);

можно удалить эту ссылку на @ISA вместе с присваиванием @ISA.

Если в строке bootstrap не было указано $VERSION, последняя строка станет

XSLoader::load(__PACKAGE__);

в этом случае она может быть ещё упрощена до

XSLoader::load();

так как load будет использовать caller для определения пакета.

Обратно совместимый шаблон

Если вы хотите иметь и то, и другое, вам нужен более сложный шаблон.

package YourPackage;

our @ISA = qw( OnePackage OtherPackage );
our $VERSION = '0.01';
eval {
   require XSLoader;
    XSLoader::load(__PACKAGE__, $VERSION);
   1;
} or do {
   require DynaLoader;
   push @ISA, 'DynaLoader';
   __PACKAGE__->bootstrap($VERSION);
};

Скобки вокруг XSLoader::load() аргументов необходимы, так как мы заменили use XSLoader на require, поэтому компилятор не знает, что функция XSLoader::load() существует.

Этот шаблон использует XSLoader, если он есть; если используется с устаревшей версией Perl, у которой нет XSLoader, он переходит к использованию DynaLoader.

Порядок инициализации: раннее загрузка load()

Пропустите этот раздел, если функции XSUB должны вызываться только из других модулей; читайте его только если вы вызываете свои XSUB из кода в вашем модуле или имеете раздел BOOT: в вашем файле XS (см. ""Раздел BOOT: в perlxs"). То, что описано здесь, также применимо к интерфейсу DynaLoader.

Достаточно сложный модуль, использующий XS, будет иметь как Perl-код (определённый в YourPackage.pm), так и XS-код (определённый в YourPackage.xs). Если этот Perl-код вызывает этот XS-код, и/или этот XS-код вызывает Perl-код, следует быть осторожным с порядком инициализации.

Вызов XSLoader::load() (или bootstrap()) вызывает код загрузки модуля. Для модулей, созданных с помощью xsubpp (почти все модули), это имеет три побочных эффекта:

• Проводится проверка целостности, чтобы убедиться, что версии .pm и (скомпилированных) .xs частей совместимы. Если было указано $VERSION, оно используется для проверки. Если не указано, используется значение по умолчанию $XS_VERSION // $VERSION (в пространстве имён модуля)

• Функции XSUB становятся доступными из Perl

• Если в файле .xs присутствовал раздел BOOT:, код в нём вызывается.

Следовательно, если код в файле .pm вызывает эти функции XSUB, удобно, чтобы функции XSUB были установлены до определения Perl-кода; например, это делает прототипы функций XSUB видимыми для этого Perl-кода. В противном случае, если раздел BOOT: вызывает Perl-функции (или использует Perl-переменные), определённые в файле .pm, они должны быть определены до вызова XSLoader::load() (или bootstrap()).

Поскольку первый случай встречается гораздо чаще, имеет смысл переписать шаблон как

package YourPackage;
use XSLoader;
our ($VERSION, @ISA);

BEGIN {
   @ISA = qw( OnePackage OtherPackage );
   $VERSION = '0.01';

   # Put Perl code used in the BOOT: section here

   XSLoader::load(__PACKAGE__, $VERSION);
}

# Put Perl code making calls into XSUBs here

Самый сложный случай

Если взаимозависимость вашего раздела BOOT: и Perl-кода более сложна (например, раздел BOOT: вызывает Perl-функции, которые вызывают XSUB с прототипами), полностью удалите раздел BOOT: . Замените его функцией onBOOT(), и вызовите её так:

package YourPackage;
use XSLoader;
our ($VERSION, @ISA);

BEGIN {
   @ISA = qw( OnePackage OtherPackage );
   $VERSION = '0.01';
   XSLoader::load(__PACKAGE__, $VERSION);
}

# Put Perl code used in onBOOT() function here; calls to XSUBs are
# prototype-checked.

onBOOT;

# Put Perl initialization code assuming that XS is initialized here

ДИАГНОСТИКА

Can't find '%s' symbol in %s

(F) Символ загрузки не был найден в модуле расширения.

Can't load '%s' for module %s: %s

(F) Загрузка или инициализация модуля расширения не удались. Следует подробная ошибка.

Undefined symbols present after loading %s: %s

(W) Как следует из сообщения, некоторые символы остаются неопределёнными, хотя модуль расширения был правильно загружен и инициализирован. Далее следует список неопределённых символов.

ОГРАНИЧЕНИЯ

Чтобы максимально уменьшить накладные расходы, проверяется только одно возможное расположение расширения DLL (это расположение, куда make install поместил бы DLL). Если не найдено, поиск DLL прозрачно делегируется DynaLoader, который ищет DLL в списке @INC.

В частности, это применимо к структуре @INC, используемой для тестирования ещё не установленных расширений. Это означает, что выполнение не установленных расширений может иметь гораздо больше накладных расходов, чем выполнение тех же расширений после make install.

ИЗВЕСТНЫЕ ОШИБКИ

Новый упрощённый способ вызова XSLoader::load() без аргументов вообще не работает в Perl 5.8.4 и 5.8.5.

ОШИБКИ

Пожалуйста, сообщайте об ошибках и предложениях по функциям с помощью утилиты perlbug(1).

СМОТРИТЕ ТАКЖЕ

DynaLoader

АВТОРЫ

Илья Захаревич изначально извлёк XSLoader из DynaLoader.

Версия CPAN в настоящее время поддерживается Sébastien Aperghis-Tramoni <sebastien@aperghis.net>.

Предыдущий основной разработчик был Michael G Schwern <schwern@pobox.com>.

АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИЯ

Авторские права (C) 1990-2011 Larry Wall и другие.

Эта программа является свободной программой; вы можете перераспределять её и/или изменять её на тех же условиях, что и Perl сам по себе.