NAME

perlXStut - XSUB を書くためのチュートリアル

DESCRIPTION

このチュートリアルは読者にPerlのエクステンションを作るのに必要な ステップを教えるものです。 読者が perlguts, perlapi, perlxs にアクセスできるということを 仮定しています。

このチュートリアルは非常に単純な例から始めて、新しい例に進むごとに 新たな機能を付加えたより複雑なものへとなります。 幾つかのコンセプトは、読者がエクステンションを作成するのが徐々に 簡単になるように、チュートリアルの後のほうまで完全には説明されません。

このチュートリアルは Unix の観点から書かれています。 (Win32 のように)ほかのプラットフォームでは異なることになると知っている 場所では、それを記しています。 何か見落としを発見したら、ぜひ教えてください。

特別な注意

make

このチュートリアルでは、Perl が使用するように設定されている make プログラムが make という名前であると想定しています。 以下の例で "make" を実行する代わりに、Perl が使うように設定された他の make プログラムを代用する必要があるかもしれません。 perl -V:make とすると、それが何かがわかります。

バージョンに関する警告

一般向けに Perl エクステンションを書くとき、あなたのマシンで 利用可能なバージョンと異なるバージョンの Perl でエクステンションが 使われることを想定するべきです。 この文書を読んでいるということは、あなたのマシンの Perl のバージョンは おそらく 5.005 以降でしょうが、エクステンションのユーザーはもっと古い バージョンかもしれません。

どのような非互換性が想定されるかを理解するために、また珍しい場合として、 マシンに入っている Perl のバージョンがこのドキュメントより古い場合、 さらなる情報は "Troubleshooting these Examples" の章を参照してください。

もしエクステンションが、Perl の古いリリースでは利用できないような Perl の 機能を使っているなら、ユーザーは早期の意味のある警告で理解します。 おそらくこの情報を README ファイルに追加するべきでしょうが、最近の エクステンションのインストールは、CPAN.pm モジュールやその他の ツールによって自動的に行われるかもしれません。

MakeMaker ベースのインストールでは、Makefile.PL が、プラットフォームの バージョンチェックの最も早い機会を提供します。 この目的のために、以下のようなものを Makefile.PL に書けます:

    eval { require 5.007 }
        or die <<EOD;
    ############
    ### This module uses frobnication framework which is not available before
    ### version 5.007 of Perl.  Upgrade your Perl before installing Kara::Mba.
    ############
    EOD

動的読み込み対静的読み込み

一般的には、システムがライブラリを動的にロードする機能を持っていなければ XSUB を作成することはできないと考えられています。 これは正しくありません。 あなたは XSUB を作ることが できます。 ただし、あなたはその XSUB のサブルーチンと、Perl とをリンクして新たな 実行ファイルを作らなければなりません。 この状況は perl4 と同じです。

このチュートリアルはまだそういったシステムを使っていても大丈夫です。 XSUB の作成機能は、システムをチェックして可能であれば動的ロード可能 ライブラリを作成し、できなければスタティックライブラリを作成してから そのスタティックライブラリをリンクしてスタティックリンクされた 実行ファイルを作成します(最後の部分はオプション)。

これからの例を使って、動的ロード可能ライブラリが使えるシステムで あってもスタティックリンクされた実行ファイルを作成したいという場合、 "make"という引数なしのコマンドを実行する代わりに、 "make perl" というコマンドを実行してください。

もしスタティックリンクされた実行ファイルを作成することを選んだのなら、 "make test" の代わりに "make test_static" を使ってください。 動的ロード可能ライブラリが作成できないシステムの場合には単に "make test" とするだけで OK です。

チュートリアル

では、見ていきましょう!

例 1

最初のエクステンションは非常に単純です。 エクステンションの中でルーチンを呼び出すときに、良く知られたメッセージを 出力してリターンします。

"h2xs -A -n Mytest" を実行します。 これは Mytest という名前のディレクトリを作成しますが、カレントの 作業ディレクトリに ext/ というディレクトリがあればその下に作成します。 MANIFEST, Makefile.PL, lib/Mytest.pm, Mytest.xs, t/Mytest.t, Changes を 含めた幾つかのファイルがディレクトリ Mytest の下に作成されます。

MANIFEST というファイルには Mytest ディレクトリに生成されたファイル すべてのファイル名があります。

Makefile.PL というファイルは以下のような形式であるべきです。

    use ExtUtils::MakeMaker;
    # See lib/ExtUtils/MakeMaker.pm for details of how to influence
    # the contents of the Makefile that is written.
    WriteMakefile(
        NAME         => 'Mytest',
        VERSION_FROM => 'Mytest.pm', # finds $VERSION
        LIBS         => [''],   # e.g., '-lm'
        DEFINE       => '',     # e.g., '-DHAVE_SOMETHING'
        INC          => '',     # e.g., '-I/usr/include/other'
    );

Mytest.pm は以下のような内容で始まります。

    package Mytest;

    use 5.008008;
    use strict;
    use warnings;

    require Exporter;

    our @ISA = qw(Exporter);
    our %EXPORT_TAGS = ( 'all' => [ qw(

    ) ] );

    our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

    our @EXPORT = qw(

    );

    our $VERSION = '0.01';

    require XSLoader;
    XSLoader::load('Mytest', $VERSION);

    # Preloaded methods go here.

    1;
    __END__
    # Below is the stub of documentation for your module. You better edit it!

.pm ファイルの残りはエクステンションのためのドキュメントをを提供するための サンプルコードからなります。

最後に、Mytest.xs の内容は以下のようになります。

    #include "EXTERN.h"
    #include "perl.h"
    #include "XSUB.h"

    #include "ppport.h"

    MODULE = Mytest             PACKAGE = Mytest

