DynaLoader

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• СИНТАКСИС
• ОПИСАНИЕ
• АВТОР

НАЗВАНИЕ

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

СИНТАКСИС

package YourPackage;
require DynaLoader;
@ISA = qw(... DynaLoader ...);
__PACKAGE__->bootstrap;

# optional method for 'global' loading
sub dl_load_flags { 0x01 }     

ОПИСАНИЕ

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

Этот документ служит как спецификацией для всех, кто хочет реализовать DynaLoader для новой платформы, так и руководством для всех, кто хочет использовать DynaLoader напрямую в приложении.

DynaLoader разработан как очень простой высокоуровневый интерфейс, достаточно общий, чтобы охватить потребности SunOS, HP-UX, Linux, VMS и других платформ.

Также надеется, что интерфейс покроет потребности OS/2, NT и т. д., а также позволит псевдодинамической компоновке (используя ld -A во время выполнения).

Следует подчеркнуть, что DynaLoader сам по себе практически бесполезен для доступа к библиотекам, не являющимся Perl-библиотеками, потому что он предоставляет очень мало «склейки» Perl-C. Например, нет механизма для вызова функции C-библиотеки или передачи аргументов. Модуль C::DynaLib доступен на сайтах CPAN, который выполняет эту функцию для некоторых распространённых типов систем. А с 2000 года также есть Inline::C, модуль, который позволяет вам писать Perl-подпрограммы на C. Также доступен на вашем локальном сайте CPAN.

Краткое описание интерфейса DynaLoader

@dl_library_path
@dl_resolve_using
@dl_require_symbols
$dl_debug
$dl_dlext
@dl_librefs
@dl_modules
@dl_shared_objects
                                                Implemented in:
bootstrap($modulename)                               Perl
@filepaths = dl_findfile(@names)                     Perl
$flags = $modulename->dl_load_flags                  Perl
$symref  = dl_find_symbol_anywhere($symbol)          Perl

$libref  = dl_load_file($filename, $flags)           C
$status  = dl_unload_file($libref)                   C
$symref  = dl_find_symbol($libref, $symbol)          C
@symbols = dl_undef_symbols()                        C
dl_install_xsub($name, $symref [, $filename])        C
$message = dl_error                                  C

@dl_library_path

Стандартный/по умолчанию список каталогов, в которых dl_findfile() будет искать библиотеки и т. д. Каталоги просматриваются в порядке: $dl_library_path[0], [1] и т. д.

@dl_library_path инициализируется списком «стандартных» каталогов (/usr/lib и т. д.), определяемых Configure ($Config{'libpth'}). Это должно обеспечить переносимость на широкий спектр платформ.

@dl_library_path также должен быть инициализирован любыми другими каталогами, которые могут быть определены из среды во время выполнения (например, LD_LIBRARY_PATH для SunOS).

После инициализации @dl_library_path может быть изменён приложением с помощью push и unshift перед вызовом dl_findfile(). Unshift может использоваться для добавления каталогов в начало порядка поиска для экономии времени поиска или для переопределения библиотек с одинаковым именем в «стандартных» каталогах.

Функция загрузки, вызываемая dl_load_file(), может потребовать абсолютный путь. Функция dl_findfile() и @dl_library_path могут использоваться для поиска и возврата абсолютного пути к библиотеке/объекту, которую вы хотите загрузить.

@dl_resolve_using

Список дополнительных библиотек или других общих объектов, которые могут быть использованы для разрешения любых неопределённых символов, которые могут быть сгенерированы последующим вызовом load_file().

Это требуется только на некоторых платформах, которые не обрабатывают зависимые библиотеки автоматически. Например, библиотека расширения Perl Socket (auto/Socket/Socket.so) содержит ссылки на многие функции сокетов, которые необходимо разрешить при её загрузке. Большинство платформ автоматически знают, где найти зависимую библиотеку (например, /usr/lib/libsocket.so). Несколько платформ нуждаются в явном указании местоположения зависимой библиотеки. Используйте @dl_resolve_using для этого.

Пример использования:

@dl_resolve_using = dl_findfile('-lsocket');

@dl_require_symbols

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

@dl_librefs

Массив дескрипторов, возвращённых успешными вызовами dl_load_file(), выполненными bootstrap, в порядке их загрузки. Может быть использован с dl_find_symbol() для поиска символа в любом из загруженных файлов.

@dl_modules

Массив имён модулей (пакетов), которые были загружены bootstrap.

@dl_shared_objects

Массив имён файлов общих объектов, которые были загружены.

dl_error()

Синтаксис:

$message = dl_error();

Текст сообщения об ошибке от последней неудачной функции DynaLoader. Обратите внимание, что, подобно errno в unix, успешный вызов функции не сбрасывает это сообщение.

Реализации должны обнаруживать ошибку сразу после её возникновения в любой из других функций и сохранять соответствующее сообщение для последующего извлечения. Это позволит избежать проблем на некоторых платформах (например, SunOS), где сообщение об ошибке очень временное (например, dlerror()).

