XSLoader

СОДЕРЖАНИЕ

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

НАЗВАНИЕ

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

ВЕРСИЯ

Версия 0.32

СИНОПСИС

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.