.xs ファイルの終わりに以下の行を追加します。

    void
    hello()
        CODE:
            printf("Hello, world!\n");

"CODE:" で始まる行がインデントされていないのは問題ありません。 しかし、読みやすさの観点から、CODE: を 1 レベルインデントして、 引き続く行をさらに 1 レベルインデントすることを勧めます。

ここで、"perl Makefile.PL" を実行します。 これで make が必要とする本当の Makefile が生成されます。 この出力は以下のようになります:

    % perl Makefile.PL
    Checking if your kit is complete...
    Looks good
    Writing Makefile for Mytest
    %

ここでmakeを実行すれば、以下のような出力が生成されます (一部の長い行は明快さを保つために短くし、一部の余分な行は削除しています):

    % make
    cp lib/Mytest.pm blib/lib/Mytest.pm
    perl xsubpp  -typemap typemap  Mytest.xs > Mytest.xsc && mv Mytest.xsc Mytest.c
    Please specify prototyping behavior for Mytest.xs (see perlxs manual)
    cc -c     Mytest.c
    Running Mkbootstrap for Mytest ()
    chmod 644 Mytest.bs
    rm -f blib/arch/auto/Mytest/Mytest.so
    cc  -shared -L/usr/local/lib Mytest.o  -o blib/arch/auto/Mytest/Mytest.so   \
                \

    chmod 755 blib/arch/auto/Mytest/Mytest.so
    cp Mytest.bs blib/arch/auto/Mytest/Mytest.bs
    chmod 644 blib/arch/auto/Mytest/Mytest.bs
    Manifying blib/man3/Mytest.3pm
    %

"prototyping behavior" に関する行は安全に無視できます - これは "The PROTOTYPES: Keyword" in perlxs で説明されています。

Perl にはテストスクリプトを簡単に書くための独自の特別な方法がありますが、 この例のためだけに、自分でテストスクリプトを作ります。 hello という名前の、以下のような内容のファイルを作ります。

    #! /opt/perl5/bin/perl

    use ExtUtils::testlib;

    use Mytest;

    Mytest::hello();

ここでスクリプトを実行可能にして(chmod +x hello)から実行すれば、 以下のような出力になるはずです。

    % ./hello
    Hello, world!
    %

例 2

今度は、数値引数を入力として一つ取り、その数値が偶数なら 1 を、奇数なら 0 を返すようなサブルーチンを追加しましょう。

以下の行を Mytest.xs の末尾に追加します:

    int
    is_even(input)
            int input
        CODE:
            RETVAL = (input % 2 == 0);
        OUTPUT:
            RETVAL

"int input" の行の始めにある空白は必須ではありませんが、これがあると 読みやすさが増します。 同様に、行末のセミコロンも省略可能です。 任意の空白を "int" と "input" の間に置くことができます。

make を再度実行して、新たな共有ライブラリを作ります。

前のステップと同じように、Makefile.PL から Makefile を作って make を実行します。

作成したエクステンションが動作するかを確認するために、Mytest.t の ようなファイルが必要となります。 このファイルは Perl 自身が持っている構造をチェックするのと同様のものを 模倣して作ります。 テストスクリプトの中では、エクステンションの動作を確認するたくさんの テストを置き、正しい動作をしたら "ok" を正しくなければ "not ok" を 出力するようにします。 BEGIN ブロックにある文を print "1..4" に変え、ファイルの末尾に以下の行を 追加します。

    use Test::More tests => 4;
    BEGIN { use_ok('Mytest') };

    #########################

    # Insert your test code below, the Test::More module is use()ed here so read
    # its man page ( perldoc Test::More ) for help writing this test script.

    is(&Mytest::is_even(0), 1);
    is(&Mytest::is_even(1), 0);
    is(&Mytest::is_even(2), 1);

"make test" というコマンドでテストスクリプトを呼び出します。 以下のような出力が出るはずです。

    %make test
    PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
    t/Mytest....ok
    All tests successful.
    Files=1, Tests=4,  0 wallclock secs ( 0.03 cusr +  0.00 csys =  0.03 CPU)
    %

何をしたの?

プログラム h2xs はエクステンションを作成する出発点となります。 後の例では、ヘッダファイルを読み込んで C のルーチンに対する 接点のテンプレートを生成するのに h2xs をどのように使うかを示します。

h2xs はエクステンションのディレクトリに数多くのファイルを作成します。 Makefile.PL というファイルはエクステンションを作成するための 本当の Makefile を生成する perl スクリプトです。 詳細は後述します。

.pm と .xs といったファイルはエクステンションの本体を含みます。 .xs ファイルにはエクステンションを作るための C のルーチンがあります。 .pm ファイルには Perl がどのようにあなたの作ったエクステンションを ロードするかを指示するルーチンがあります。

Makefile を生成し、make を実行することでカレントの作業ディレクトリの 下に blib ( "build library" を意味します)と呼ばれるディレクトリが 作られます。 このディレクトリには、私たちが作成する共有ライブラリが置かれます。 一度それをテストすれば、最終的な場所にインストールすることができます。

"make test" 経由でテストスクリプトを実行することによって、非常に重要な 幾つかのことを行います。 これは perl に -I 引数を付けて起動し、これによりエクステンションの 一部である様々なファイルを見つけることができるようにします。 エクステンションをテストするのに "make test" を使うのは 非常に 重要です。 もし、テストスクリプトをそのまま実行してしまったら、致命的なエラーが 発生するでしょう。 テストスクリプトを実行するのに "make test" を使うもう一つの重大な 理由は、既にあるエクステンションをアップグレードしたものを テストしようとしたときに、"make test" を使っていれば、既に あるものではなく、新しいものをテストすることが保証されるためです。