$dl_debug

Внутренние сообщения отладки включены, когда $dl_debug установлено в true. В настоящее время установка $dl_debug влияет только на перловую сторону DynaLoader. Эти сообщения помогут разработчику приложений решить любые проблемы с использованием DynaLoader.

$dl_debug установлено в $ENV{'PERL_DL_DEBUG'} при определении.

Для разработчика/порта DynaLoader существует аналогичная переменная отладки, добавленная в код C (см. dlutils.c), и включена, если Perl был скомпилирован со флагом -DDEBUGGING. Это также можно установить с помощью переменной окружения PERL_DL_DEBUG. Установите значение 1 для минимальной информации или большее значение для большей информации.

$dl_dlext

При указании (локализации) в файле .pm модуля указывает расширение, которое будет иметь загружаемый объект модуля. Например:

local $DynaLoader::dl_dlext = 'unusual_ext';

указало бы, что загружаемый объект модуля имеет расширение unusual_ext вместо более распространённого $Config{dlext}. ПРИМЕЧАНИЕ: Это также требует, чтобы Makefile.PL модуля указал (в WriteMakefile()):

DLEXT => 'unusual_ext',

dl_findfile()

Синтаксис:

@filepaths = dl_findfile(@names)

Определяет полные пути (включая расширение файла) одного или нескольких загружаемых файлов по их общим именам и, необязательно, по одному или нескольким каталогам. По умолчанию ищет в каталогах в @dl_library_path и возвращает пустой список, если файлы не найдены.

Имена могут быть указаны в различных независимых от платформы форматах. Все имена в формате -lname преобразуются в libname.*, где .* — подходящее расширение для платформы.

Если имя ещё не имеет соответствующего префикса и/или суффикса, то соответствующий файл будет искаться путём перебора комбинаций префикса и суффикса, подходящих для платформы: "$name.o", "lib$name.*" и "$name".

Если в @names указаны каталоги, они будут просматриваться перед @dl_library_path. Каталоги могут быть указаны как -Ldir. Все остальные имена рассматриваются как имена файлов, которые нужно искать.

Использование аргументов в формате -Ldir и -lname рекомендуется.

Пример:

@dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));

dl_expandspec()

Синтаксис:

$filepath = dl_expandspec($spec)

Некоторые необычные системы, такие как VMS, требуют специальной обработки имён файлов для работы со символическими именами файлов (т. е. логическими именами VMS).

Для поддержки этих систем можно реализовать функцию dl_expandspec() либо в файле dl_*.xs, либо добавить код в функцию dl_expandspec() в DynaLoader.pm. См. DynaLoader_pm.PL для получения дополнительной информации.

dl_load_file()

Синтаксис:

$libref = dl_load_file($filename, $flags)

Динамически загружает $filename, который должен быть путём к общему объекту или библиотеке. В качестве дескриптора загруженного объекта возвращается невидимый «ссылка на библиотеку». Возвращает undef при ошибке.

Аргумент $flags изменяет поведение dl_load_file. Присвоенные биты:

0x01  make symbols available for linking later dl_load_file's.
      (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
      (ignored under VMS; this is a normal part of image linking)

(На системах, которые предоставляют дескриптор загруженного объекта, таких как SunOS и HPUX, $libref будет этим дескриптором. На других системах $libref обычно будет $filename или указатель на буфер, содержащий $filename. Приложение не должно ни как не изучать ни изменять $libref.)

Это функция, которая выполняет фактическую работу. Она должна использовать текущие значения @dl_require_symbols и @dl_resolve_using при необходимости.

SunOS: dlopen($filename)
HP-UX: shl_load($filename)
Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
VMS:   lib$find_image_symbol($filename,$dl_require_symbols[0])

(Функция dlopen() также используется Solaris и некоторыми версиями Linux, и является общим выбором при предоставлении «оболочки» на других механизмах, как это делается в порте OS/2.)

dl_unload_file()

Синтаксис:

$status = dl_unload_file($libref)

Динамически разгружает $libref, который должен быть невидимой «ссылкой на библиотеку», как возвращённой из dl_load_file. Возвращает 1 при успехе и 0 при неудаче. Эта функция необязательна и может не предоставляться на всех платформах.

Если она определена и макрос С DL_UNLOAD_ALL_AT_EXIT определён при компиляции perl, то он вызывается автоматически при завершении интерпретатора для каждого общего объекта или библиотеки, загруженной DynaLoader::bootstrap. Все такие ссылки на библиотеки хранятся в @dl_librefs DynaLoader::Bootstrap при загрузке библиотек. Файлы разгружаются в порядке LIFO.

Эта разгрузка обычно необходима при встраивании перла общего объекта (например, настроенного с помощью -Duseshrplib) в более крупное приложение, и интерпретатор Perl создаётся и уничтожается несколько раз за время жизни приложения. В этом случае возможно, что системный динамический компоновщик разгрузит и затем повторно загрузит общий libperl без перераспределения каких-либо ссылок на него из любых файлов, DynaLoaded предыдущей инкарнацией интерпретатора. В результате любые общие объекты, открытые DynaLoader, могут указывать на теперь недействительный «призрак» общего объекта libperl, что приведёт к, казалось бы, случайному повреждению памяти и ошибкам. Это поведение чаще всего наблюдается при использовании Apache и mod_perl, построенных с помощью механизма APXS.

SunOS: dlclose($libref)
HP-UX: ???
Linux: ???
VMS:   ???

(Функция dlclose() также используется Solaris и некоторыми версиями Linux, и является общим выбором при предоставлении «оболочки» на других механизмах, как это делается в порте OS/2.)

dl_load_flags()

Синтаксис:

$flags = dl_load_flags $modulename;

Предназначен для вызова метода и переопределения производным классом (т. е. классом, у которого DynaLoader находится в @ISA). Определение в самом DynaLoader возвращает 0, что обеспечивает стандартное поведение от dl_load_file().

dl_find_symbol()

Синтаксис:

$symref = dl_find_symbol($libref, $symbol)

Возвращает адрес символа $symbol или undef если не найден. Если целевая система имеет отдельные функции для поиска символов разных типов, то dl_find_symbol() должна искать символы функций в первую очередь, а затем и другие типы.

Точный способ возврата адреса в $symref в настоящее время не определён. Единственное первоначальное требование состоит в том, что $symref может быть передан и понят dl_install_xsub().

SunOS: dlsym($libref, $symbol)
HP-UX: shl_findsym($libref, $symbol)
Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
VMS:   lib$find_image_symbol($libref,$symbol)

dl_find_symbol_anywhere()

Синтаксис:

$symref = dl_find_symbol_anywhere($symbol)

Применяет dl_find_symbol() к членам @dl_librefs и возвращает первую найденную пару.

dl_undef_symbols()

Пример

@symbols = dl_undef_symbols()

Возвращает список имён символов, которые остаются неопределёнными после load_file(). Возвращает () если неизвестно. Не беспокойтесь, если ваша платформа не предоставляет механизм для этого. Большинство платформ не нуждаются в нём и поэтому его не предоставляют, они просто возвращают пустой список.

dl_install_xsub()

Синтаксис:

dl_install_xsub($perl_name, $symref [, $filename])

Создаёт новую внешнюю подпрограмму Perl с именем $perl_name, используя $symref в качестве указателя на функцию, которая реализует подпрограмму. Это просто прямой вызов newXS()/newXS_flags(). Возвращает ссылку на установленную функцию.

Параметр $filename используется Perl для определения исходного файла функции, если это требуется die(), caller() или отладчиком. Если $filename не определён, то будет использовано "DynaLoader".

bootstrap()

Синтаксис:

bootstrap($module [...])

Это обычная точка входа для автоматической динамической загрузки в Perl.

Выполняются следующие действия:

• находит каталог auto/$module, выполняя поиск в @INC

• использует dl_findfile() для определения имени файла для загрузки

• устанавливает @dl_require_symbols в ("boot_$module")

• выполняет файл auto/$module/$module.bs, если он существует (обычно используется для добавления в @dl_resolve_using любых файлов, необходимых для загрузки модуля в текущей системе)

• вызывает dl_load_flags() для определения способа загрузки файла.

• вызывает dl_load_file() для загрузки файла

• вызывает dl_undef_symbols() и выводит предупреждение, если какие-либо символы не определены

• вызывает dl_find_symbol() для "boot_$module"

• вызывает dl_install_xsub() для установки его как "${module}::bootstrap"

• вызывает &{"${module}::bootstrap"} для запуска модуля (фактически используется ссылка на функцию, возвращённую dl_install_xsub, для повышения скорости)

Все аргументы функции bootstrap() передаются в функцию bootstrap модуля. По умолчанию сгенерированный xsubpp код ожидает $module [, $version]. Если необязательный аргумент $version не указан, он по умолчанию равен $XS_VERSION // $VERSION в таблице символов модуля. По умолчанию код сравнивает версию пространства Perl с версией скомпилированного XS-кода и выводит ошибку, если они не совпадают.

АВТОР

Тим Банс, 11 августа 1994.

Этот интерфейс основан на работе и комментариях (в произвольном порядке): Ларри Уолл, Роберт Сандерс, Дину Роэрих, Джефф Окамото, Анно Зигель, Томас Нойманн, Пол Маркесс, Чарльз Бейли, я и другие.

Ларри Уолл спроектировал элегантный механизм наследования bootstrap и реализовал первый динамический загрузчик Perl 5, использующий его.

Глобальная загрузка Solaris добавлена Ником Инг-Симмонсом с помощью помощи в проектировании/кодировании Тима Банса, январь 1996.