. We knew exactly what code would be run, and assumed we could avoid variable collisions and outrageous symbol table growth. =end original しかしながら永続的なインタプリタを使うときには、名前空間や変数のスコープをより注意深く扱わねばならないでしょう。先の例では、私たちはデフォルトパッケージ C

でグローバル変数を使いました。私たちは実際にあのコードが実行できることを知りましたが、変数の衝突やシンボルテーブル拡大の限界に当たらないことを仮定していました。 =begin original 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. =end original あなたのアプリケーションが、時折幾つかの任意のファイルから Perl コードが実行されるサーバーであるとしましょう。あなたのサーバーは実行させたコードを知る術がありません。非常に危険です。 =begin original If the file is pulled in by C, compiled into a newly constructed interpreter, and subsequently cleaned out with C afterwards, you're shielded from most namespace troubles. =end original ファイルが C を使って引き込まれた場合、新しく構築されたインタプリタへコンパイルされ、後の C で始末されます; これによってほとんどの名前空間にまつわるトラブルから守られます。 =begin original 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 L. 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 L, We'll call the subroutine C which lives in the file C and pass the filename and boolean cleanup/cache flag as arguments. =end original このシナリオにおいて名前空間の衝突を防ぐ一つの方法は、ファイル名をユニークであることが保証されているパッケージ名に変換し、それから L を使ったコードにコンパイルするのです。先の例では、各ファイルは一回だけコンパイルされました。あるいは、アプリケーションはファイルに結び付けられたシンボルテーブルをそれが必要なくなった時点で掃除してしまうことを選択するかもしれません。 L を使うことで、私たちは C というファイルにあるサブルーチン C を呼び出し、それにファイル名と cleanup/cache を表わすブール値を引数として渡します。 =begin original Note that the process will continue to grow for each file that it uses. In addition, there might be Ced 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 L whenever possible. =end original プロセスはそれぞれのファイルを使うごとに大きくなるということに注意してください。それに加えて、C されたサブルーチンなどの条件によっても、 Perl のシンボルテーブルは大きくなります。あなたはプロセスの大きさを記録しつづける何等かのロジックを欲するかもしれませんし、あるいはメモリの消費量を最少にするために特定回数のリクエストの後で自分自身を再スタートするようにしたいかもしれません。また、可能であるときにはいつでも L を使ってあなたの使う変数を見通したいでしょう。 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 = ; 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 #include /* 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" }; char *args[] = { "", DO_CLEAN, NULL }; char filename[BUFFER_SIZE]; int exitstatus = 0; PERL_SYS_INIT3(&argc,&argv,&env); if((my_perl = perl_alloc()) == NULL) { fprintf(stderr, "no memory!"); exit(1); } perl_construct(my_perl); PL_origalen = 1; /* don't let $0 assignment update the proctitle or embedding[0] */ exitstatus = perl_parse(my_perl, NULL, 2, embedding, NULL); PL_exit_flags |= PERL_EXIT_DESTRUCT_END; if(!exitstatus) { exitstatus = perl_run(my_perl); 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; perl_destruct(my_perl); perl_free(my_perl); PERL_SYS_TERM(); exit(exitstatus); } =begin original Now compile: =end original さあ、コンパイルしましょう: % cc -o persistent persistent.c \ `perl -MExtUtils::Embed -e ccopts -e ldopts` =begin original Here's an example script file: =end original スクリプトファイルの例です。 #test.pl my $string = "hello"; foo($string); sub foo { print "foo says: @_\n"; } =begin original Now run: =end original これを実行してみましょう: % 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 =head2 Execution of END blocks (END ブロックの実行) =begin original 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 C to get the new behaviour. This also enables the running of END blocks if the perl_parse fails and C will return the exit value. =end original 伝統的に END ブロックは perl_run の最後に実行されてきました。これは、perl_run を呼び出さないアプリケーションで問題となります。 perl 5.7.2 から、新しい振る舞いを取らせるために C を指定できます。これはまた、もし perl_parse が失敗して C が終了値を返したときにも END ブロックを実行するようにします。 =head2 $0 assignments ($0 への代入) =begin original 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 C<1> to the variable C before perl_parse() is called. =end original perl スクリプトが $0 に値を代入すると、perl のランタイムは、perl_parse() に渡された argv が指すメモリを更新して、利用可能なら setproctitle() のような API 関数も呼び出すことによって、その値を "ps" で報告されるプログラム名として表示させようとします。この振る舞いは組み込み perl では不適切かもしれないので、perl_parse() が呼び出される前に C に C<1> を代入することで無効にできます。 =begin original The F example above is for instance likely to segfault when $0 is assigned to if the C assignment is removed. This because perl will try to write to the read only memory of the C strings. =end original 例えば、上述の F の例は、もし C 代入を取り除くと、$0 が代入されたときにおそらくセグメンテーションフォルトが起きるでしょう。これは C 文字列の読み込み専用メモリに書き込もうとするからです。 =head2 Maintaining multiple interpreter instances (複数のインタプリタのインスタンスを保持する) =begin original 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. =end original ごく一部のアプリケーションでは、二つ以上のインタプリタを生成する必要があるかもしれません。そのようなアプリケーションはインタプリタに結び付けられたリソースを解放することを決定することがあるかもしれません。 =begin original The program must take care to ensure that this takes place I the next interpreter is constructed. By default, when perl is not built with any special options, the global variable C is set to C<0>, since extra cleaning isn't usually needed when a program only ever creates a single interpreter in its entire lifetime. =end original プログラムは次のインタプリタが構築されるよりB<前に>、解放が発生することに注意を払い、それを保証しなければなりません。デフォルトでは、perl が特殊なオプション付きでビルドされていなければ、グローバル変数 C は C<0> に設定されています; これはプログラムが生涯ただ一つのインタプリタを作っただけのときには、普通は余分な後始末が不要であるからです。 =begin original Setting C to C<1> makes everything squeaky clean: =end original 全てを始末させるためには C を C<1> に設定します。 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! */ } =begin original When I is called, the interpreter's syntax parse tree and symbol tables are cleaned up, and global variables are reset. The second assignment to C is needed because perl_construct resets it to C<0>. =end original I が呼ばれたとき、インタプリタの構文解析木とシンボルテーブルは始末され、そしてグローバル変数がリセットされます。 C への第 2 引数は、perl_construct を C<0> にリセットするために必要です。 =begin original 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 C<-Dusemultiplicity> or the options C<-Dusethreads -Duseithreads> when building perl. By default, enabling one of these Configure options sets the per-interpreter global variable C to C<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 C<-Dusemultiplicity> option otherwise some interpreter variables may not be initialized correctly between consecutive runs and your application may crash. =end original 現在、二つ以上のインタプリタのインスタンスを同時に実行することがサポートされています。これは可能なことですが、Perlビルドしたときに Configure オプション C<-Dusemultiplicity> か C<-Dusethreads -Duseithreads> を使ったときのみです。デフォルトでは、これらの Configure オプションの一つが有効になるとインタプリタ単位のグローバル変数 C が C<1> に設定され、これによって徹底的なクリーニングは自動的で、インタプリタ変数は正しく初期化されます。同時に複数のインタプリタを実行するつもりがない場合でも、上述の例のように順番に実行させるつもりなら、C<-Dusemultiplicity> オプションをつけて perl をビルドすることを推奨します; さもなければ連続した実行の間にインタプリタ変数が正しく初期化されずに、アプリケーションがクラッシュするかもしれません。 =begin original See also L. =end original L も参照してください。 =begin original Using C<-Dusethreads -Duseithreads> rather than C<-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. =end original もし、異なるスレッドで同時に複数のインタプリタを実行するつもりなら、 C<-Dusemultiplicity> ではなく C<-Dusethreads -Duseithreads> がより適切です; なぜならこれはインタプリタにシステムのスレッドライブラリをリンクすることへの対応を有効にするからです。 =begin original Let's give it a try: =end original 試してみましょう: #include #include /* 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 }; char *two_args[] = { "two_perl", SAY_HELLO }; 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(); } =begin original 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. =end original PERL_SET_CONTEXT() の呼び出しに注意してください。実行されている個々のプロセスやスレッドで、どのインタプリタが「カレント」なのかを追跡するグローバルな状態を初期化するために必要です。もし複数のインタプリタがあって、両方のインタプリタに交互に perl API 呼び出しを行うなら、常にこれを行うべきです。 =begin original PERL_SET_CONTEXT(interp) should also be called whenever C is used by a thread that did not create it (using either perl_alloc(), or the more esoteric perl_clone()). =end original (perl_alloc() か、より難解な perl_clone() を使って、) C を作ったのではないスレッドによって使われるときはいつでも、 PERL_SET_CONTEXT(interp) も呼び出されるべきです。 =begin original Compile as usual: =end original いつもと同じようにコンパイルします: % cc -o multiplicity multiplicity.c \ `perl -MExtUtils::Embed -e ccopts -e ldopts` =begin original Run it, Run it: =end original 実行、実行: % multiplicity Hi, I'm one_perl Hi, I'm two_perl =head2 Using Perl modules, which themselves use C libraries, from your C program (C プログラムから、C のライブラリを使っている Perl モジュールを使う) =begin original If you've played with the examples above and tried to embed a script that Is a Perl module (such as I) which itself uses a C or C++ library, this probably happened: =end original あなたがこれまでにでてきた例を使っていて、(I のような)それ自身が C や C++ のライブラリを使っている Perl モジュールを I しているスクリプトを埋め込もうとしているのであれば、こうなる可能性があります。 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.) =begin original What's wrong? =end original なにがまずいのでしょう? =begin original 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 I, handing it NULL for the second argument: =end original あなたの使うインタプリタはこういったエクステンションとどのように交信するのかを知りません。ちょっとした糊(glue)が助けになります。これまでは、I を呼び出すときにはその第二引数として NULL を使っていました: perl_parse(my_perl, NULL, argc, my_argv, NULL); =begin original 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 I to see how Perl does this: =end original ここは Perl と、リンクされた C/C++ ルーチンとの間の初期化時の交信を生成するために挿入することのできる糊コード(glue code)の場所です。 Perl がどのようにこれを行っているのかを知るために、I の一部を見てみましょう。 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); } =begin original 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 I and is invoked when you say I. In turn, this hooks into an XSUB, I, which creates a Perl counterpart for each of the extension's XSUBs. Don't worry about this part; leave that to the I and extension authors. If your extension is dynamically loaded, DynaLoader creates I 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. =end original あなたの使う Perl の実行ファイルにリンクされているエクステンション毎に、そのエクステンションのルーチンを組み込むための Perl サブルーチンが生成されます。通常はこういったサブルーチンは I という名称で、あなたが I としたときに起動されます。次にこれは、各エクステンションの XSUB に対する Perl の counterpart として生成されるXSUB I にフックされます。この部分に関して心配することはありません; I と、エクステンションの作者に任せましょう。あなたの使うエクステンションが動的ロードを必要とするならば、 DynaLoader はあなたのためにその場で I を生成します。実際のところ、あなたが DynaLoader を使っているのであれば、他のエクステンションを静的にリンクする必要性はほとんどないでしょう。 =begin original Once you have this code, slap it into the second argument of I: =end original このコードを一度書いてしまえば、それを I の第二引数に置けます: perl_parse(my_perl, xs_init, argc, my_argv, NULL); =begin original Then compile: =end original そしてコンパイルします: % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts` % interp use Socket; use SomeDynamicallyLoadedModule; print "Now I can use extensions!\n"' =begin original B can also automate writing the I glue code. =end original B も I 糊コードを書くことを自動化できます。 % 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` =begin original Consult L, L, and L for more details. =end original 詳しくは L, L, L を参照してください。 =head2 Using embedded Perl with POSIX locales =begin original (See L 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 S> within the perl code, this mostly has no effect (but see L). 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 C is set (even if set to 0 or C<"">). A Perl that has this capability will define the C pre-processor symbol C. This allows code that has to work with multiple Perl versions to do some sort of work-around when confronted with an earlier Perl. =end original (これらに関する情報については L を参照してください。) Perl インタプリタが普通に開始したとき、システムのデフォルトのロケールを使うということをシステムに伝えます。これはたいてい "C" または "POSIX" ロケールですが、そうである必要はありません。 perl のコードに S> がなければ、これはほとんど何の影響もありません (しかし L を参照してください)。また、組み込み Perl で使いたいロケールがシステムのデフォルトと同じ場合は問題になりません。しかし、システムのデフォルトではないロケールを設定して使いたい場合は動作しません。 Perl v5.20 から、ロケールは既に適切に設定されているので、通常の初期化を飛ばすように組み込み Perl インタプリタに伝えられます。環境変数 C が設定されていれば (たとえ 0 または C<""> に設定されていても) 飛ばされます。この機能のある Perl は C プリプロセッサシンボル C が設定されています。これにより、古い Perl に直面したときに、複数の Perl バージョンに対して何らかの回避策をとれるようになります。 =head1 Hiding Perl_ (Perl_ を隠す) =begin original 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 =end original もし Perl public API の短い形式を完全に隠したいなら、コンパイルオプションに -DPERL_NO_SHORT_NAMES を追加してください。これは、例えば以下のように書く代わりに: warn("%d bottles of beer on the wall", bottlecount); =begin original you will have to write the explicit full form =end original 以下のように明示的に完全な形式で書く必要があります: Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount); =begin original (See L for the explanation of the C. ) 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.) =end original (C の説明については L を参照してください。) 短い形式を隠すことは、その他のソフトウェアパッケージとのあらゆる種類の不快なもの(C プリプロセッサやその他のもの)との衝突を避けるためにとても便利です。 =head1 MORAL =begin original You can sometimes I in C, but you can always I in Perl. Because you can use each from the other, combine them as you wish. =end original あなたは時々 C で B<より速いコードを> 書くことができるかもしれませんが、あなた常に Perl で B<コードをより早く> 書くことができるのです。これは片方でもう片方のものを作ることができ、望むままに組み合わせることができるからです。 =head1 AUTHOR =begin original Jon Orwant > and Doug MacEachern >, with small contributions from Tim Bunce, Tom Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya Zakharevich. =end original Jon Orwant > と Doug MacEachern >; さらに Tim Bunce, Tom Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, Ilya Zakharevich からの小さな貢献によります。 =begin original 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. =end original 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 プラグインに使っています。 =head1 COPYRIGHT 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. =begin meta Translate: KIMURA Koichi (5.005) Update: SHIRAKATA Kentaro (5.10.0-) Status: completed =end meta