Perl が use extension; という行を見つけたとき、use する エクステンションと同じ名前で .pm という拡張を持つファイルを検索します。 もしそういったファイルが見つからなければ、Perl は致命的エラーにより 終了します。 デフォルトの検索パスは @INC という配列に置かれます。

Mytest.pm は perl に Exporter エクステンション と Dynamic Loader エクステンションが必要であるいうことを教えます。 この後配列 @ISA, @EXPORT とスカラー $VERSION に値を設定し、最後に モジュールをブートストラップするように perl に指示します。 perl はそのダイナミックローダールーチンを(あれば)呼び出し、共有ライブラリを ロードします。

@ISA と @EXPORT の二つの配列は非常に重要です。 配列 @ISA には、メソッド(もしくはサブルーチン)がカレントパッケージに なかったときに探しに行く他のパッケージのリストがあります。 これは普通オブジェクト指向エクステンション(これについてはずっと後の方で 議論します)でのみ重要なので、普通は修正する必要はありません。

配列 @EXPORT は Perl に対して、呼び出されたときにパッケージの名前空間に 置くべきエクステンションの変数とサブルーチンを指示します。 ユーザーが既にあなたの変数名やサブルーチン名を使っているかどうかは わからないので、何をエクスポートするかを慎重に選択することは極めて 重要です。 何かそうするべき理由がない限りは、メソッド名や変数名を デフォルトでは エクスポート しない ようにしてください。

一般的な規則として、モジュールがオブジェクト指向しようとした場合には 何もエクスポートしません。 モジュールが単なる関数と変数の集まりであれば、別の配列 @EXPORT_OK を 通じてそれらをエクスポートできます。 この配列は、ユーザーがそうしてほしと明示的に指定しない限り、 自動的にはサブルーチン名と変数名を名前空間に置きません。

詳細は perlmod を参照してください。

変数 $VERSION は .pm ファイルと共有ライブラリがそれぞれ 「同期している」ことを保証します。 .pm ファイルや .xs ファイルを変更したとき、この変数の値を 増加させるべきです。

良いテストスクリプトを書く

良いテストスクリプトを書くことの重要性は、いくら強調しても足りません。 Perl 自身が使っている "ok/not ok" の形式を忠実に守り、テストケースで どうなったかを簡単に、曖昧なことなくわかるようにします。 バグを発見して修正したら、テストケースにそれを追加しましょう。

"make test" を実行することにより、正しいスクリプト Mytest.t を実行して 適切なバージョンのエクステンションを使うことが保証されます。 たくさんのテストケースがあるのなら、 "t" という名前のディレクトリに、".t" の拡張子でテストファイルを保存します。 "make test" を実行すると、これらのテストファイル全てが実行されます。

例 3

三番目の例は、入力として引数を一つとってその値を丸めてからその結果を 引数にセットするというものです。

以下の行を Mytest.xs の末尾に追加します:

        void
        round(arg)
                double  arg
            CODE:
                if (arg > 0.0) {
                        arg = floor(arg + 0.5);
                } else if (arg < 0.0) {
                        arg = ceil(arg - 0.5);
                } else {
                        arg = 0.0;
                }
            OUTPUT:
                arg

Makefile.pl というファイルを編集し、対応する行を以下に示すように してください。

        'LIBS'      => ['-lm'],   # e.g., '-lm'

Makefile を生成してから make を実行します。 Mytest.t のテスト番号を "9" に変更し、さらに以下のテストを追加します。

        $i = -1.5; &Mytest::round($i); is( $i, -2.0 );
        $i = -1.1; &Mytest::round($i); is( $i, -1.0 );
        $i = 0.0; &Mytest::round($i);  is( $i,  0.0 );
        $i = 0.5; &Mytest::round($i);  is( $i,  1.0 );
        $i = 1.2; &Mytest::round($i);  is( $i,  1.0 );

"make test" を実行します。 ここで、九つのテストすべてで ok と出力されるはずです。

これらの新しいテストケースでは、丸めるために渡される引数が スカラ変数であることに注目してください。 定数やリテラルを丸めたらどうなるだろうか、という疑問を持ったかもしれません。 何が起きるかを確かめるために、以下の行を Mytest.t に一時的に 追加してください。

        &Mytest::round(3);

"make test" を実行すると、Perl は致命的エラーを起こして 終了してしまいます。 Perl は、定数値を変更させないのです!

何が新しいの?

入力パラメータと出力パラメータ

関数の戻り値と名前を宣言した後の行に XSUB に渡すパラメータを指定できます。 各パラメータ行は(省略可能な)空白で始まり、(省略可能な)終端する セミコロンがあります。

出力パラメータは関数の最後、OUTPUT: 指示子の直後に置きます。 RETVAL を使うことで、Perl に XSUB 関数の戻り値を返したいという意志を 伝えます。 例 3 では、「返り値」を私たちが渡した元の変数に入れてほしいので、 (RETVAL でなく) その変数を OUTPUT: セクションに並べたのです。

XSUBPP プログラム

xsubpp プログラムは .xs ファイルにある XS コードを取り、それを C に 翻訳しその結果を .c という拡張子のファイルに出力します。 変換された C コードは Perl の中にある C の関数を使うように作られます。

TYPEMAP ファイル

xsubpp プログラムは Perl のデータ型(スカラー、配列、など)から C のデータ型(int, char, など)に変換する規則を使います。 これらのルールは typemap ファイル ($PERLLIB/ExtUtils/typemap)に 格納されます。 このファイルは三つの部分に分けられます。

