perlembed.pod

=encoding euc-jp

=head1 NAME

=begin original

perlembed - how to embed perl in your C program

=end original

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

=head1 DESCRIPTION

=head2 PREAMBLE

=begin original

Do you want to:

=end original

あなたのやりたいことは

=over 5

=item B<Use C from Perl?>

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

=begin original

Read L<perlxstut>, L<perlxs>, L<h2xs>, L<perlguts>, and L<perlapi>.

=end original

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

=item B<Use a Unix program from Perl?>

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

=begin original

Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.

=end original

バッククォートに関することと、
L<perlfunc>にあるC<system>、C<exec>に関することを読みましょう。

=item B<Use Perl from Perl?>

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

=begin original

Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require>
and L<perlfunc/use>.

=end original

L<perlfunc/do>、 L<perlfunc/eval>、L<perlfunc/require>、
L<perlfunc/use>を読みましょう。

=item B<Use C from C?>

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

=begin original

Rethink your design.

=end original

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

=item B<Use Perl from C?>

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

=begin original

Read on...

=end original

読み続けてください…

=back

=head2 ROADMAP

(ロードマップ)

=over 5

=item *

=begin original

Compiling your C program

=end original

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

=item *

=begin original

Adding a Perl interpreter to your C program

=end original

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

=item *

=begin original

Calling a Perl subroutine from your C program

=end original

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

=item *

=begin original

Evaluating a Perl statement from your C program

=end original

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

=item *

=begin original

Performing Perl pattern matches and substitutions from your C program

=end original

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

=item *

=begin original

Fiddling with the Perl stack from your C program

=end original

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

=item *

=begin original

Maintaining a persistent interpreter

=end original

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

=item *

=begin original

Maintaining multiple interpreter instances

=end original

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

=item *

=begin original

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

=end original

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

=item *

=begin original

Embedding Perl under Win32

=end original

Win32 における組み込み Perl

=back

=head2 Compiling your C program

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

=begin original

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.)

=end original

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

=begin original

Also, every C program that uses Perl must link in the I<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 (I</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
I<lib> directory.)

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

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

=begin original

or perhaps just

=end original

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

    /usr/local/lib/perl5/CORE

=begin original

or maybe something like

=end original

こうかもしれません

    /usr/opt/perl5/CORE

=begin original

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

=end original

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

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

=begin original

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

=end original

次のセクション L</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

=begin original

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

=end original

(これは実際には一行です。)
私の使う 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

=begin original

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

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

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

=begin original

If the B<ExtUtils::Embed> module isn't part of your Perl distribution,
you can retrieve it from
L<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.)

=end original

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

=begin original

The B<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.

=end original

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

=head2 Adding a Perl interpreter to your C program

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

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

=begin original

or

=end original

または

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

=begin original

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

=end original

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

=head2 Calling a Perl subroutine from your C program

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

=begin original

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

=end original

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

=begin original

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

=end original

以下に示すのは、I<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);
    }

=begin original

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

=end original

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

=begin original

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

=end original

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

 print "I shan't be printed.";

 sub showtime {
     print time;
 }

=begin original

Simple enough. Now compile and run:

=end original

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

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

=begin original

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.

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=head2 Evaluating a Perl statement from your C program

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

=begin original

Perl provides two API functions to evaluate pieces of Perl code.
These are L<perlapi/eval_sv> and L<perlapi/eval_pv>.

=end original

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

=begin original

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
L<perlfunc/use>, L<perlfunc/require>, and L<perlfunc/do> to
include external Perl files.

=end original

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

=begin original

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

=end original

I<eval_pv> は独立した Perl の文字列を評価し、強制的に C の型へと
変数を展開します。
以下に示すプログラムは I<string.c> は、三つの
Perl 文字列を実行し、最初のものを C<int >に、二番目のものを C<float> に、
三番目のものを C<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();
 }

=begin original

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

=end original

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

=begin original

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

=end original

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

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

=begin original

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 I<eval_pv()> instead.  Example:

=end original

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

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

=begin original

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

=end original

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

=head2 Performing Perl pattern matches and substitutions from your C program

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

=begin original

The I<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: I<match()>, I<substitute()>, and I<matches()>.

=end original

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

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

=begin original

Given a string and a pattern (e.g., C<m/clasp/> or C</\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.

=end original

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

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

=begin original

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

=end original

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

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

=begin original

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

=end original

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

=begin original

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

=end original

以下に示すのはサンプルプログラム I<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();
 }

=begin original

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

=end original

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

  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.

=head2 Fiddling with the Perl stack from your C program

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

=begin original

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.

=end original

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

=begin original

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 L<perlguts> and L<perlapi>.

=end original

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

=begin original

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

=end original

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

=begin original

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

=end original

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

=begin original

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 I<pow()> function).  First
I'll create a stub exponentiation function in I<power.pl>:

=end original

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

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

=begin original

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

=end original

今度は I<expo()> への二つの引数をプッシュするのとそこからの戻り値
をポップするに必要なすべての perlguts を含んでいる I<PerlPower()> と
いう関数を持った C プログラム I<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);
 }

=begin original

