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 для сокетов (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 при ошибке. Эта функция необязательна и может не предоставляться на всех платформах.

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

Эта разгрузка обычно необходима при встраивании перла общего объекта (например, одного, сконфигурированного с -Duseshrplib) в более крупное приложение, и перловый интерпретатор создается и уничтожается несколько раз за время жизни приложения. В этом случае возможно, что системный динамический линковщик разгрузит, а затем повторно загрузит общий 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() передаются функции загрузки модуля. Код по умолчанию, генерируемый xsubpp, ожидает $module [, $version]. Если необязательный аргумент $version не указан, он по умолчанию устанавливается в $XS_VERSION // $VERSION в таблице символов модуля. Код по умолчанию сравнивает версию Perl-пространства с версией скомпилированного XS-кода и выводит ошибку, если они не совпадают.

АВТОР

Tim Bunce, 11 августа 1994.

Этот интерфейс основан на работе и комментариях (в произвольном порядке): Larry Wall, Robert Sanders, Dean Roehrich, Jeff Okamoto, Anno Siegel, Thomas Neumann, Paul Marquess, Charles Bailey, мной и другими.

Larry Wall разработал элегантный механизм наследования загрузки и реализовал первый динамический загрузчик Perl 5, используя его.

Глобальная загрузка Solaris добавлена Nick Ing-Simmons с помощью помощи в разработке/кодировании от Tim Bunce, январь 1996.