最初のセクションは様々な C のデータ型を、様々な Perl の型にいくらか対応する 名前にマッピングするものです。 二番目のセクションは入力パラメータを扱うために xsubpp が使用する C コードからなります。 三番目のセクションは出力パラメータに対して xsubpp が使用する C コードからなります。

さあ、私たちのエクステンションのために作られた .c ファイルの一部を 見てみましょう。 ファイル名は Mytest.c です:

        XS(XS_Mytest_round)
        {
            dXSARGS;
            if (items != 1)
                Perl_croak(aTHX_ "Usage: Mytest::round(arg)");
        PERL_UNUSED_VAR(cv); /* -W */
            {
                double  arg = (double)SvNV(ST(0));      /* XXXXX */
                if (arg > 0.0) {
                        arg = floor(arg + 0.5);
                } else if (arg < 0.0) {
                        arg = ceil(arg - 0.5);
                } else {
                        arg = 0.0;
                }
                sv_setnv(ST(0), (double)arg);   /* XXXXX */
        SvSETMAGIC(ST(0));
            }
            XSRETURN_EMPTY;
        }

"XXXXX" というコメントが付けられた二つの行に注意してください。 typemap ファイルの最初のセクションを確かめれば、doublesT_DOUBLE という型で あることがわかるでしょう。 INPUT セクションでは T_DOUBLE である引数は、SvNv というルーチンを 呼び出すことによって変数が割り当てられ、その後で double に キャストされてから引数である変数に代入されます。 同様に、OUTPUT セクションでは一度引数が最終的な値を持てば、それは 呼び出された関数に返すために関数 sv_setnv に渡されます。 これら二つの関数は perlguts で説明されています。 引数スタックにあるセクションの "ST(0)" の意味は後で説明します。

出力引数に関する警告

一般的にいって、例 3 にあるように入力引数を書き換えるような エクステンションを作ることはよくありません。 代わりに、おそらくは複数の値を配列で返して、呼び出し元にそれを扱わせるように するべきです(これは後の例で行います)。 しかしながら、すでにある入力パラメータを書き換えるような C のルーチンの 呼び出しにより良く適応するために、この振る舞いが許されているのです。 次の例では、これをどう行うかを説明します。

例 4

この例で、すでにある C ライブラリとやりとりするような XSUB の記述を 始めます。 これを始めるために、独自の小さなライブラリを作ります。 それから .pm と .xs のための h2xs を記述します。

ディレクトリ Mytest と同じレベルに、Mytest2 ディレクトリを新たに 作ります。 Mytest2 ディレクトリで、mylib という別のディレクトリを作成し、そこに cd します。

ここで、テスト用のライブラリを生成するための幾つかのファイルを作ります。 こういったファイルには、C ソースファイルとヘッダーファイルが含まれます。 また、このディレクトリで Makefile.PL も作ります。 その後で、Mytest2 のレベルで make を実行することにより自動的に Makefile.PL が実行され、その結果 Makefile が作成されます。

ディレクトリ mylib で、以下のような内容の mylib.h というファイルを 作成します。

        #define TESTVAL 4

        extern double   foo(int, long, const char*);

        #include <stdlib.h>
        #include "./mylib.h"

        #include <stdlib.h>
        #include "./mylib.h"

        double
        foo(int a, long b, const char *c)
        {
                return (a + b + atof(c) + TESTVAL);
        }

        use ExtUtils::MakeMaker;
        $Verbose = 1;
        WriteMakefile(
            NAME   => 'Mytest2::mylib',
            SKIP   => [qw(all static static_lib dynamic dynamic_lib)],
            clean  => {'FILES' => 'libmylib$(LIB_EXT)'},
        );

        use ExtUtils::MakeMaker;
        $Verbose = 1;
        WriteMakefile(
            NAME   => 'Mytest2::mylib',
            SKIP   => [qw(all static static_lib dynamic dynamic_lib)],
            clean  => {'FILES' => 'libmylib$(LIB_EXT)'},
        );

        sub MY::top_targets {
                '
        all :: static

        pure_all :: static

        static ::       libmylib$(LIB_EXT)

        libmylib$(LIB_EXT): $(O_FILES)
                $(AR) cr libmylib$(LIB_EXT) $(O_FILES)
                $(RANLIB) libmylib$(LIB_EXT)

        ';
        }

"$(AR)" と "$(RANLIB)" で始まる行では空白ではなくタブを使っていることを 確認してください。 また、Win32 システムでは、$(AR) の "cr" 引数は不要であることが 報告されています。

ここでトップレベルの Mytest2 というファイルを作成します。 Mytest2 ディレクトリ に変更して、以下のコマンドを実行します。

        % h2xs -O -n Mytest2 ./Mytest2/mylib/mylib.h

これにより、Mytest2 を上書きするという警告が出ますが、気にすることは ありません。 私たちのファイルは Mytest2/mylib にありますが、さわりません。

h2xs が生成した通常の Makefile.PL は mylib ディレクトリに関してなにも 知りません。 私たちはそういったサブディレクトリがあり、そこにライブラリを作成すると いうことを教えなければなりません。 引数 MYEXTLIB を WriteMakefile 呼び出しに追加して、次のような感じに しましょう:

        WriteMakefile(
            'NAME'      => 'Mytest2',
            'VERSION_FROM' => 'Mytest2.pm', # finds $VERSION
            'LIBS'      => [''],   # e.g., '-lm'
            'DEFINE'    => '',     # e.g., '-DHAVE_SOMETHING'
            'INC'       => '',     # e.g., '-I/usr/include/other'
            'MYEXTLIB' => 'mylib/libmylib$(LIB_EXT)',
        );