Compile and run:

=end original

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

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

    % power
    3 to the 4th power is 81.

=head2 Maintaining a persistent interpreter

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

=begin original

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.

=end original

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

=begin original

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 C<main>.  We
knew exactly what code would be run, and assumed we could avoid
variable collisions and outrageous symbol table growth.

=end original

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

=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<perl_parse()>, compiled into a newly
constructed interpreter, and subsequently cleaned out with
C<perl_destruct()> afterwards, you're shielded from most namespace
troubles.

=end original

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

=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<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 L<perlapi/call_argv>, We'll
call the subroutine C<Embed::Persistent::eval_file> which lives in the
file C<persistent.pl> and pass the filename and boolean cleanup/cache
flag as arguments.

=end original

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

=begin original

Note that the process will continue to grow for each file that it
uses.  In addition, there might be C<AUTOLOAD>ed 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<perlfunc/my> whenever possible.

=end original

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

 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);
 }

=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<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 C<perl_destruct> will return the exit value.

=end original

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

=end original

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

=begin original

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

=end original

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

=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<before>
the next interpreter is constructed.  By default, when perl is not
built with any special options, the global variable
C<PL_perl_destruct_level> 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<PL_perl_destruct_level> は C<0> に設定されています;
これはプログラムが生涯ただ一つのインタプリタを作っただけの
ときには、普通は余分な後始末が不要であるからです。

=begin original

Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean:

=end original

全てを始末させるためには C<PL_perl_destruct_level> を 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<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 C<PL_perl_destruct_level> is needed because
perl_construct resets it to C<0>.

=end original

I<perl_destruct()> が呼ばれたとき、インタプリタの構文解析木と
シンボルテーブルは始末され、そしてグローバル変数がリセットされます。
C<PL_perl_destruct_level> への第 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<PL_perl_destruct_level> 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<PL_perl_destruct_level> が C<1> に
設定され、これによって徹底的なクリーニングは自動的で、インタプリタ変数は
正しく初期化されます。
同時に複数のインタプリタを実行するつもりがない場合でも、上述の例のように
順番に実行させるつもりなら、C<-Dusemultiplicity> オプションをつけて
perl をビルドすることを推奨します; さもなければ連続した実行の間に
インタプリタ変数が正しく初期化されずに、アプリケーションが
クラッシュするかもしれません。

=begin original

See also L<perlxs/Thread-aware system interfaces>.

=end original

L<perlxs/Thread-aware system interfaces> も参照してください。

=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 <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);
 }

=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<interp> 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<interp> を
作ったのではないスレッドによって使われるときはいつでも、
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 I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++
library, this probably happened:

=end original

あなたがこれまでにでてきた例を使っていて、(I<Socket> のような)そ
れ自身が C や C++ のライブラリを使っている Perl モジュールを
I<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.)

=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<perl_parse()>, handing it NULL for the second argument:

=end original

あなたの使うインタプリタはこういったエクステンションと
どのように交信するのかを知りません。
ちょっとした糊(glue)が助けになります。
これまでは、I<perl_parse()> を呼び出すときにはその第二引数として
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<perlmain.c> to see how Perl does this:

=end original

ここは Perl と、リンクされた C/C++ ルーチンとの間の初期化時の交信を
生成するために挿入することのできる糊コード(glue code)の場所です。
Perl がどのようにこれを行っているのかを知るために、I<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);
 }

=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<Module::bootstrap()> and is invoked when you say I<use Module>.  In
turn, this hooks into an XSUB, I<boot_Module>, which creates a Perl
counterpart for each of the extension's XSUBs.  Don't worry about this
part; leave that to the I<xsubpp> and extension authors.  If your
extension is dynamically loaded, DynaLoader creates I<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.

=end original

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

=begin original

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

=end original

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

 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<ExtUtils::Embed> can also automate writing the I<xs_init> glue code.

=end original

B<ExtUtils::Embed> も I<xs_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`

=begin original

Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details.

=end original

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

=head2 Using embedded Perl with POSIX locales

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

=begin original

(See L<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 S<C<"use locale">> within the perl
code, this mostly has no effect (but see L<perllocale/Not within the
scope of "use locale">).  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<PERL_SKIP_LOCALE_INIT> is set (even
if set to 0 or C<"">).  A perl that has this capability will define the
C pre-processor symbol C<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.

=end original

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

=begin original

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.

=end original

あなたのプログラムが POSIX 2008 マルチスレッドロケール機能を使っている場合、
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<perlguts/"Background and PERL_IMPLICIT_CONTEXT"> for the explanation
of the C<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.)

=end original

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

=head1 MORAL

=begin original

You can sometimes I<write faster code> in C, but
you can always I<write code faster> 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 <F<orwant@media.mit.edu>> and Doug MacEachern
<F<dougm@covalent.net>>, with small contributions from Tim Bunce, Tom
Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
Zakharevich.

=end original

Jon Orwant <F<orwant@media.mit.edu>> と Doug MacEachern
<F<dougm@covalent.net>>; さらに 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 ( L<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 ( L<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 <argrath@ub32.org> (5.10.0-)
Status: completed

=end meta