5.30.0

名前

perlembed - how to embed perl in your C program

perlembed - C プログラムへの Perl の埋め込み方

説明

PREAMBLE

Do you want to:

あなたのやりたいことは

Use C from Perl?

(Perl から C を使うことですか?)

perlxstut, perlxs, h2xs, perlguts, perlapi を 読みましょう。

Use a Unix program from Perl?

(Perl から UNIX プログラムを使うことですか?)

Read about back-quotes and about system and exec in perlfunc.

バッククォートに関することと、 perlfuncにあるsystemexecに関することを読みましょう。

Use Perl from Perl?

(Perl から Perl を使うことですか?)

"do" in perlfunc"eval" in perlfunc"require" in perlfunc"use" in perlfuncを読みましょう。

Use C from C?

(C から C を使うことですか?)

Rethink your design.

デザインを考え直しましょう。

Use Perl from C?

(C から Perl を使うことですか?)

Read on...

読み続けてください…

ロードマップ

  • Compiling your C program

    C プログラムをコンパイルする

  • Adding a Perl interpreter to your C program

    C プログラムに Perl インタプリタを追加する

  • Calling a Perl subroutine from your C program

    C プログラムから Perl サブルーチンを呼び出す

  • Evaluating a Perl statement from your C program

    C プログラムから Perl の文を評価する

  • Performing Perl pattern matches and substitutions from your C program

    C プログラムから Perl のパターンマッチングや置換を実行する

  • Fiddling with the Perl stack from your C program

    C プログラムから Perl のスタックを扱う

  • Maintaining a persistent interpreter

    永続的(persistent)インタプリタを取り扱う

  • Maintaining multiple interpreter instances

    複数のインタプリタのインスタンスを取り扱う

  • Using Perl modules, which themselves use C libraries, from your C program

    C ライブラリを使っている Perl のモジュールを C プログラムから使う

  • Embedding Perl under Win32

    Win32 における組み込み Perl

あなたのCプログラムをコンパイルする

If you have trouble compiling the scripts in this documentation, you're not alone. The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY THE SAME WAY THAT YOUR PERL WAS COMPILED. (Sorry for yelling.)

このドキュメントにあるスクリプトのコンパイルがうまく行かなくても、 あなたは孤独ではありません。 基本的なルールはこうです: あなたが Perl をコンパイルしたときと全く同じやり方でプログラムを コンパイルしなさい。 (叫んでしまってすみません。)

Also, every C program that uses Perl must link in the perl library. What's that, you ask? Perl is itself written in C; the perl library is the collection of compiled C programs that were used to create your perl executable (/usr/bin/perl or equivalent). (Corollary: you can't use Perl from your C program unless Perl has been compiled on your machine, or installed properly--that's why you shouldn't blithely copy Perl executables from machine to machine without also copying the lib directory.)

また、Perlを使うすべての C プログラムは perl ライブラリ にリンクして いなければなりません。 それって何、と聞きますか? Perl それ自身が C で書かれています。 Perl ライブラリはあなたの perl 実行ファイル(/usr/bin/perl か これに等価な)を作るために使われたコンパイル済みの C プログラムの 集合体です(あなたの使うマシンで Perl がコンパイルされているか、正しく インストールされていなければ C プログラムから Perl を使うことはできません。 これが、Perl の実行ファイルをあるマシンからマシンへ lib ディレクトリ 抜きでコピーしてしまうような軽率なことをすべきでないという理由です)。

When you use Perl from C, your C program will--usually--allocate, "run", and deallocate a PerlInterpreter object, which is defined by the perl library.

Perl を C から使うとき、その C プログラムは -- 普通は -- perl ライブラリで 定義されている PerlInterpreter オブジェクトの割り付け、「実行」、解放を 行います。