それから、末尾にサブルーチンを付け加えます(これは既に存在するサブルーチンを 上書きします)。 "cd" で始まる行のインデントにタブ文字を使うことを忘れないでください!

        sub MY::postamble {
        '
        $(MYEXTLIB): mylib/Makefile
                cd mylib && $(MAKE) $(PASSTHRU)
        ';
        }

また、ファイル MANIFEST を私たちのエクステンションの内容を反映するように 修正しましょう。 "mylib" という単一の行を以下の三行で置き換えます。

        mylib/Makefile.PL
        mylib/mylib.c
        mylib/mylib.h

私たちの名前空間を奇麗で、汚染されていない状態に保つために .pm ファイルを 編集して、@EXPORT を設定している行を @EXPORT_OK に変更します。 最後に .xs ファイルで、#include の行を編集します。

        #include "mylib/mylib.h"

さらに、以下の関数定義を .xs ファイルの末尾に追加します。

        double
        foo(a,b,c)
                int             a
                long            b
                const char *    c
            OUTPUT:
                RETVAL

ここで、デフォルトの Perl は今のところ const char * という型をサポートして いないので、typemap ファイルを作成する必要があります。 Mytest2 ディレクトリに typemap と呼ばれるファイルを作成し、それを以下の 内容にします:

        const char *    T_PV

次にトップレベルの Makefile.PL で perl を実行します。 mylib ディレクトリにある Makefile も作られるということに注意してください。 make を実行し、それにより mylib ディレクトリに cd し、そこで make が 実行されるのを確認します。

Mytest2.t スクリプトを編集して、テストの数を "4" に変更して、 スクリプトの末尾に以下の行を追加します。

        is( &Mytest2::foo(1, 2, "Hello, world!"), 7 );
        is( &Mytest2::foo(1, 2, "0.0"), 7 );
        ok( abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 );

(浮動小数点数の比較を行うとき、等しいということをチェックしないことが 最良なのですが、代わりに予想される値と実際の結果の差がある値 (εと呼ばれます)、この場合では 0.01 以内かを調べています)

"make test" を実行すれば、すべてがうまくいくはずです。 Mytest2::mylib エクステンションにテストがないという警告が出ますが、 無視して構いません。

ここで何が起きているの?

先の例とは違って、今回は実際のインクルードファイルに対して h2xs を 実行しました。 これは .pm ファイルと .xs ファイルの両方に対して幾つかの追加されるものを もたらします。

.xs ファイルの解剖

"EXAMPLE 4" の .xs ファイルにはいくつか新しい要素を含んでいます。 これらの要素の意味を理解するために、以下の行に注目してください

        MODULE = Mytest2                PACKAGE = Mytest2

この行以前の全てはインクルードするヘッダおよび便利な関数を定義した プレーンな C コードです。 この部分では、組み込みの POD 文書が読み飛ばされる(perlpod を 参照してください)ことを除いては何の変換は行われず、そのまま出力 C ファイルが 出力されます。

この行以降の全ては XSUB 関数の記述です。 これらの記述は、関数を Perl 呼び出し規則を使って実装し、関数が Perl インタプリタから見えるように、xsubpp が C コードに変換します。

constant 関数には特別な注意を払ってください。 この名前は生成された .xs ファイルに 2 回現れます: 1 回目は最初の部分に static C 関数として、2 回目は 2 番目の部分に、 この static C 関数への XSUB インターフェースが定義されたときです。

これは .xs ファイルではかなり典型的です: 普通 .xs ファイルは既にある C 関数へのインターフェースを提供します。 それからこの C 関数はどこか(外部ライブラリか、.xs ファイルの最初の部分)で 定義され、この関数への Perl インターフェース(つまり「Perl の糊」)が .xs ファイルの 2 番目の部分に記述されます。 "EXAMPLE 1", "EXAMPLE 2", "EXAMPLE 3" の状況、 つまり全ての動作が「Perl の糊」の内側で行われるときは、 規則ではなく何らかの例外があります。

太った部分を XSUB の外に出す

"EXAMPLE 4" で、.xs ファイルの 2 番目の部分には、以下の XSUB の 記述を含んでいます:

        double
        foo(a,b,c)
                int             a
                long            b
                const char *    c
            OUTPUT:
                RETVAL

"EXAMPLE 1", "EXAMPLE 2", "EXAMPLE 3" と比較して、この記述は Perl 関数 foo() の呼び出しに何が起きているのかの実際の コード は 含んでいません。 ここで何が起きているのかを理解するために、この XSUB に CODE セクションを 追加できます:

        double
        foo(a,b,c)
                int             a
                long            b
                const char *    c
            CODE:
                RETVAL = foo(a,b,c);
            OUTPUT:
                RETVAL

しかし、これら 2 つの XSUB はほとんど同じ C コードを生成します: xsubpp コンパイラは、XSUB の記述の最初の 2 行から CODE: セクションを見つけ出すことができるぐらい賢いです。 OUTPUT: セクションについてはどうでしょう? 実際、これは全く同じです! CODE: セクションや PPCODE: セクションが指定されない限り、 OUTPUT: セクションも同様に削除でき、同様に OUTPUT セクションを 自動生成します。 従って、XSUB を以下のように省略できます:

        double
        foo(a,b,c)
                int             a
                long            b
                const char *    c

同じことを "EXAMPLE 2" の XSUB:

        int
        is_even(input)
                int     input
            CODE:
                RETVAL = (input % 2 == 0);
            OUTPUT:
                RETVAL

