perlembed - C プログラムへの Perl の埋め込み方 Do you want to: あなたのやりたいことは Use C from Perl? (Perl から C を使うことですか?) Read perlxstut, perlxs, h2xs, perlguts, and perlapi. 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にあるsystem、execに関することを読みましょう。 Use Perl from Perl? (Perl から Perl を使うことですか?) Read about perlfunc/do and perlfunc/eval and perlfunc/require and perlfunc/use. perlfunc/do、 perlfunc/eval、perlfunc/require、 perlfunc/useを読みましょう。 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.H と perl.h)が次のようなディレクトリに 置かれていることでしょう。 or perhaps just あるいは以下のような場所かもしれませんし or maybe something like こうかもしれません Execute this statement for a hint about where to find CORE: CORE の場所を見つけ出すために以下のような文を実行します。 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での場合) (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 を 使う場合では、オマジナイはちょっと違います。 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.h や perl.h が見つからないというエラーであれば、 -I の後にあるパスを変更する必要があります。 You may have to add extra libraries as well. Which ones? Perhaps those printed by おそらく、さらにライブラリを追加指定する必要があるでしょう。 どれを? おそらく以下のようにすれば表示されます: Provided your perl binary was properly configured and installed the ExtUtils::Embed module will determine all of this information for you: あなたの使っている perl のバイナリが適切なコンフィギュレーションが 行われているもので、かつ ExtUtils::Embed モジュールが インストールされていれば、これによって必要な全ての情報が決定できます。 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 です。 /* from the Perl distribution */ #include /* from the Perl distribution */ ]]> 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. The macros PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific tune up of the C runtime environment necessary to run Perl interpreters; since PERL_SYS_INIT3() may change env, it may be more appropriate to provide env as an argument to perl_parse(). ここで、env ポインタを使っていないことに注意してください。 通常は perl_parse はその最終引数として env を取りますが、 ここではカレントの環境をそのまま使うことを示す NULL に置き換えられています。 PERL_SYS_INIT3() と PERL_SYS_TERM() のマクロは、Perl インタプリタを 実行するのに必要な C ランタイム環境の、システム固有の調整を提供します; PERL_SYS_INIT3() は env を変更するかもしれないので、perl_parse() の 引数として env を提供する方がより適切です。 Now compile this program (I'll call it interp.c) into an executable: ここでこのプログラム(interp.c と呼びましょう)をコンパイルして 実行ファイルを作りましょう。 After a successful compilation, you'll be able to use interp just like perl itself: コンパイルに成功すれば、perl そのものと同じように interp を使うことができるでしょう。 Pretty Good Perl 10890 - 9801 is 1089 ]]> or または 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 ]]> 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 サブルーチンを 定義しましょう: Simple enough. Now compile and run: 単純にして十分です。 さあコンパイルして実行してみましょう: 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 perlapi/eval_sv and perlapi/eval_pv. Perl は Perl コードのかけら(pieces of Perl code)を評価するための二つの API 関数 perlapi/eval_sv と perlapi/eval_pv を提供しています。 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 perlfunc/use, perlfunc/require, and perlfunc/do to include external Perl files. これらの関数は、C プログラムの中で Perl のコードの断片を実行するのに 必要だったルーチンにすぎません。 あなたはコードを好きなだけ長くでき、複数の文を含むことができます。 また、外部の Perl ファイルを取り込むために perlfunc/use, perlfunc/require, perlfunc/do を使うことができます。 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 ]]> 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 の型への変換を 手助けします。 詳しい説明は perlguts と perlapi にあります。 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() を使って文字列を生成した 結果を見ることになるでしょう。 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() の戻り値を取ることで可能であり、かつ ほとんどの場合にはこれが良い戦略なのです。 例えば: 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()といった幾つかの関数を 定義できました。 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 を返します。 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 の中の文字列の書き換えを行って、置換の回数を返します。 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 ]]> which produces the output (again, long lines have been wrapped here) この出力は以下のようになります(繰り返しますが、長い行は 整形されています)。 (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 の型との間の変換の方法を知る必要があります。 これらは perlguts と perlapi に記述されています。 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 にべき乗関数を作成しましょう。 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 ]]> Compile and run: コンパイルして実行しましょう: (永続的インタプリタの保持) 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 perlfunc/eval. 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 perlapi/call_argv, 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. このシナリオにおいて名前空間の衝突を防ぐ一つの方法は、ファイル名を ユニークであることが保証されているパッケージ名に変換し、それから perlfunc/eval を使ったコードにコンパイルするのです。 先の例では、各ファイルは一回だけコンパイルされました。 あるいは、アプリケーションはファイルに結び付けられたシンボルテーブルを それが必要なくなった時点で掃除してしまうことを選択するかもしれません。 perlapi/call_argv を使うことで、私たちは 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 perlfunc/my whenever possible. プロセスはそれぞれのファイルを使うごとに大きくなるということに 注意してください。 それに加えて、AUTOLOAD されたサブルーチンなどの条件によっても、 Perl のシンボルテーブルは大きくなります。 あなたはプロセスの大きさを記録しつづける何等かのロジックを 欲するかもしれませんし、あるいはメモリの消費量を最少にするために 特定回数のリクエストの後で自分自身を 再スタートするようにしたいかもしれません。 また、可能であるときにはいつでも perlfunc/my を使ってあなたの 使う変数を見通したいでしょう。 handler\n"; } else { local *FH; open FH, $filename or die "open '$filename' $!"; local($/) = undef; my $sub = ; close FH; ]]> handler;}; die $@ if $@; ]]> rnew($package)->as_string, $/; } ]]> #include ]]> Now compile: さあ、コンパイルしましょう: Here's an example script file: スクリプトファイルの例です。 Now run: これを実行してみましょう: 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_origalen に 1 を代入することで無効にできます。 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_level は 0 に設定されています; これはプログラムが生涯ただ一つのインタプリタを作っただけの ときには、普通は余分な後始末が不要であるからです。 Setting PL_perl_destruct_level to 1 makes everything squeaky clean: 全てを始末させるためには PL_perl_destruct_level を 1 に設定します。 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_level が 1 に 設定され、これによって徹底的なクリーニングは自動的で、インタプリタ変数は 正しく初期化されます。 同時に複数のインタプリタを実行するつもりがない場合でも、上述の例のように 順番に実行させるつもりなら、-Dusemultiplicity オプションをつけて perl をビルドすることを推奨します; さもなければ連続した実行の間に インタプリタ変数が正しく初期化されずに、アプリケーションが クラッシュするかもしれません。 See also perlxs/Thread-aware system interfaces. perlxs/Thread-aware system interfaces も参照してください。 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 ]]> 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() の呼び出しに注意してください。 実行されている個々のプロセスやスレッドで、どのインタプリタが 「カレント」なのかを追跡するグローバルな状態を初期化するために必要です。 the particular process or thread that may be running it. もし複数のインタプリタがあって、両方のインタプリタに交互に 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: いつもと同じようにコンパイルします: Run it, Run it: 実行、実行: (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() しているスクリプトを埋め込もうとしているのであれば、こうなる 可能性があります。 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 を使っていました。 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 の 一部を見てみましょう。 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() の第二引数に 置けます: Then compile: そしてコンパイルします: ExtUtils::Embed can also automate writing the xs_init glue code. ExtUtils::Embed も xs_init 糊コードを書くことを 自動化できます。 Consult perlxs, perlguts, and perlapi for more details. 詳しくは perlxs, perlguts, perlapi を参照してください。 (Win32 での Perl の組み込み) In general, all of the source code shown here should work unmodified under Windows. 一般的に、ここで示した全てのコードは Windows でも無変更で動作するはずです。 However, there are some caveats about the command-line examples shown. For starters, backticks won't work under the Win32 native command shell. The ExtUtils::Embed kit on CPAN ships with a script called genmake, which generates a simple makefile to build a program from a single C source file. It can be used like this: しかし、コマンドラインの例についてはいくつかの問題があります。 まず、バッククォートは、Win32 ネイティブのコマンドシェルでは働きません。 CPAN にある ExtUtils::Embed キットには、genmake という単一の C の ソースファイルからプログラムをビルドするための単純な makefile を生成する スクリプトが一緒にあります。 これは以下のように使います: perl genmake interp.c C:\ExtUtils-Embed\eg> nmake C:\ExtUtils-Embed\eg> interp -e "print qq{I'm embedded in Win32!\n}" ]]> You may wish to use a more robust environment such as the Microsoft Developer Studio. In this case, run this to generate perlxsi.c: あなたは Micorsoft Developer Studio のようなより堅牢な環境を使いたいと 思うかもしれません。 その場合、perlxsi.c を生成するために以下のようにします。 Create a new project and Insert -> Files into Project: perlxsi.c, perl.lib, and your own source files, e.g. interp.c. Typically you'll find perl.lib in C:\perl\lib\CORE, if not, you should see the CORE directory relative to perl -V:archlib. The studio will also need this path so it knows where to find Perl include files. This path can be added via the Tools -> Options -> Directories menu. Finally, select Build -> Build interp.exe and you're ready to go. 新たなプロジェクトを作成してからプロジェクトに perlxsi.c、perl.lib と 自分のソースファイル、例えば interp.c を登録します。 典型的には perl.lib は C:\perl\lib\CORE があるでしょう。 ここになければ、CORE ディレクトリを見つけ出すために perl -V:archlib を使いましょう。 studio は Perl のインクルードファイルがどこにあるのかを知る 必要もあります。 このパスは Tools→Options→Directories とメニューを たどることで追加することができます。 最後に Build→Build interp.exe を選択して、これで準備は完了です。 (Perl_ を隠す) If you completely hide the short forms 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 を追加してください。 これは、例えば以下のように書く代わりに: you will have to write the explicit full form 以下のように明示的に完全な形式で書く必要があります: (See {tag:link xref='perlguts/Background and PERL_IMPLICIT_CONTEXT for the explanation of the aTHX_.'}perlguts/Background and PERL_IMPLICIT_CONTEXT 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_ の説明については perlguts/Background and PERL_IMPLICIT_CONTEXT を参照してください。) 短い形式を隠すことは、その他のソフトウェアパッケージとのあらゆる種類の 不快なもの(C プリプロセッサやその他のもの)との衝突を避けるためにとても 便利です。 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. Permission is granted to make and distribute verbatim copies of this documentation provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this documentation under the conditions for verbatim copying, provided also that they are marked clearly as modified versions, that the authors' names and title are unchanged (though subtitles and additional authors' names may be added), and that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this documentation into another language, under the above conditions for modified versions. Created: KIMURA Koichi (5.005) Updated: Kentaro Shirakata <argrath@ub32.org> (5.10.0-)