If your copy of Perl is recent enough to contain this documentation (version 5.002 or later), then the perl library (and EXTERN.h and perl.h, which you'll also need) will reside in a directory that looks like this:

あなたの使っている Perl がこのドキュメントの内容にあっている(バージョン 5.002 以降)であるのであれば、perl ライブラリ(とこれも必要な EXTERN.Hperl.h)が次のようなディレクトリに 置かれていることでしょう。

    /usr/local/lib/perl5/your_architecture_here/CORE

or perhaps just

あるいは以下のような場所かもしれませんし

    /usr/local/lib/perl5/CORE

or maybe something like

こうかもしれません

    /usr/opt/perl5/CORE

Execute this statement for a hint about where to find CORE:

CORE の場所を見つけ出すために以下のような文を実行します。

    perl -MConfig -e 'print $Config{archlib}'

Here's how you'd compile the example in the next section, "Adding a Perl interpreter to your C program", on my Linux box:

次のセクション "Adding a Perl interpreter to your C program" に ある例をコンパイルするこうします(私のLinux boxでの場合)

    % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
    -I/usr/local/lib/perl5/i586-linux/5.003/CORE
    -L/usr/local/lib/perl5/i586-linux/5.003/CORE
    -o interp interp.c -lperl -lm

(That's all one line.) On my DEC Alpha running old 5.003_05, the incantation is a bit different:

(これは実際には一行です。) 私の使う DEC Alpha 上で古い 5.003_05 を使う場合では、オマジナイはちょっと 違います:

    % cc -O2 -Olimit 2900 -I/usr/local/include
    -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
    -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
    -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm

How can you figure out what to add? Assuming your Perl is post-5.001, execute a perl -V command and pay special attention to the "cc" and "ccflags" information.

追加するのものを見つけるにはどうすればよいでしょうか? あなたの使う Perl が 5.001 より後のものであれば、perl -V を実行して、 "cc" と "ccflags" の情報に特に注意して見ましょう。

You'll have to choose the appropriate compiler (cc, gcc, et al.) for your machine: perl -MConfig -e 'print $Config{cc}' will tell you what to use.

あなたは、あなたの使うマシンのために適切なコンパイラ(cc, gcc など)を選ぶ必要があります。 perl -MConfig -e 'print $Config{cc}' はあなたに使うべき コンパイラを教えてくれるでしょう。

You'll also have to choose the appropriate library directory (/usr/local/lib/...) for your machine. If your compiler complains that certain functions are undefined, or that it can't locate -lperl, then you need to change the path following the -L. If it complains that it can't find EXTERN.h and perl.h, you need to change the path following the -I.

同様に、適切なライブラリディレクトリ(/usr/local/lib/...) も 選択せねばなりません。 もしあなたの使うコンパイラが幾つかの関数が 未定義であるとか、-lperl が見つからないという報告をしてきたら、 -L の後に続くパスを変更する必要があります。 EXTERN.hperl.h が見つからないというエラーであれば、 -I の後にあるパスを変更する必要があります。

You may have to add extra libraries as well. Which ones? Perhaps those printed by

おそらく、さらにライブラリを追加指定する必要があるでしょう。 どれを? おそらく以下のようにすれば表示されます:

   perl -MConfig -e 'print $Config{libs}'

Provided your perl binary was properly configured and installed the ExtUtils::Embed module will determine all of this information for you:

あなたの使っている perl のバイナリが適切なコンフィギュレーションが 行われているもので、かつ ExtUtils::Embed モジュールが インストールされていれば、これによって必要な全ての情報が決定できます。

   % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

If the ExtUtils::Embed module isn't part of your Perl distribution, you can retrieve it from http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/ (If this documentation came from your Perl distribution, then you're running 5.004 or better and you already have it.)

ExtUtils::Embed モジュールは Perl 配布パッケージに含まれていなければ、 http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/ から 入手できます(もしこのドキュメントがあなたの持っている Perl 配布パッケージにあったものならば、あなたは 5.004 以降のものを 使っているはずで、すでにそのモジュールを持っているはずです。)

The ExtUtils::Embed kit on CPAN also contains all source code for the examples in this document, tests, additional examples and other information you may find useful.

CPAN にある ExtUtils::Embed キットにもこのドキュメントにある例の すべてのソースコードがあり、テストと追加された例、その他の情報が あります。

あなたの C プログラムに Perl インタプリタを追加する

In a sense, perl (the C program) is a good example of embedding Perl (the language), so I'll demonstrate embedding with miniperlmain.c, included in the source distribution. Here's a bastardized, non-portable version of miniperlmain.c containing the essentials of embedding:

ある意味で、perl(C プログラムとしての perl)は組み込み Perl(言語としての Perl)の良い例です; ですから、ソース配布にある miniperlmain.c を 使って組込みのデモンストレーションをします。 以下に示すのは、組込みの本質を持っていて配布ソースにも含まれている (そして粗悪で移植性に欠ける)miniperlmain.c です。

 #include <EXTERN.h>               /* from the Perl distribution     */
 #include <perl.h>                 /* from the Perl distribution     */

 static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/

 int main(int argc, char **argv, char **env)
 {
        PERL_SYS_INIT3(&argc,&argv,&env);
        my_perl = perl_alloc();
        perl_construct(my_perl);
        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
        perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
        perl_run(my_perl);
        perl_destruct(my_perl);
        perl_free(my_perl);
        PERL_SYS_TERM();
        exit(EXIT_SUCCESS);
 }

Notice that we don't use the env pointer. Normally handed to perl_parse as its final argument, env here is replaced by NULL, which means that the current environment will be used.

ここで、env ポインタを使っていないことに注意してください。 通常は perl_parse はその最終引数として env を取りますが、 ここではカレントの環境をそのまま使うことを示す NULL に置き換えられています。

The macros PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific tune up of the C runtime environment necessary to run Perl interpreters; they should only be called once regardless of how many interpreters you create or destroy. Call PERL_SYS_INIT3() before you create your first interpreter, and PERL_SYS_TERM() after you free your last interpreter.

PERL_SYS_INIT3() と PERL_SYS_TERM() のマクロは、Perl インタプリタを 実行するのに必要な C ランタイム環境の、システム固有の調整を提供します; これらはインタプリタが何回作成または破壊されたかに関わらず、1 回だけ 呼び出されるべきです。 最初のインタプリタを作る前に PERL_SYS_INIT3() を呼び出し、 最後のインタプリタを解放した後に PERL_SYS_TERM() を呼び出します。

Since PERL_SYS_INIT3() may change env, it may be more appropriate to provide env as an argument to perl_parse().

PERL_SYS_INIT3() は env を変更するかもしれないので、perl_parse() の 引数として env を提供する方がより適切です。

Also notice that no matter what arguments you pass to perl_parse(), PERL_SYS_INIT3() must be invoked on the C main() argc, argv and env and only once.

また、どんな引数を perl_parse() に渡したかに関わらず、PERL_SYS_INIT3() は C main() argc, argv, env から一度だけ起動されなければなりません。

Mind that argv[argc] must be NULL, same as those passed to a main function in C.

C の main 関数に渡されるものと同じように、 argv[argc] は NULL でなければならないことを注意してください。

Now compile this program (I'll call it interp.c) into an executable:

ここでこのプログラム(interp.c と呼びましょう)をコンパイルして 実行ファイルを作りましょう。

    % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

After a successful compilation, you'll be able to use interp just like perl itself:

コンパイルに成功すれば、perl そのものと同じように interp を使うことができるでしょう。

    % interp
    print "Pretty Good Perl \n";
    print "10890 - 9801 is ", 10890 - 9801;
    <CTRL-D>
    Pretty Good Perl
    10890 - 9801 is 1089

or

または

    % interp -e 'printf("%x", 3735928559)'
    deadbeef

You can also read and execute Perl statements from a file while in the midst of your C program, by placing the filename in argv[1] before calling perl_run.

perl_run を呼び出す前に argv[1] にファイル名を置くことで、 C プログラムの中ほどで Perl 文をファイルから読み込んで実行するという こともできます。

あなたの C プログラムから Perl のサブルーチンを呼ぶ

To call individual Perl subroutines, you can use any of the call_* functions documented in perlcall. In this example we'll use call_argv.

独立した Perl サブルーチンを呼び出すために、perlcall に記載されている call_* の類の関数を使うことができます。 次の例では call_argv を使います。

That's shown below, in a program I'll call showtime.c.

以下に示すのは、showtime.c という名前のプログラムです。

    #include <EXTERN.h>
    #include <perl.h>

    static PerlInterpreter *my_perl;

    int main(int argc, char **argv, char **env)
    {
        char *args[] = { NULL };
        PERL_SYS_INIT3(&argc,&argv,&env);
        my_perl = perl_alloc();
        perl_construct(my_perl);

        perl_parse(my_perl, NULL, argc, argv, NULL);
        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;

        /*** skipping perl_run() ***/

        call_argv("showtime", G_DISCARD | G_NOARGS, args);

        perl_destruct(my_perl);
        perl_free(my_perl);
        PERL_SYS_TERM();
        exit(EXIT_SUCCESS);
    }

where showtime is a Perl subroutine that takes no arguments (that's the G_NOARGS) and for which I'll ignore the return value (that's the G_DISCARD). Those flags, and others, are discussed in perlcall.

showtime は引数をとらない Perl サブルーチン(G_NOARGS)で、その 戻り値を無視します(G_DISCARD)。 これらのフラグ等は perlcall に説明されています。

I'll define the showtime subroutine in a file called showtime.pl:

showtime.pl と呼ばれるファイルで、showtime サブルーチンを 定義しましょう:

 print "I shan't be printed.";

 sub showtime {
     print time;
 }

Simple enough. Now compile and run:

単純にして十分です。 さあコンパイルして実行してみましょう:

 % cc -o showtime showtime.c \
     `perl -MExtUtils::Embed -e ccopts -e ldopts`
 % showtime showtime.pl
 818284590

yielding the number of seconds that elapsed between January 1, 1970 (the beginning of the Unix epoch), and the moment I began writing this sentence.

1970 年 1 月 1 日(UNIX 紀元の開始時点)からこのセンテンスを書いた時点までの 経過秒数が得られます。

In this particular case we don't have to call perl_run, as we set the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in perl_destruct.

この特殊な状況では、私たちは perl_run を呼ぶ必要はありません; perl_destruct で END ブロックを実行する PL_exit_flag PERL_EXIT_DESTRUCT_END をセットしているからです。

If you want to pass arguments to the Perl subroutine, you can add strings to the NULL-terminated args list passed to call_argv. For other data types, or to examine return values, you'll need to manipulate the Perl stack. That's demonstrated in "Fiddling with the Perl stack from your C program".

Perl サブルーチンに引数を渡したいという場合、call_argv に 渡される NULL で終端されたリスト args に文字列を追加することが できます。 他のデータ型を使ったり戻り値をチェックするには Perl スタックを 操作する必要があるでしょう。 これは本ドキュメントの最後の セクション "Fiddling with the Perl stack from your C program" で 説明されています。

CプログラムからPerlの文を評価する

Perl provides two API functions to evaluate pieces of Perl code. These are "eval_sv" in perlapi and "eval_pv" in perlapi.

Perl は Perl コードのかけら(pieces of Perl code)を評価するための二つの API 関数を提供しています。 "eval_sv" in perlapi"eval_pv" in perlapi です。

Arguably, these are the only routines you'll ever need to execute snippets of Perl code from within your C program. Your code can be as long as you wish; it can contain multiple statements; it can employ "use" in perlfunc, "require" in perlfunc, and "do" in perlfunc to include external Perl files.

これらの関数は、C プログラムの中で Perl のコードの断片を実行するのに 必要だったルーチンにすぎません。 あなたはコードを好きなだけ長くでき、複数の文を含むことができます; また、外部の Perl ファイルを取り込むために "use" in perlfunc, "require" in perlfunc, "do" in perlfunc を使うことができます。

eval_pv lets us evaluate individual Perl strings, and then extract variables for coercion into C types. The following program, string.c, executes three Perl strings, extracting an int from the first, a float from the second, and a char * from the third.

eval_pv は独立した Perl の文字列を評価し、強制的に C の型へと 変数を展開します。 以下に示すプログラムは string.c は、三つの Perl 文字列を実行し、最初のものを int に、二番目のものを float に、 三番目のものを char *へ 展開します。

 #include <EXTERN.h>
 #include <perl.h>

 static PerlInterpreter *my_perl;

 main (int argc, char **argv, char **env)
 {
     char *embedding[] = { "", "-e", "0", NULL };

     PERL_SYS_INIT3(&argc,&argv,&env);
     my_perl = perl_alloc();
     perl_construct( my_perl );

     perl_parse(my_perl, NULL, 3, embedding, NULL);
     PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
     perl_run(my_perl);

     /** Treat $a as an integer **/
     eval_pv("$a = 3; $a **= 2", TRUE);
     printf("a = %d\n", SvIV(get_sv("a", 0)));

     /** Treat $a as a float **/
     eval_pv("$a = 3.14; $a **= 2", TRUE);
     printf("a = %f\n", SvNV(get_sv("a", 0)));

     /** Treat $a as a string **/
     eval_pv(
       "$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
     printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));

     perl_destruct(my_perl);
     perl_free(my_perl);
     PERL_SYS_TERM();
 }

All of those strange functions with sv in their names help convert Perl scalars to C types. They're described in perlguts and perlapi.

名前に sv の付いた奇妙な関数は Perl のスカラから C の型への変換を 手助けします。 これらは perlgutsperlapi に記述されています。

If you compile and run string.c, you'll see the results of using SvIV() to create an int, SvNV() to create a float, and SvPV() to create a string:

string.c をコンパイルして実行すれば、SvIV() を使って int を、 SvNV() を使って float を、SvPV() を使って文字列を生成した 結果を見ることになるでしょう。

   a = 9
   a = 9.859600
   a = Just Another Perl Hacker

In the example above, we've created a global variable to temporarily store the computed value of our eval'ed expression. It is also possible and in most cases a better strategy to fetch the return value from eval_pv() instead. Example:

先の例では、私たちが式を評価した値を一時的に格納するためのグローバル 変数を生成しました。 これと同様なことが eval_pv() の戻り値を取ることで可能であり、かつ ほとんどの場合にはこれが良い戦略なのです。 例えば:

   ...
   SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
   printf("%s\n", SvPV_nolen(val));
   ...

This way, we avoid namespace pollution by not creating global variables and we've simplified our code as well.

このやり方によればグローバル変数を生成せず、またプログラムを単純に したことによって名前空間の汚染を防ぎます。

CプログラムからPerlのパターンマッチングと置換を使ってみる

The eval_sv() function lets us evaluate strings of Perl code, so we can define some functions that use it to "specialize" in matches and substitutions: match(), substitute(), and matches().

関数 eval_pv は Perl コードの文字列を評価するものなので、 私たちはマッチや置換に「特化」(specilalize)するために使う match(), substitute(), matches()といった幾つかの関数を 定義できました。

   I32 match(SV *string, char *pattern);

Given a string and a pattern (e.g., m/clasp/ or /\b\w*\b/, which in your C program might appear as "/\\b\\w*\\b/"), match() returns 1 if the string matches the pattern and 0 otherwise.

文字列と m/clasp//\b\w*\b/ のようなパターン(これは C プログラムでは"/\\b\\w*\\b/" のようになっているでしょう)を与えると、 match() は文字列がパターンにマッチしたときには1を、そうでないときは 0 を返します。

   int substitute(SV **string, char *pattern);

Given a pointer to an SV and an =~ operation (e.g., s/bob/robert/g or tr[A-Z][a-z]), substitute() modifies the string within the SV as according to the operation, returning the number of substitutions made.

SV へのポインタと =~ 操作(s/bob/robert/g もしくは tr[A-Z][a-z])を与えると、substitue() はその操作に従って SV の中の文字列の書き換えを行って、置換の回数を返します。

   SSize_t matches(SV *string, char *pattern, AV **matches);

Given an SV, a pattern, and a pointer to an empty AV, matches() evaluates $string =~ $pattern in a list context, and fills in matches with the array elements, returning the number of matches found.

SV、パターン、空の AV へのポインタを渡すと、 matchs() はリストコンテキストで $string =~ $pattern を評価して matches を配列の要素(メモリを割り当てます)で満たし、マッチした 回数を返します。

Here's a sample program, match.c, that uses all three (long lines have been wrapped here):

以下に示すのはサンプルプログラム match.c で、三つの関数すべてを 使います(長い行は整形されてます)。

 #include <EXTERN.h>
 #include <perl.h>

 static PerlInterpreter *my_perl;

 /** my_eval_sv(code, error_check)
 ** kinda like eval_sv(),
 ** but we pop the return value off the stack
 **/
 SV* my_eval_sv(SV *sv, I32 croak_on_error)
 {
     dSP;
     SV* retval;

     PUSHMARK(SP);
     eval_sv(sv, G_SCALAR);

     SPAGAIN;
     retval = POPs;
     PUTBACK;

     if (croak_on_error && SvTRUE(ERRSV))
        croak_sv(ERRSV);

     return retval;
 }

 /** match(string, pattern)
 **
 ** Used for matches in a scalar context.
 **
 ** Returns 1 if the match was successful; 0 otherwise.
 **/

 I32 match(SV *string, char *pattern)
 {
     SV *command = newSV(0), *retval;

     sv_setpvf(command, "my $string = '%s'; $string =~ %s",
              SvPV_nolen(string), pattern);

     retval = my_eval_sv(command, TRUE);
     SvREFCNT_dec(command);

     return SvIV(retval);
 }

 /** substitute(string, pattern)
 **
 ** Used for =~ operations that
 ** modify their left-hand side (s/// and tr///)
 **
 ** Returns the number of successful matches, and
 ** modifies the input string if there were any.
 **/

 I32 substitute(SV **string, char *pattern)
 {
     SV *command = newSV(0), *retval;

     sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
              SvPV_nolen(*string), pattern);

     retval = my_eval_sv(command, TRUE);
     SvREFCNT_dec(command);

     *string = get_sv("string", 0);
     return SvIV(retval);
 }

 /** matches(string, pattern, matches)
 **
 ** Used for matches in a list context.
 **
 ** Returns the number of matches,
 ** and fills in **matches with the matching substrings
 **/

 SSize_t matches(SV *string, char *pattern, AV **match_list)
 {
     SV *command = newSV(0);
     SSize_t num_matches;

     sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
              SvPV_nolen(string), pattern);

     my_eval_sv(command, TRUE);
     SvREFCNT_dec(command);

     *match_list = get_av("array", 0);
     num_matches = av_top_index(*match_list) + 1;

     return num_matches;
 }

 main (int argc, char **argv, char **env)
 {
     char *embedding[] = { "", "-e", "0", NULL };
     AV *match_list;
     I32 num_matches, i;
     SV *text;

     PERL_SYS_INIT3(&argc,&argv,&env);
     my_perl = perl_alloc();
     perl_construct(my_perl);
     perl_parse(my_perl, NULL, 3, embedding, NULL);
     PL_exit_flags |= PERL_EXIT_DESTRUCT_END;

     text = newSV(0);
     sv_setpv(text, "When he is at a convenience store and the "
        "bill comes to some amount like 76 cents, Maynard is "
        "aware that there is something he *should* do, something "
        "that will enable him to get back a quarter, but he has "
        "no idea *what*.  He fumbles through his red squeezey "
        "changepurse and gives the boy three extra pennies with "
        "his dollar, hoping that he might luck into the correct "
        "amount.  The boy gives him back two of his own pennies "
        "and then the big shiny quarter that is his prize. "
        "-RICHH");

     if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
        printf("match: Text contains the word 'quarter'.\n\n");
     else
        printf("match: Text doesn't contain the word 'quarter'.\n\n");

     if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
        printf("match: Text contains the word 'eighth'.\n\n");
     else
        printf("match: Text doesn't contain the word 'eighth'.\n\n");

     /** Match all occurrences of /wi../ **/
     num_matches = matches(text, "m/(wi..)/g", &match_list);
     printf("matches: m/(wi..)/g found %d matches...\n", num_matches);

     for (i = 0; i < num_matches; i++)
         printf("match: %s\n",
                  SvPV_nolen(*av_fetch(match_list, i, FALSE)));
     printf("\n");

     /** Remove all vowels from text **/
     num_matches = substitute(&text, "s/[aeiou]//gi");
     if (num_matches) {
        printf("substitute: s/[aeiou]//gi...%lu substitutions made.\n",
               (unsigned long)num_matches);
        printf("Now text is: %s\n\n", SvPV_nolen(text));
     }

     /** Attempt a substitution **/
     if (!substitute(&text, "s/Perl/C/")) {
        printf("substitute: s/Perl/C...No substitution made.\n\n");
     }

     SvREFCNT_dec(text);
     PL_perl_destruct_level = 1;
     perl_destruct(my_perl);
     perl_free(my_perl);
     PERL_SYS_TERM();
 }

which produces the output (again, long lines have been wrapped here)

この出力は以下のようになります(繰り返しますが、長い行は 整形されています)。

  match: Text contains the word 'quarter'.

  match: Text doesn't contain the word 'eighth'.

  matches: m/(wi..)/g found 2 matches...
  match: will
  match: with

  substitute: s/[aeiou]//gi...139 substitutions made.
  Now text is: Whn h s t  cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
  Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt
  bck qrtr, bt h hs n d *wht*.  H fmbls thrgh hs rd sqzy chngprs nd
  gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct
  mnt.  Th by gvs hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s
  hs prz. -RCHH

  substitute: s/Perl/C...No substitution made.

C プログラムから Perl のスタックを見つけだす

When trying to explain stacks, most computer science textbooks mumble something about spring-loaded columns of cafeteria plates: the last thing you pushed on the stack is the first thing you pop off. That'll do for our purposes: your C program will push some arguments onto "the Perl stack", shut its eyes while some magic happens, and then pop the results--the return value of your Perl subroutine--off the stack.

スタックを説明しようとするとき、ほとんどのコンピュータ科学の教科書は 食堂のプレート皿のばね仕掛けの仕切りのようなはっきりとしない解説をします: 最後にスタックに押し込んだ(push)ものが最初に取り出す(pop)ものです。 これが、私たちの目的のために行うことです: あなたの C プログラムでは、幾つかの 引数を「Perl スタック」へプッシュして、魔法が掛かる間に目を閉じれば結果、 つまりあなたの使った Perl サブルーチンの戻り値がスタックの一番上に できます -- これをポップします。

First you'll need to know how to convert between C types and Perl types, with newSViv() and sv_setnv() and newAV() and all their friends. They're described in perlguts and perlapi.

まず第一に、あなたは newSViv()、sv_setnv()、newAV() そしてその他の 関数を使った C の型と Perl の型との間の変換の方法を知る必要があります。 これらは perlgutsperlapi に記述されています。

Then you'll need to know how to manipulate the Perl stack. That's described in perlcall.

それから Perl スタックの操作方法を知る必要があります。 これは perlcall に説明があります。

Once you've understood those, embedding Perl in C is easy.

これらを理解すれば、C に Perl を組み込むのは簡単です。

Because C has no builtin function for integer exponentiation, let's make Perl's ** operator available to it (this is less useful than it sounds, because Perl implements ** with C's pow() function). First I'll create a stub exponentiation function in power.pl:

C には整数のべき乗を行う組み込み関数がないので、Perl の ** 演算子を 使えるようにしましょう(これは思ったほど便利ではありません; なぜなら Perl は ** を C の pow() 関数を使って実装しているからです)。 最初に power.pl にべき乗関数を作成しましょう。

    sub expo {
        my ($a, $b) = @_;
        return $a ** $b;
    }

Now I'll create a C program, power.c, with a function PerlPower() that contains all the perlguts necessary to push the two arguments into expo() and to pop the return value out. Take a deep breath...

今度は expo() への二つの引数をプッシュするのとそこからの戻り値 をポップするに必要なすべての perlguts を含んでいる PerlPower() と いう関数を持った C プログラム power.c を作ります。 深く息をすって…

 #include <EXTERN.h>
 #include <perl.h>

 static PerlInterpreter *my_perl;

 static void
 PerlPower(int a, int b)
 {
   dSP;                            /* initialize stack pointer      */
   ENTER;                          /* everything created after here */
   SAVETMPS;                       /* ...is a temporary variable.   */
   PUSHMARK(SP);                   /* remember the stack pointer    */
   XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack  */
   XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack  */
   PUTBACK;                      /* make local stack pointer global */
   call_pv("expo", G_SCALAR);      /* call the function             */
   SPAGAIN;                        /* refresh stack pointer         */
                                 /* pop the return value from stack */
   printf ("%d to the %dth power is %d.\n", a, b, POPi);
   PUTBACK;
   FREETMPS;                       /* free that return value        */
   LEAVE;                       /* ...and the XPUSHed "mortal" args.*/
 }

 int main (int argc, char **argv, char **env)
 {
   char *my_argv[] = { "", "power.pl", NULL };

   PERL_SYS_INIT3(&argc,&argv,&env);
   my_perl = perl_alloc();
   perl_construct( my_perl );

   perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
   PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
   perl_run(my_perl);

   PerlPower(3, 4);                      /*** Compute 3 ** 4 ***/

   perl_destruct(my_perl);
   perl_free(my_perl);
   PERL_SYS_TERM();
   exit(EXIT_SUCCESS);
 }

Compile and run:

コンパイルして実行しましょう:

    % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

    % power
    3 to the 4th power is 81.

永続的インタプリタの保持

When developing interactive and/or potentially long-running applications, it's a good idea to maintain a persistent interpreter rather than allocating and constructing a new interpreter multiple times. The major reason is speed: since Perl will only be loaded into memory once.

対話的であるとか、長い時間実行される可能性のあるアプリケーションを 開発するとき、複数回新しいインタプリタを割り当てて構築するよりは永続的な インタプリタを保持するのが良い考えです。 主な理由はスピードです: (永続的にすることで)Perl はメモリーに一度しか ロードされません。

However, you have to be more cautious with namespace and variable scoping when using a persistent interpreter. In previous examples we've been using global variables in the default package main. We knew exactly what code would be run, and assumed we could avoid variable collisions and outrageous symbol table growth.

しかしながら永続的なインタプリタを使うときには、名前空間や変数の スコープをより注意深く扱わねばならないでしょう。 先の例では、私たちはデフォルトパッケージ main でグローバル変数を 使いました。 私たちは実際にあのコードが実行できることを知りましたが、変数の衝突や シンボルテーブル拡大の限界に当たらないことを仮定していました。

Let's say your application is a server that will occasionally run Perl code from some arbitrary file. Your server has no way of knowing what code it's going to run. Very dangerous.

あなたのアプリケーションが、時折幾つかの任意のファイルから Perl コードが 実行されるサーバーであるとしましょう。 あなたのサーバーは実行させたコードを知る術がありません。 非常に危険です。

If the file is pulled in by perl_parse(), compiled into a newly constructed interpreter, and subsequently cleaned out with perl_destruct() afterwards, you're shielded from most namespace troubles.

ファイルが perl_parse() を使って引き込まれた場合、新しく構築された インタプリタへコンパイルされ、後の perl_destruct() で始末されます; これによってほとんどの名前空間にまつわるトラブルから守られます。

One way to avoid namespace collisions in this scenario is to translate the filename into a guaranteed-unique package name, and then compile the code into that package using "eval" in perlfunc. In the example below, each file will only be compiled once. Or, the application might choose to clean out the symbol table associated with the file after it's no longer needed. Using "call_argv" in perlapi, We'll call the subroutine Embed::Persistent::eval_file which lives in the file persistent.pl and pass the filename and boolean cleanup/cache flag as arguments.

このシナリオにおいて名前空間の衝突を防ぐ一つの方法は、ファイル名を ユニークであることが保証されているパッケージ名に変換し、それから "eval" in perlfunc を使ったコードにコンパイルするのです。 先の例では、各ファイルは一回だけコンパイルされました。 あるいは、アプリケーションはファイルに結び付けられたシンボルテーブルを それが必要なくなった時点で掃除してしまうことを選択するかもしれません。 "call_argv" in perlapi を使うことで、私たちは persistent.pl という ファイルにあるサブルーチン Embed::Persistent::eval_file を呼び出し、それに ファイル名と cleanup/cache を表わすブール値を引数として渡します。

Note that the process will continue to grow for each file that it uses. In addition, there might be AUTOLOADed subroutines and other conditions that cause Perl's symbol table to grow. You might want to add some logic that keeps track of the process size, or restarts itself after a certain number of requests, to ensure that memory consumption is minimized. You'll also want to scope your variables with "my" in perlfunc whenever possible.

プロセスはそれぞれのファイルを使うごとに大きくなるということに 注意してください。 それに加えて、AUTOLOAD されたサブルーチンなどの条件によっても、 Perl のシンボルテーブルは大きくなります。 あなたはプロセスの大きさを記録しつづける何等かのロジックを 欲するかもしれませんし、あるいはメモリの消費量を最少にするために 特定回数のリクエストの後で自分自身を 再スタートするようにしたいかもしれません。 また、可能であるときにはいつでも "my" in perlfunc を使ってあなたの 使う変数を見通したいでしょう。

 package Embed::Persistent;
 #persistent.pl

 use strict;
 our %Cache;
 use Symbol qw(delete_package);

 sub valid_package_name {
     my($string) = @_;
     $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
     # second pass only for words starting with a digit
     $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;

     # Dress it up as a real package name
     $string =~ s|/|::|g;
     return "Embed" . $string;
 }

 sub eval_file {
     my($filename, $delete) = @_;
     my $package = valid_package_name($filename);
     my $mtime = -M $filename;
     if(defined $Cache{$package}{mtime}
        &&
        $Cache{$package}{mtime} <= $mtime)
     {
        # we have compiled this subroutine already,
        # it has not been updated on disk, nothing left to do
        print STDERR "already compiled $package->handler\n";
     }
     else {
        local *FH;
        open FH, $filename or die "open '$filename' $!";
        local($/) = undef;
        my $sub = <FH>;
        close FH;

        #wrap the code into a subroutine inside our unique package
        my $eval = qq{package $package; sub handler { $sub; }};
        {
            # hide our variables within this block
            my($filename,$mtime,$package,$sub);
            eval $eval;
        }
        die $@ if $@;

        #cache it unless we're cleaning out each time
        $Cache{$package}{mtime} = $mtime unless $delete;
     }

     eval {$package->handler;};
     die $@ if $@;

     delete_package($package) if $delete;

     #take a look if you want
     #print Devel::Symdump->rnew($package)->as_string, $/;
 }

 1;

 __END__

 /* persistent.c */
 #include <EXTERN.h>
 #include <perl.h>

 /* 1 = clean out filename's symbol table after each request,
    0 = don't
 */
 #ifndef DO_CLEAN
 #define DO_CLEAN 0
 #endif

 #define BUFFER_SIZE 1024

 static PerlInterpreter *my_perl = NULL;

 int
 main(int argc, char **argv, char **env)
 {
     char *embedding[] = { "", "persistent.pl", NULL };
     char *args[] = { "", DO_CLEAN, NULL };
     char filename[BUFFER_SIZE];
     int failing, exitstatus;

     PERL_SYS_INIT3(&argc,&argv,&env);
     if((my_perl = perl_alloc()) == NULL) {
        fprintf(stderr, "no memory!");
        exit(EXIT_FAILURE);
     }
     perl_construct(my_perl);

     PL_origalen = 1; /* don't let $0 assignment update the
                         proctitle or embedding[0] */
     failing = perl_parse(my_perl, NULL, 2, embedding, NULL);
     PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
     if(!failing)
        failing = perl_run(my_perl);
     if(!failing) {
        while(printf("Enter file name: ") &&
              fgets(filename, BUFFER_SIZE, stdin)) {

            filename[strlen(filename)-1] = '\0'; /* strip \n */
            /* call the subroutine,
                     passing it the filename as an argument */
            args[0] = filename;
            call_argv("Embed::Persistent::eval_file",
                           G_DISCARD | G_EVAL, args);

            /* check $@ */
            if(SvTRUE(ERRSV))
                fprintf(stderr, "eval error: %s\n", SvPV_nolen(ERRSV));
        }
     }

     PL_perl_destruct_level = 0;
     exitstatus = perl_destruct(my_perl);
     perl_free(my_perl);
     PERL_SYS_TERM();
     exit(exitstatus);
 }

Now compile:

さあ、コンパイルしましょう:

 % cc -o persistent persistent.c \
        `perl -MExtUtils::Embed -e ccopts -e ldopts`

Here's an example script file:

スクリプトファイルの例です。

 #test.pl
 my $string = "hello";
 foo($string);

 sub foo {
     print "foo says: @_\n";
 }

Now run:

これを実行してみましょう:

 % persistent
 Enter file name: test.pl
 foo says: hello
 Enter file name: test.pl
 already compiled Embed::test_2epl->handler
 foo says: hello
 Enter file name: ^C

END ブロックの実行

Traditionally END blocks have been executed at the end of the perl_run. This causes problems for applications that never call perl_run. Since perl 5.7.2 you can specify PL_exit_flags |= PERL_EXIT_DESTRUCT_END to get the new behaviour. This also enables the running of END blocks if the perl_parse fails and perl_destruct will return the exit value.

伝統的に END ブロックは perl_run の最後に実行されてきました。 これは、perl_run を呼び出さないアプリケーションで問題となります。 perl 5.7.2 から、新しい振る舞いを取らせるために PL_exit_flags |= PERL_EXIT_DESTRUCT_END を指定できます。 これはまた、もし perl_parse が失敗して perl_destruct が終了値を返した ときにも END ブロックを実行するようにします。

$0 への代入

When a perl script assigns a value to $0 then the perl runtime will try to make this value show up as the program name reported by "ps" by updating the memory pointed to by the argv passed to perl_parse() and also calling API functions like setproctitle() where available. This behaviour might not be appropriate when embedding perl and can be disabled by assigning the value 1 to the variable PL_origalen before perl_parse() is called.

perl スクリプトが $0 に値を代入すると、perl のランタイムは、perl_parse() に 渡された argv が指すメモリを更新して、利用可能なら setproctitle() のような API 関数も呼び出すことによって、その値を "ps" で報告される プログラム名として表示させようとします。 この振る舞いは組み込み perl では不適切かもしれないので、perl_parse() が 呼び出される前に PL_origalen1 を代入することで無効にできます。

The persistent.c example above is for instance likely to segfault when $0 is assigned to if the PL_origalen = 1; assignment is removed. This because perl will try to write to the read only memory of the embedding[] strings.

例えば、上述の persistent.c の例は、もし PL_origalen = 1; 代入を 取り除くと、$0 が代入されたときにおそらくセグメンテーションフォルトが 起きるでしょう。 これは embedding[] 文字列の読み込み専用メモリに 書き込もうとするからです。

複数のインタプリタのインスタンスを保持する

Some rare applications will need to create more than one interpreter during a session. Such an application might sporadically decide to release any resources associated with the interpreter.

ごく一部のアプリケーションでは、二つ以上のインタプリタを生成する 必要があるかもしれません。 そのようなアプリケーションはインタプリタに結び付けられたリソースを 解放することを決定することがあるかもしれません。

The program must take care to ensure that this takes place before the next interpreter is constructed. By default, when perl is not built with any special options, the global variable PL_perl_destruct_level is set to 0, since extra cleaning isn't usually needed when a program only ever creates a single interpreter in its entire lifetime.

プログラムは次のインタプリタが構築されるより前に、解放が 発生することに注意を払い、それを保証しなければなりません。 デフォルトでは、perl が特殊なオプション付きでビルドされていなければ、 グローバル変数 PL_perl_destruct_level0 に設定されています; これはプログラムが生涯ただ一つのインタプリタを作っただけの ときには、普通は余分な後始末が不要であるからです。

Setting PL_perl_destruct_level to 1 makes everything squeaky clean:

全てを始末させるためには PL_perl_destruct_level1 に設定します。

 while(1) {
     ...
     /* reset global variables here with PL_perl_destruct_level = 1 */
     PL_perl_destruct_level = 1;
     perl_construct(my_perl);
     ...
     /* clean and reset _everything_ during perl_destruct */
     PL_perl_destruct_level = 1;
     perl_destruct(my_perl);
     perl_free(my_perl);
     ...
     /* let's go do it again! */
 }

When perl_destruct() is called, the interpreter's syntax parse tree and symbol tables are cleaned up, and global variables are reset. The second assignment to PL_perl_destruct_level is needed because perl_construct resets it to 0.

perl_destruct() が呼ばれたとき、インタプリタの構文解析木と シンボルテーブルは始末され、そしてグローバル変数がリセットされます。 PL_perl_destruct_level への第 2 引数は、perl_construct を 0 に リセットするために必要です。

Now suppose we have more than one interpreter instance running at the same time. This is feasible, but only if you used the Configure option -Dusemultiplicity or the options -Dusethreads -Duseithreads when building perl. By default, enabling one of these Configure options sets the per-interpreter global variable PL_perl_destruct_level to 1, so that thorough cleaning is automatic and interpreter variables are initialized correctly. Even if you don't intend to run two or more interpreters at the same time, but to run them sequentially, like in the above example, it is recommended to build perl with the -Dusemultiplicity option otherwise some interpreter variables may not be initialized correctly between consecutive runs and your application may crash.

現在、二つ以上のインタプリタのインスタンスを同時に実行することが サポートされています。 これは可能なことですが、Perlビルドしたときに Configure オプション -Dusemultiplicity-Dusethreads -Duseithreads を 使ったときのみです。 デフォルトでは、これらの Configure オプションの一つが有効になると インタプリタ単位のグローバル変数 PL_perl_destruct_level1 に 設定され、これによって徹底的なクリーニングは自動的で、インタプリタ変数は 正しく初期化されます。 同時に複数のインタプリタを実行するつもりがない場合でも、上述の例のように 順番に実行させるつもりなら、-Dusemultiplicity オプションをつけて perl をビルドすることを推奨します; さもなければ連続した実行の間に インタプリタ変数が正しく初期化されずに、アプリケーションが クラッシュするかもしれません。

"Thread-aware system interfaces" in perlxs も参照してください。

Using -Dusethreads -Duseithreads rather than -Dusemultiplicity is more appropriate if you intend to run multiple interpreters concurrently in different threads, because it enables support for linking in the thread libraries of your system with the interpreter.

もし、異なるスレッドで同時に複数のインタプリタを実行するつもりなら、 -Dusemultiplicity ではなく -Dusethreads -Duseithreads がより適切です; なぜならこれはインタプリタにシステムのスレッドライブラリを リンクすることへの対応を有効にするからです。

Let's give it a try:

試してみましょう:

 #include <EXTERN.h>
 #include <perl.h>

 /* we're going to embed two interpreters */

 #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"

 int main(int argc, char **argv, char **env)
 {
     PerlInterpreter *one_perl, *two_perl;
     char *one_args[] = { "one_perl", SAY_HELLO, NULL };
     char *two_args[] = { "two_perl", SAY_HELLO, NULL };

     PERL_SYS_INIT3(&argc,&argv,&env);
     one_perl = perl_alloc();
     two_perl = perl_alloc();

     PERL_SET_CONTEXT(one_perl);
     perl_construct(one_perl);
     PERL_SET_CONTEXT(two_perl);
     perl_construct(two_perl);

     PERL_SET_CONTEXT(one_perl);
     perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
     PERL_SET_CONTEXT(two_perl);
     perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);

     PERL_SET_CONTEXT(one_perl);
     perl_run(one_perl);
     PERL_SET_CONTEXT(two_perl);
     perl_run(two_perl);

     PERL_SET_CONTEXT(one_perl);
     perl_destruct(one_perl);
     PERL_SET_CONTEXT(two_perl);
     perl_destruct(two_perl);

     PERL_SET_CONTEXT(one_perl);
     perl_free(one_perl);
     PERL_SET_CONTEXT(two_perl);
     perl_free(two_perl);
     PERL_SYS_TERM();
     exit(EXIT_SUCCESS);
 }

Note the calls to PERL_SET_CONTEXT(). These are necessary to initialize the global state that tracks which interpreter is the "current" one on the particular process or thread that may be running it. It should always be used if you have more than one interpreter and are making perl API calls on both interpreters in an interleaved fashion.

PERL_SET_CONTEXT() の呼び出しに注意してください。 実行されている個々のプロセスやスレッドで、どのインタプリタが 「カレント」なのかを追跡するグローバルな状態を初期化するために必要です。 もし複数のインタプリタがあって、両方のインタプリタに交互に perl API 呼び出しを行うなら、常にこれを行うべきです。

PERL_SET_CONTEXT(interp) should also be called whenever interp is used by a thread that did not create it (using either perl_alloc(), or the more esoteric perl_clone()).

(perl_alloc() か、より難解な perl_clone() を使って、) interp を 作ったのではないスレッドによって使われるときはいつでも、 PERL_SET_CONTEXT(interp) も呼び出されるべきです。

Compile as usual:

いつもと同じようにコンパイルします:

 % cc -o multiplicity multiplicity.c \
  `perl -MExtUtils::Embed -e ccopts -e ldopts`

Run it, Run it:

実行、実行:

 % multiplicity
 Hi, I'm one_perl
 Hi, I'm two_perl

C プログラムから、C のライブラリを使っている Perl モジュールを使う

If you've played with the examples above and tried to embed a script that use()s a Perl module (such as Socket) which itself uses a C or C++ library, this probably happened:

あなたがこれまでにでてきた例を使っていて、(Socket のような)そ れ自身が C や C++ のライブラリを使っている Perl モジュールを use() しているスクリプトを埋め込もうとしているのであれば、こうなる 可能性があります。

 Can't load module Socket, dynamic loading not available in this perl.
  (You may need to build a new perl executable which either supports
  dynamic loading or has the Socket module statically linked into it.)

What's wrong?

なにがまずいのでしょう?

Your interpreter doesn't know how to communicate with these extensions on its own. A little glue will help. Up until now you've been calling perl_parse(), handing it NULL for the second argument:

あなたの使うインタプリタはこういったエクステンションと どのように交信するのかを知りません。 ちょっとした糊(glue)が助けになります。 これまでは、perl_parse() を呼び出すときにはその第二引数として NULL を使っていました:

 perl_parse(my_perl, NULL, argc, my_argv, NULL);

That's where the glue code can be inserted to create the initial contact between Perl and linked C/C++ routines. Let's take a look some pieces of perlmain.c to see how Perl does this:

ここは Perl と、リンクされた C/C++ ルーチンとの間の初期化時の交信を 生成するために挿入することのできる糊コード(glue code)の場所です。 Perl がどのようにこれを行っているのかを知るために、perlmain.c の 一部を見てみましょう。

 static void xs_init (pTHX);

 EXTERN_C void boot_DynaLoader (pTHX_ CV* cv);
 EXTERN_C void boot_Socket (pTHX_ CV* cv);

 EXTERN_C void
 xs_init(pTHX)
 {
        char *file = __FILE__;
        /* DynaLoader is a special case */
        newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
        newXS("Socket::bootstrap", boot_Socket, file);
 }

Simply put: for each extension linked with your Perl executable (determined during its initial configuration on your computer or when adding a new extension), a Perl subroutine is created to incorporate the extension's routines. Normally, that subroutine is named Module::bootstrap() and is invoked when you say use Module. In turn, this hooks into an XSUB, boot_Module, which creates a Perl counterpart for each of the extension's XSUBs. Don't worry about this part; leave that to the xsubpp and extension authors. If your extension is dynamically loaded, DynaLoader creates Module::bootstrap() for you on the fly. In fact, if you have a working DynaLoader then there is rarely any need to link in any other extensions statically.

あなたの使う Perl の実行ファイルにリンクされているエクステンション毎に、 そのエクステンションのルーチンを組み込むための Perl サブルーチンが 生成されます。 通常はこういったサブルーチンは Module::bootstrap() という名称で、 あなたが use Module としたときに起動されます。 次にこれは、各エクステンションの XSUB に対する Perl の counterpart として 生成されるXSUB boot_Module にフックされます。 この部分に関して心配することはありません; xsubpp と、エクステンションの 作者に任せましょう。 あなたの使うエクステンションが動的ロードを必要とするならば、 DynaLoader はあなたのためにその場で Module::bootstrap() を生成します。 実際のところ、あなたが DynaLoader を使っているのであれば、他の エクステンションを静的にリンクする必要性はほとんどないでしょう。

Once you have this code, slap it into the second argument of perl_parse():

このコードを一度書いてしまえば、それを perl_parse() の第二引数に 置けます:

 perl_parse(my_perl, xs_init, argc, my_argv, NULL);

Then compile:

そしてコンパイルします:

 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

 % interp
   use Socket;
   use SomeDynamicallyLoadedModule;

   print "Now I can use extensions!\n"'

ExtUtils::Embed can also automate writing the xs_init glue code.

ExtUtils::Embedxs_init 糊コードを書くことを 自動化できます。

 % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
 % cc -c interp.c  `perl -MExtUtils::Embed -e ccopts`
 % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`

Consult perlxs, perlguts, and perlapi for more details.

詳しくは perlxs, perlguts, perlapi を参照してください。

POSIX ロケールで組み込み Perl を使う

(See perllocale for information about these.) When a Perl interpreter normally starts up, it tells the system it wants to use the system's default locale. This is often, but not necessarily, the "C" or "POSIX" locale. Absent a "use locale" within the perl code, this mostly has no effect (but see "Not within the scope of "use locale"" in perllocale). Also, there is not a problem if the locale you want to use in your embedded perl is the same as the system default. However, this doesn't work if you have set up and want to use a locale that isn't the system default one. Starting in Perl v5.20, you can tell the embedded Perl interpreter that the locale is already properly set up, and to skip doing its own normal initialization. It skips if the environment variable PERL_SKIP_LOCALE_INIT is set (even if set to 0 or ""). A perl that has this capability will define the C pre-processor symbol HAS_SKIP_LOCALE_INIT. This allows code that has to work with multiple Perl versions to do some sort of work-around when confronted with an earlier Perl.

(これらに関する情報については perllocale を参照してください。) Perl インタプリタが普通に開始したとき、システムのデフォルトのロケールを 使うということをシステムに伝えます。 これはたいてい "C" または "POSIX" ロケールですが、そうである必要はありません。 perl のコードに "use locale" がなければ、これはほとんど何の影響も ありません (しかし "Not within the scope of "use locale"" in perllocale を参照してください)。 また、組み込み Perl で使いたいロケールがシステムのデフォルトと同じ場合は 問題になりません。 しかし、システムのデフォルトではないロケールを設定して使いたい場合は 動作しません。 Perl v5.20 から、ロケールは既に適切に設定されているので、通常の初期化を 飛ばすように組み込み Perl インタプリタに伝えられます。 環境変数 PERL_SKIP_LOCALE_INIT が設定されていれば (たとえ 0 または "" に設定されていても) 飛ばされます。 この機能のある Perl は C プリプロセッサシンボル HAS_SKIP_LOCALE_INIT が 設定されています。 これにより、古い Perl に直面したときに、複数の Perl バージョンに対して何らかの 回避策をとれるようになります。

If your program is using the POSIX 2008 multi-thread locale functionality, you should switch into the global locale and set that up properly before starting the Perl interpreter. It will then properly switch back to using the thread-safe functions.

あなたのプログラムが POSIX 2008 マルチスレッドロケール機能を使っている場合、 Perl インタプリタを起動する前にグローバルロケールに切り替えて適切に 設定するべきです。 それからスレッドセーフ関数を使うように適切に戻します。

Perl_ を隠す

If you completely hide the short forms of the Perl public API, add -DPERL_NO_SHORT_NAMES to the compilation flags. This means that for example instead of writing

もし Perl public API の短い形式を完全に隠したいなら、 コンパイルオプションに -DPERL_NO_SHORT_NAMES を追加してください。 これは、例えば以下のように書く代わりに:

    warn("%d bottles of beer on the wall", bottlecount);

you will have to write the explicit full form

以下のように明示的に完全な形式で書く必要があります:

    Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);

(See "Background and PERL_IMPLICIT_CONTEXT" in perlguts for the explanation of the aTHX_. ) Hiding the short forms is very useful for avoiding all sorts of nasty (C preprocessor or otherwise) conflicts with other software packages (Perl defines about 2400 APIs with these short names, take or leave few hundred, so there certainly is room for conflict.)

(aTHX_ の説明については "Background and PERL_IMPLICIT_CONTEXT" in perlguts を参照してください。) 短い形式を隠すことは、その他のソフトウェアパッケージとのあらゆる種類の 不快なもの(C プリプロセッサやその他のもの)との衝突を避けるためにとても 便利です。

MORAL

You can sometimes write faster code in C, but you can always write code faster in Perl. Because you can use each from the other, combine them as you wish.

あなたは時々 C で より速いコードを 書くことができるかもしれませんが、 あなた常に Perl で コードをより早く 書くことができるのです。 これは片方でもう片方のものを作ることができ、望むままに 組み合わせることができるからです。

作者

Jon Orwant <orwant@media.mit.edu> and Doug MacEachern <dougm@covalent.net>, with small contributions from Tim Bunce, Tom Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya Zakharevich.

Jon Orwant <orwant@media.mit.edu> と Doug MacEachern <dougm@covalent.net>; さらに Tim Bunce, Tom Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, Ilya Zakharevich からの 小さな貢献によります。

Doug MacEachern has an article on embedding in Volume 1, Issue 4 of The Perl Journal ( http://www.tpj.com/ ). Doug is also the developer of the most widely-used Perl embedding: the mod_perl system (perl.apache.org), which embeds Perl in the Apache web server. Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl have used this model for Oracle, Netscape and Internet Information Server Perl plugins.

Doug MacEachern は The Perl Journal ( http://www.tpj.com/ ) の Volume 1, Issue 4 に組み込みの記事を書いています。 Doug はまた、もっとも広く使われている Perl 組み込みの作者です: mod_perl (perl.apache.org) は Apache ウェブサーバに Perl を組み込みます。 Oracle, Binary Evolution, ActiveState, Ben Sugars の nsapi_perl は このモデルを Oracle, Netscape, Internet Information Server の Perl プラグインに使っています。

コピーライト

Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All Rights Reserved.

This document may be distributed under the same terms as Perl itself.