で出来るでしょうか? これをするためには、C 関数 int is_even(int input) を定義する 必要があります。 "Anatomy of .xs file" で見たように、この定義に適切な場所は .xs ファイルの 最初の部分です。 実際、C 関数

        int
        is_even(int arg)
        {
                return (arg % 2 == 0);
        }

というのはおそらくここではやりすぎです。 #define と同じぐらい単純なこともできます:

        #define is_even(arg)    ((arg) % 2 == 0)

.xs ファイルの最初の部分にこれを入れた後、 「Perl の糊」の部分は以下のように単純です

        int
        is_even(input)
                int     input

実際の動作の部分から糊の部分を分離する技術は明らかなトレードオフです: もし Perl インターフェースをしようとすると、コードの 2 箇所を変更する 必要があります。 しかし、これは多くの乱雑なものを取り除き、実際の動作の部分を Perl 呼び出し 規則の特異性から独立させます。 (実際のところ、上述の記述には Perl 固有のものはなく、異なるバージョンの xsubpp はこれを TCL の糊や Python の糊にも変換できるかもしれません。)

さらに XSUB 引数について

例 4 を補完するために、私たちは世界で最もクリーンというわけではないであろう 現実のライブラリのシミュレートをするための簡単な方法があります。 私たちは xsubpp コンパイラに渡す引数についての議論を 続けなければなりません。

.xs ファイルでルーチンへの引数を指定したとき、あなたはそれぞれの 引数がリストアップされた三つの情報ブロックを渡しているでしょう。 最初のブロックは、引数の相対的な順序(一番目、二番目、…)です。 二番目のブロックは引数の型で、引数の型宣言からなります。 三番目のブロックは、引数がライブラリ関数を呼び出すときに使われる引数の 呼び出し規約です。

Perl は関数に引数を参照渡ししますが、C は引数を値渡しします; 「引数」の 一つのデータを修正する C 関数を実装するには、この C 関数の実際の引数は そのデータへのポインタになります。 従って、2 つの C 関数宣言:

        int string_length(char *s);
        int upper_case_char(char *cp);

は完全に異なった動作をします: 前者は s で示された char の配列を検査します; 後者は直ちに cp を デリファレンスして、*cp だけを操作します(返り値は成功を示すものとして 使われます)。 Perl からはこれらの関数は全く異なった方法で使います。

& による引数の前に * を置き換えることで、この情報を xsubpp に 伝えられます。 & は、引数がアドレスでライブラリ関数に渡されることを意味します。 上記の 2 つの関数は以下のように XSUB 化できます

        int
        string_length(s)
                char *  s

        int
        upper_case_char(cp)
                char    &cp

例として、次のものを考えます:

        int
        foo(a,b)
                char    &a
                char *  b

最初の Perl の引数はこの関数では char として扱われ、変数 a に代入され、 そしてそのアドレスは関数 foo に渡されます。 二番目の Perl の引数は文字列へのポインターとして扱われ、変数 b へ 代入されます。 b の 値 も関数 foo へ渡されます。 xsubpp が生成する関数 foo への実際の呼び出しは次のようになります。

        foo(&a, b);

xsubpp は以下の関数引数リストを同じものと解析します:

        char    &a
        char&a
        char    & a

しかしながらわかりやすくするために、 "&" に変数名を続けて変数の型からは 離しておくことと、 "*" を型名に近づけるが変数名からは離す(前述した foo の 呼び出しのように)ということをお勧めします。 これを行うことで、実際に C の関数に渡されるがなんなのかを簡単に 理解できます; これは "last column" にあるものでしょう。

可能ならば、関数に(自分が望む)変数の型を渡すことに挑戦して苦労したほうが 良いでしょう。 長い目で見ればそれによって多くのトラブルを避けることになります。

引数スタック

例 1 以外の このチュートリアルで作成した C コードを見たのならば、 たくさんのST(n) (n は通常は 0)に対する参照に気がついたことでしょう。 "ST" は実際には引数スタック上の n 番目の引数を指し示すマクロです。 従って ST(0) はスタック上の最初の引数なので、XSUB に渡される最初の 引数であり、ST(1) は二番目の引数となります。

.xs ファイル中で XSUB に対する引数をリストアップしたとき、それは引数 スタックの対応する引数を xsubpp に指定するということです(例えば、 リストの最初にあれば第一引数、二番目なら第二引数ということ)。 関数が期待するのと同じ順番でリストアップしなければ、思いがけない 災害を招くことになります。

引数スタックの実際の値は渡された値へのポインタです。 引数が OUTPUT の値として挙げられている場合、スタック上の対応する値 (例えば、最初の引数なら ST(0)) が変更されます。 例 3 で生成された C コードを見ることでこれを検証できます。 round() XSUB ルーチンのコードは以下のように見える行を含んでいます:

        double  arg = (double)SvNV(ST(0));
        /* Round the contents of the variable arg */
        sv_setnv(ST(0), (double)arg);

引数変数は、まず ST(0) の値から取られるものにセットされ、その後ルーチンの 最後に ST(0) に書き戻されます。

XSUB は単なるスカラではなく、リストを返すこともできます。 これはスタック値 ST(0), ST(1) などを微妙に違う方法で操作することによって 行う必要があります。 詳しくは perlxs を参照してください。

XSUB はまた、Perl 関数引数から C 関数引数への自動変換を回避することも できます。 詳しくは perlxs を参照してください。 自動変換が行われる場合でも ST(i) を検査することでの手動変換を好む 人々もいて、これにより XSUB 呼び出しのロジックがよりきれいになると 主張しています。 XSUB における「Perl の糊」と「実働部隊」の完全な分離に関する似たような トレードオフに関して、"Getting the fat out of XSUBs" と 比較してください。

専門家はこれらの慣用法について主張する一方、Perl の内部に関する初心者は Perl 内部に固有のものを可能な限り小さくする方法を好みます; これはつまり "Getting the fat out of XSUBs" のような、自動変換と自動呼び出し 生成です。 この手法には、XSUB 作者を Perl API の将来の変更から守るという追加の利点も あります。

エクステンションを拡張する

Perlとあなたのエクステンションとの間のインターフェースをより簡単に、 より理解しやすくするのを助けるためにメソッドやサブルーチンを 作りたいと思う事があるかもしれません。 こういったルーチンは .pm ファイルに置くのが良いです。 これがエクステンション自身がロードされたときロードされるにしろ、 サブルーチン定義が置かれている. pm ファイルに依存する呼び出しのときのみ ロードするにしろ、自動的にロードが行われます。 追加のサブルーチンを保管して読み込むもう一つの方法としては AutoLoader を参考にすることもできます。

エクステンションを文書化する

あなたのエクステンションに関するドキュメントがないということについて、 あなたは何の言い訳もできません。 ドキュメントは .pm ファイルに属します。 このファイルは pod2man に送り込まれ、埋め込まれたドキュメントが man ページフォーマットに変換され、それから blib ディレクトリに置かれます。 このドキュメントは、エクステンションがインストールされるときに Perl の man ページディレクトリにもコピーされます。

あなたは .pm ファイルにあるドキュメントと Perl コードをまき散らすことが あるかもしれません。 事実、あなたがメソッドを autoload しようとするならば、.pm ファイルの中に あるコメントで説明されているようにこれを行わねばなりません。

pod フォーマットについてのより詳しい情報は perlpod を参照してください。

エクステンションをインストールする

あなたの作ったエクステンションが完成し、かつすべてのテストに合格すれば、 それを実に単純なやりかたでインストールします。 ただ単に "make install" と実行するだけです。 Perl がインストールされたディレクトリに対する書き込み権限が持っている 必要がありますが、あるいは、あなたのシステム管理者にあなたの make を 実行するようお願いする必要があるでしょう。

別の方法として、"make install" の後ろに (あるいはおかしな make を使っている 場合は "make" と "install" の間に)"PREFIX=/destination/directory" と 書くことで、エクステンションのファイルを置く正確なディレクトリを 指定できます。 これは、最終的に複数のシステムに配布されるエクステンションをビルドしている 場合にとても有用です。 その後単に出力先のディレクトリのファイルをアーカイブして、目的のシステムに 配布します。

例 5

この例では、引数スタックにさらなる作業をします。 前の例では全て、単一の値を返すものだけです。 ここでは、配列を返すエクステンションを作ります。

このエクステンションはとても Unix 指向です(struct statfs と statfs システムコール)。 もし Unix システム以外で実行するなら、statfs を複数の値を返す別の関数に 置き換えるか、呼び出し元に返す値をハードコーディングする(しかしこれは エラーの場合をテストするのが少し難しくなります)か、あるいは単に この例を実行しないということもできます。 もし XSUB を変更したなら、テストケースも変更にあわせて確実に 修正してください。

Mytest ディレクトリに戻って、Mytest.xs の末尾に以下のコードを追加します:

        void
        statfs(path)
                char *  path
            INIT:
                int i;
                struct statfs buf;

            PPCODE:
                i = statfs(path, &buf);
                if (i == 0) {
                        XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
                        XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
                } else {
                        XPUSHs(sv_2mortal(newSVnv(errno)));
                }

また、.xs ファイルの先頭、"XSUB.h" をインクルードした直後に、以下のコードを 追加する必要があります:

        #include <sys/vfs.h>

また、以下のコードを Mytest.t に追加する一方、"9" のテストを "11" に 増やします:

        @a = &Mytest::statfs("/blech");
        ok( scalar(@a) == 1 && $a[0] == 2 );
        @a = &Mytest::statfs("/");
        is( scalar(@a), 7 );

この例での新しいこと

この例はいくつかの全く新しい概念を追加します。 一回に一つずつやります。

例 6

この例では、入力パラメータとして配列へのリファレンスを受け付け、ハッシュの 配列へのリファレンスを返します。 ここでは、複雑な Perl データ型を XSUB から操作する方法を示します。

このエクステンションはやや不自然です。 これは以前の例のコードを基礎にしています。 これは statfs 関数を複数呼び出し、入力としてファイル名の配列への リファレンスを受け付けて、それぞれのファイルシステムのデータを含む ハッシュの配列へのリファレンスを返します。

Mytest ディレクトリに戻って、Mytest.xs の末尾に以下のコードを追加します:

    SV *
    multi_statfs(paths)
            SV * paths
        INIT:
            AV * results;
            I32 numpaths = 0;
            int i, n;
            struct statfs buf;

            if ((!SvROK(paths))
                || (SvTYPE(SvRV(paths)) != SVt_PVAV)
                || ((numpaths = av_len((AV *)SvRV(paths))) < 0))
            {
                XSRETURN_UNDEF;
            }
            results = (AV *)sv_2mortal((SV *)newAV());
        CODE:
            for (n = 0; n <= numpaths; n++) {
                HV * rh;
                STRLEN l;
                char * fn = SvPV(*av_fetch((AV *)SvRV(paths), n, 0), l);

                i = statfs(fn, &buf);
                if (i != 0) {
                    av_push(results, newSVnv(errno));
                    continue;
                }

                rh = (HV *)sv_2mortal((SV *)newHV());

                hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0);
                hv_store(rh, "f_bfree",  7, newSVnv(buf.f_bfree),  0);
                hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0);
                hv_store(rh, "f_bsize",  7, newSVnv(buf.f_bsize),  0);
                hv_store(rh, "f_ffree",  7, newSVnv(buf.f_ffree),  0);
                hv_store(rh, "f_files",  7, newSVnv(buf.f_files),  0);
                hv_store(rh, "f_type",   6, newSVnv(buf.f_type),   0);

                av_push(results, newRV((SV *)rh));
            }
            RETVAL = newRV((SV *)results);
        OUTPUT:
            RETVAL

また、以下のコードを Mytest.t に追加する一方、"11" のテストを "13" に増やします:

        $results = Mytest::multi_statfs([ '/', '/blech' ]);
        ok( ref $results->[0] );
        ok( ! ref $results->[1] );

この例での新しいこと

ここでは後述するいくつかの新しい概念があります:

例 7 (近日公開)

引数の XPUSH と RETVAL のセットと返り値の配列への代入

例 8 (近日公開)

$! をセットする

例 9 オープンしたファイルを XS に渡す

型グロブなどで、XS にファイルを渡すのは難しいと考えるかもしれません。 えっと、そうではありません。

標準 C ライブラリ関数 fputs() のラッパーが必要、という不思議な 理由があるとしましょう。 必要なものは以下のものだけです:

        #define PERLIO_NOT_STDIO 0
        #include "EXTERN.h"
        #include "perl.h"
        #include "XSUB.h"

        #include <stdio.h>

        int
        fputs(s, stream)
                char *          s
                FILE *          stream

実際の作業は標準の typemap で行われます。

しかし、perlio 層で行われる素晴らしい機能全てを手放すことになります。 これは stdio 関数 fputs() を呼び出すので、それらについては何もしません。

標準 typemap は 3 種類の PerlIO * を提供します: InputStream (T_IN), InOutStream (T_INOUT), OutputStream (T_OUT) です。 生の PerlIO * は T_INOUT として扱われます。 コード中でこれが問題になる場合(なぜそうなり得るかは以下を 参照してください)、特定の名前の一つを #define や typedef して、 それを XS ファイルで引数や結果の型として使ってください。

perl 5.7 以前の標準 typemap には PerlIO * は含まれていませんが、 3 種類のストリームの種類があります。 PerlIO * を直接使うと、独自の typemap を提供しない限り、 後方互換ではありません。

perl から 来るストリームについて、主な違いは OutputStream が 出力 PerlIO * を得るということです - これはソケットの場合に違いとなります。 私たちの例と同様に…

perl に 渡されるストリームについて、新しいファイルハンドル (つまり、新しいグロブへのリファレンス)が作成され、提供された PerlIO * と 結び付けられます。 もし PerlIO * の読み込み/書き込み状態が正しくない場合、ファイルハンドルが 使われたときにエラーや警告を受けることになります。 従って、もし PerlIO * を "w" としてオープンしたなら実際には OutputStream であるべきですし、"r" としてオープンしたなら InputStream であるべきです。

ここで、XS で perlio 層を使いたいとしましょう。 例のように、perlio の PerlIO_puts() 関数を使います。

XS ファイルの C の部分 (最初の MODULE 行の上) に以下のようにします

        #define OutputStream    PerlIO *
    or
        typedef PerlIO *        OutputStream;

そして XS コードはこれです:

        int
        perlioputs(s, stream)
                char *          s
                OutputStream    stream
        CODE:
                RETVAL = PerlIO_puts(stream, s);
        OUTPUT:
                RETVAL

PerlIO_puts() は fputs() と比較する予約された引数を持っていて、 引数は同じままにしたいので、CODE セクションを使う必要があります。

これを完全に探索するために、PerlIO * に stdio の fputs() を使いたいです。 これは、perlio システムに stdio の FILE * を問い合わせる必要があります:

        int
        perliofputs(s, stream)
                char *          s
                OutputStream    stream
        PREINIT:
                FILE *fp = PerlIO_findFILE(stream);
        CODE:
                if (fp != (FILE*) 0) {
                        RETVAL = fputs(s, fp);
                } else {
                        RETVAL = -1;
                }
        OUTPUT:
                RETVAL

注意: PerlIO_findFILE() は stdio 層の層を検索します。 もしそれが見つからなければ、新しい stdio FILE を生成するために PerlIO_exportFILE() を呼び出します。 新しい FILE が必要な場合にのみ PerlIO_exportFILE() を 呼び出すようにしてください。 これは呼び出し毎に新しいものを生成して新しい stdio 層にプッシュします。 従って、同じファイルに対して繰り返し呼び出さないでください。 PerlIO_findFILE() は、一度 PerlIO_exportFILE() で生成された stdio 層を 取り出します。

これは perlio システムにのみ適用されます。 5.7 以前のバージョンでは、PerlIO_exportFILE() は PerlIO_findFILE() と 等価です。

これらの例のトラブルシューティング

この文書の最初に触れたように、もしこれらの例のエクステンションで問題が あった場合、以下が参考になるかもしれません。

See also

より詳しい情報は、perlguts, perlapi, perlxs, perlmod, perlpod を参照してください。

Author

Jeff Okamoto <okamoto@corp.hp.com>

Dean Roehrich, Ilya Zakharevich, Andreas Koenig, Tim Bunce によるレビューと 助力を受けました。

PerlIO の素材は Lupe Christoph によって提供され、Nick Ing-Simmons によって 明確化されたものです。

Perl 5.8.x での h2xs に関しては Renee Baecker が変更しました。

Last Changed

2007/10/11