1 |
|
2 |
=encoding euc-jp |
3 |
|
4 |
=head1 NAME |
5 |
|
6 |
=begin original |
7 |
|
8 |
perlguts - Introduction to the Perl API |
9 |
|
10 |
=end original |
11 |
|
12 |
perlguts - Perl API の紹介 |
13 |
|
14 |
=head1 DESCRIPTION |
15 |
|
16 |
=begin original |
17 |
|
18 |
This document attempts to describe how to use the Perl API, as well as |
19 |
to provide some info on the basic workings of the Perl core. It is far |
20 |
from complete and probably contains many errors. Please refer any |
21 |
questions or comments to the author below. |
22 |
|
23 |
=end original |
24 |
|
25 |
このドキュメントでは Perl API の使い方、および Perl コアの基本的な動作に |
26 |
関するいくばくかの情報を提供しようとしています。 |
27 |
完璧からは程遠いものですし、間違いも多いと思います。 |
28 |
疑問点やコメントは後述する著者に対して行なってください。 |
29 |
|
30 |
=head1 Variables |
31 |
|
32 |
(変数) |
33 |
|
34 |
=head2 Datatypes |
35 |
|
36 |
(データ型) |
37 |
|
38 |
=begin original |
39 |
|
40 |
Perl has three typedefs that handle Perl's three main data types: |
41 |
|
42 |
=end original |
43 |
|
44 |
Perl では、主となる三つのデータ型を扱うために三つの型定義を行なっています: |
45 |
|
46 |
SV Scalar Value |
47 |
AV Array Value |
48 |
HV Hash Value |
49 |
|
50 |
=begin original |
51 |
|
52 |
Each typedef has specific routines that manipulate the various data types. |
53 |
|
54 |
=end original |
55 |
|
56 |
それぞれの typedef には様々なデータ型を操作するための特別なルーチンが |
57 |
用意されています。 |
58 |
|
59 |
=head2 What is an "IV"? |
60 |
|
61 |
("IV" ってなに?) |
62 |
|
63 |
=begin original |
64 |
|
65 |
Perl uses a special typedef IV which is a simple signed integer type that is |
66 |
guaranteed to be large enough to hold a pointer (as well as an integer). |
67 |
Additionally, there is the UV, which is simply an unsigned IV. |
68 |
|
69 |
=end original |
70 |
|
71 |
Perl では、符号付き整数でもポインタでも十分に入れることのできる特別な |
72 |
typedef である IV を使います。 |
73 |
更に、単に符号なしの IV である UV もあります。 |
74 |
|
75 |
=begin original |
76 |
|
77 |
Perl also uses two special typedefs, I32 and I16, which will always be at |
78 |
least 32-bits and 16-bits long, respectively. (Again, there are U32 and U16, |
79 |
as well.) They will usually be exactly 32 and 16 bits long, but on Crays |
80 |
they will both be 64 bits. |
81 |
|
82 |
=end original |
83 |
|
84 |
Perl はまた、二つの特殊な typedef である I32 と I16 を使っています; |
85 |
これらはそれぞれ、常に最低 32bit、16bit の長さを持っているものです。 |
86 |
(再び、同様に U32 と U16 もあります。) |
87 |
これらは普通は正確に 32 ビットと 16 ビットですが、Cray では両方とも |
88 |
64 ビットです。 |
89 |
|
90 |
=head2 Working with SVs |
91 |
|
92 |
(SV に対する作業) |
93 |
|
94 |
=begin original |
95 |
|
96 |
An SV can be created and loaded with one command. There are five types of |
97 |
values that can be loaded: an integer value (IV), an unsigned integer |
98 |
value (UV), a double (NV), a string (PV), and another scalar (SV). |
99 |
("PV" stands for "Pointer Value". You might think that it is misnamed |
100 |
because it is described as pointing only to strings. However, it is |
101 |
possible to have it point to other things For example, it could point |
102 |
to an array of UVs. But, |
103 |
using it for non-strings requires care, as the underlying assumption of |
104 |
much of the internals is that PVs are just for strings. Often, for |
105 |
example, a trailing C<NUL> is tacked on automatically. The non-string use |
106 |
is documented only in this paragraph.) |
107 |
|
108 |
=end original |
109 |
|
110 |
SV は、1 つのコマンドで生成し、値をロードすることができます。 |
111 |
ロードできる値の型には、整数 (IV)、符号なし整数 (UV)、 |
112 |
倍精度 (NV)、文字列 (PV)、その他のスカラ (SV) があります。 |
113 |
("PV" は "Pointer Value" の意味です。 |
114 |
文字列だけを指すように表現しているので誤った名称であると考えるかもしれません。 |
115 |
しかし、他のものを指すことも可能です。 |
116 |
例えば、UV の配列を指すこともできます。 |
117 |
しかし、非文字列の使用は注意が必要です; 内部の多くの基となる仮定は、 |
118 |
PV は単に文字列であるというものだからです。 |
119 |
しばしば、例えば、末尾の C<NUL> は自動的に連結されます。 |
120 |
非文字列の使用はこの段落でのみ文書化されています。) |
121 |
|
122 |
=begin original |
123 |
|
124 |
The seven routines are: |
125 |
|
126 |
=end original |
127 |
|
128 |
これらを行なう、7 つのルーチンは: |
129 |
|
130 |
SV* newSViv(IV); |
131 |
SV* newSVuv(UV); |
132 |
SV* newSVnv(double); |
133 |
SV* newSVpv(const char*, STRLEN); |
134 |
SV* newSVpvn(const char*, STRLEN); |
135 |
SV* newSVpvf(const char*, ...); |
136 |
SV* newSVsv(SV*); |
137 |
|
138 |
=begin original |
139 |
|
140 |
C<STRLEN> is an integer type (Size_t, usually defined as size_t in |
141 |
F<config.h>) guaranteed to be large enough to represent the size of |
142 |
any string that perl can handle. |
143 |
|
144 |
=end original |
145 |
|
146 |
C<STRLEN> は perl が扱えるどんな文字列のサイズも表現するのに十分なだけの |
147 |
大きさを持つことが保証されている整数型(Size_t, 普通は F<config.h> で |
148 |
size_t として定義されています)。 |
149 |
|
150 |
=begin original |
151 |
|
152 |
In the unlikely case of a SV requiring more complex initialization, you |
153 |
can create an empty SV with newSV(len). If C<len> is 0 an empty SV of |
154 |
type NULL is returned, else an SV of type PV is returned with len + 1 (for |
155 |
the C<NUL>) bytes of storage allocated, accessible via SvPVX. In both cases |
156 |
the SV has the undef value. |
157 |
|
158 |
=end original |
159 |
|
160 |
あまりなさそうですが、SV がもっと複雑な初期化を必要とする場合、 |
161 |
newSV(len) で空の SV も作成できます。 |
162 |
もし C<len> が 0 なら、NULL 型の空の SV が返され、さもなければ |
163 |
PV 型の SV は、SvPVX でアクセスできる len + 1 (C<NUL> のため) バイトの領域を |
164 |
割り当てられて返されます。 |
165 |
両方の場合で、SV の値は未定義値です。 |
166 |
|
167 |
SV *sv = newSV(0); /* no storage allocated */ |
168 |
SV *sv = newSV(10); /* 10 (+1) bytes of uninitialised storage |
169 |
* allocated */ |
170 |
|
171 |
=begin original |
172 |
|
173 |
To change the value of an I<already-existing> SV, there are eight routines: |
174 |
|
175 |
=end original |
176 |
|
177 |
I<既に存在する> スカラの値を変更するために 8 つのルーチンがあります: |
178 |
|
179 |
void sv_setiv(SV*, IV); |
180 |
void sv_setuv(SV*, UV); |
181 |
void sv_setnv(SV*, double); |
182 |
void sv_setpv(SV*, const char*); |
183 |
void sv_setpvn(SV*, const char*, STRLEN) |
184 |
void sv_setpvf(SV*, const char*, ...); |
185 |
void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *, |
186 |
SV **, I32, bool *); |
187 |
void sv_setsv(SV*, SV*); |
188 |
|
189 |
=begin original |
190 |
|
191 |
Notice that you can choose to specify the length of the string to be |
192 |
assigned by using C<sv_setpvn>, C<newSVpvn>, or C<newSVpv>, or you may |
193 |
allow Perl to calculate the length by using C<sv_setpv> or by specifying |
194 |
0 as the second argument to C<newSVpv>. Be warned, though, that Perl will |
195 |
determine the string's length by using C<strlen>, which depends on the |
196 |
string terminating with a C<NUL> character, and not otherwise containing |
197 |
NULs. |
198 |
|
199 |
=end original |
200 |
|
201 |
代入すべき文字列の長さを C<sv_setpvn> や C<newSVpv>、あるいは |
202 |
C<newSVpv> を使って指定することもできますし、C<sv_setpv> を使ったり |
203 |
C<newSVpv> の第二引数に 0 を指定することによって、Perl 自身に |
204 |
文字列の長さを計算させることもできます。 |
205 |
ただし Perl は、C<NUL> 文字で終了していて、それ以外に NUL が |
206 |
含まれていないということに依存している C<strlen> を使って長さを |
207 |
計算しているということに注意してください。 |
208 |
|
209 |
=begin original |
210 |
|
211 |
The arguments of C<sv_setpvf> are processed like C<sprintf>, and the |
212 |
formatted output becomes the value. |
213 |
|
214 |
=end original |
215 |
|
216 |
C<sv_setpvf> の引数は C<sprintf> と同じように処理され、書式化された |
217 |
出力が値となります。 |
218 |
|
219 |
=begin original |
220 |
|
221 |
C<sv_vsetpvfn> is an analogue of C<vsprintf>, but it allows you to specify |
222 |
either a pointer to a variable argument list or the address and length of |
223 |
an array of SVs. The last argument points to a boolean; on return, if that |
224 |
boolean is true, then locale-specific information has been used to format |
225 |
the string, and the string's contents are therefore untrustworthy (see |
226 |
L<perlsec>). This pointer may be NULL if that information is not |
227 |
important. Note that this function requires you to specify the length of |
228 |
the format. |
229 |
|
230 |
=end original |
231 |
|
232 |
C<sv_vsetpvfn> は C<vsprintf> と同じようなものですが、可変引数リストに対する |
233 |
ポインタか SV の配列のアドレスと長さのいずれかを指定することができます。 |
234 |
最後の引数は真偽値を指し示します; 関数から返ってきたときにこれが |
235 |
真であれば、フォーマット文字列としてロケール固有の情報が使われているので |
236 |
その文字列の内容は信頼するできないことを表わしています(L<perlsec> を参照)。 |
237 |
ロケールに関する情報が重要でないのなら、このポインタは NULL であっても |
238 |
かまいません。 |
239 |
この関数はフォーマットの長さを要求していることに注意してください。 |
240 |
|
241 |
=begin original |
242 |
|
243 |
The C<sv_set*()> functions are not generic enough to operate on values |
244 |
that have "magic". See L<Magic Virtual Tables> later in this document. |
245 |
|
246 |
=end original |
247 |
|
248 |
C<sv_set*()> 関数群は "magic" を持っている値に対する |
249 |
操作に対して充分に一般化されたものではありません。 |
250 |
後述する L<Magic Virtual Tables> を参照してください。 |
251 |
|
252 |
=begin original |
253 |
|
254 |
All SVs that contain strings should be terminated with a C<NUL> character. |
255 |
If it is not C<NUL>-terminated there is a risk of |
256 |
core dumps and corruptions from code which passes the string to C |
257 |
functions or system calls which expect a C<NUL>-terminated string. |
258 |
Perl's own functions typically add a trailing C<NUL> for this reason. |
259 |
Nevertheless, you should be very careful when you pass a string stored |
260 |
in an SV to a C function or system call. |
261 |
|
262 |
=end original |
263 |
|
264 |
すべてのSV は、必須と言うわけではありませんが C<NUL> キャラクターで |
265 |
終端されているべきです。 |
266 |
この終端の C<NUL> が無かった場合、コアダンプしたり文字列を |
267 |
(文字列が C<NUL> で終端されていることを期待している) C 関数やシステムコールに |
268 |
渡すコードをおかしくする危険があります。 |
269 |
Perl 自身の典型的な関数は、この理由により終端に C<NUL> を追加します。 |
270 |
そうであったとしても、あなたが SV に格納されている文字列を C の関数や |
271 |
システムコールに渡す時には十二分に気をつけるべきなのです。 |
272 |
|
273 |
=begin original |
274 |
|
275 |
To access the actual value that an SV points to, you can use the macros: |
276 |
|
277 |
=end original |
278 |
|
279 |
SV が指し示す実際の値をアクセスするには、以下のマクロを使えます: |
280 |
|
281 |
SvIV(SV*) |
282 |
SvUV(SV*) |
283 |
SvNV(SV*) |
284 |
SvPV(SV*, STRLEN len) |
285 |
SvPV_nolen(SV*) |
286 |
|
287 |
=begin original |
288 |
|
289 |
which will automatically coerce the actual scalar type into an IV, UV, double, |
290 |
or string. |
291 |
|
292 |
=end original |
293 |
|
294 |
これは実際のスカラの型を自動的に IV や UV や倍精度や文字列にします。 |
295 |
|
296 |
=begin original |
297 |
|
298 |
In the C<SvPV> macro, the length of the string returned is placed into the |
299 |
variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do |
300 |
not care what the length of the data is, use the C<SvPV_nolen> macro. |
301 |
Historically the C<SvPV> macro with the global variable C<PL_na> has been |
302 |
used in this case. But that can be quite inefficient because C<PL_na> must |
303 |
be accessed in thread-local storage in threaded Perl. In any case, remember |
304 |
that Perl allows arbitrary strings of data that may both contain NULs and |
305 |
might not be terminated by a C<NUL>. |
306 |
|
307 |
=end original |
308 |
|
309 |
C<SvPV> マクロでは、返される文字列の長さは、変数 C<len> に格納されます |
310 |
(これはマクロですから、C<&len> と I<しないで> ください)。 |
311 |
もしデータの長さを気にしないのであれば、C<SvPV_nolen> マクロを |
312 |
使ってください。 |
313 |
歴史的に、この場合にはグローバル変数 C<PL_na> に C<SvPV> マクロが |
314 |
使われてきました。 |
315 |
しかしこれは可能ですが効率は良くありません; |
316 |
なぜなら C<PL_na> はスレッド化した Perl ではスレッドローカルな |
317 |
領域にアクセスしなければならないからです。 |
318 |
いずれの場合にも、Perl は NUL を含んでいる文字列と C<NUL> で |
319 |
終端されていないような文字列の両方を扱うことができるということを |
320 |
覚えておいてください。 |
321 |
|
322 |
=begin original |
323 |
|
324 |
Also remember that C doesn't allow you to safely say C<foo(SvPV(s, len), |
325 |
len);>. It might work with your |
326 |
compiler, but it won't work for everyone. |
327 |
Break this sort of statement up into separate assignments: |
328 |
|
329 |
=end original |
330 |
|
331 |
同様に、Cで C<foo(SvPV(s, len), len);> とすることが安全ではないことを |
332 |
忘れないでください。 |
333 |
これはあなたの使うコンパイラによってはうまくいきますが、 |
334 |
いつでもそうだとは限らないのです。 |
335 |
そこで、こういったステートメントは以下のように分割します: |
336 |
|
337 |
SV *s; |
338 |
STRLEN len; |
339 |
char *ptr; |
340 |
ptr = SvPV(s, len); |
341 |
foo(ptr, len); |
342 |
|
343 |
=begin original |
344 |
|
345 |
If you want to know if the scalar value is TRUE, you can use: |
346 |
|
347 |
=end original |
348 |
|
349 |
単にスカラ値が真かどうかを知りたいだけならば、 |
350 |
|
351 |
SvTRUE(SV*) |
352 |
|
353 |
=begin original |
354 |
|
355 |
Although Perl will automatically grow strings for you, if you need to force |
356 |
Perl to allocate more memory for your SV, you can use the macro |
357 |
|
358 |
=end original |
359 |
|
360 |
Perl は、SV にもっとメモリを割り当てて欲しいときには自動的に文字列を |
361 |
大きくしてくれますが、さらにメモリを割り当てさせることが必要であれば |
362 |
|
363 |
SvGROW(SV*, STRLEN newlen) |
364 |
|
365 |
=begin original |
366 |
|
367 |
which will determine if more memory needs to be allocated. If so, it will |
368 |
call the function C<sv_grow>. Note that C<SvGROW> can only increase, not |
369 |
decrease, the allocated memory of an SV and that it does not automatically |
370 |
add space for the trailing C<NUL> byte (perl's own string functions typically do |
371 |
C<SvGROW(sv, len + 1)>). |
372 |
|
373 |
=end original |
374 |
|
375 |
というマクロが使えます。 |
376 |
もし必要なら、このマクロが C<sv_grow>を呼びます。 |
377 |
C<SvGROW> は SV に割り当てたメモリを増やすだけで、減らすことは |
378 |
できないということと、終端の NUL の分のバイトが自動的に加算されない |
379 |
(perl 自身の文字列関数は 大概 C<SvGROW(sv, len + 1)> としています)と |
380 |
いうことに注意してください。 |
381 |
|
382 |
=begin original |
383 |
|
384 |
If you want to write to an existing SV's buffer and set its value to a |
385 |
string, use SvPV_force() or one of its variants to force the SV to be |
386 |
a PV. This will remove any of various types of non-stringness from |
387 |
the SV while preserving the content of the SV in the PV. This can be |
388 |
used, for example, to append data from an API function to a buffer |
389 |
without extra copying: |
390 |
|
391 |
=end original |
392 |
|
393 |
もし既存の SV のバッファに書き込みたくて、その値を文字列に設定したいなら、 |
394 |
SV を PV に強制するために |
395 |
SvPV_force() またはその変種の一つを使ってください。 |
396 |
これは SV から様々な種類の非文字列性を除去する一方、PV の中の SV の |
397 |
内容は保存します。 |
398 |
これは、例えば、追加のコピーなしに API 関数からバッファにデータを |
399 |
追加するのに使えます: |
400 |
|
401 |
(void)SvPVbyte_force(sv, len); |
402 |
s = SvGROW(sv, len + needlen + 1); |
403 |
/* something that modifies up to needlen bytes at s+len, but |
404 |
modifies newlen bytes |
405 |
eg. newlen = read(fd, s + len, needlen); |
406 |
ignoring errors for these examples |
407 |
*/ |
408 |
s[len + newlen] = '\0'; |
409 |
SvCUR_set(sv, len + newlen); |
410 |
SvUTF8_off(sv); |
411 |
SvSETMAGIC(sv); |
412 |
|
413 |
=begin original |
414 |
|
415 |
If you already have the data in memory or if you want to keep your |
416 |
code simple, you can use one of the sv_cat*() variants, such as |
417 |
sv_catpvn(). If you want to insert anywhere in the string you can use |
418 |
sv_insert() or sv_insert_flags(). |
419 |
|
420 |
=end original |
421 |
|
422 |
既にメモリにデータを持っている場合や、コードを単純に保ちたい場合は、 |
423 |
sv_catpvn() のような sv_cat*() の変種の一つを使えます。 |
424 |
もし文字列中のどこかに挿入したいなら、sv_insert() や |
425 |
sv_insert_flags() が使えます。 |
426 |
|
427 |
=begin original |
428 |
|
429 |
If you don't need the existing content of the SV, you can avoid some |
430 |
copying with: |
431 |
|
432 |
=end original |
433 |
|
434 |
SV の既存の内容が必要でないなら、次のようにして一部のコピーを |
435 |
回避できます: |
436 |
|
437 |
sv_setpvn(sv, "", 0); |
438 |
s = SvGROW(sv, needlen + 1); |
439 |
/* something that modifies up to needlen bytes at s, but modifies |
440 |
newlen bytes |
441 |
eg. newlen = read(fd, s. needlen); |
442 |
*/ |
443 |
s[newlen] = '\0'; |
444 |
SvCUR_set(sv, newlen); |
445 |
SvPOK_only(sv); /* also clears SVf_UTF8 */ |
446 |
SvSETMAGIC(sv); |
447 |
|
448 |
=begin original |
449 |
|
450 |
Again, if you already have the data in memory or want to avoid the |
451 |
complexity of the above, you can use sv_setpvn(). |
452 |
|
453 |
=end original |
454 |
|
455 |
再び、既にメモリにデータを持っている場合や、前述のような複雑さを |
456 |
避けたい場合は、sv_setpvn() が使えます。 |
457 |
|
458 |
=begin original |
459 |
|
460 |
If you have a buffer allocated with Newx() and want to set that as the |
461 |
SV's value, you can use sv_usepvn_flags(). That has some requirements |
462 |
if you want to avoid perl re-allocating the buffer to fit the trailing |
463 |
NUL: |
464 |
|
465 |
=end original |
466 |
|
467 |
If you have a buffer allocated with |
468 |
Newx() で割り当てられたバッファを持っていて、それを SV の値として |
469 |
設定したいなら、sv_usepvn_flags() が使えます。 |
470 |
perl が末尾の NUL に収まるようにバッファを再配置するのを避けたいなら、 |
471 |
いくつかの要求事項があります: |
472 |
|
473 |
Newx(buf, somesize+1, char); |
474 |
/* ... fill in buf ... */ |
475 |
buf[somesize] = '\0'; |
476 |
sv_usepvn_flags(sv, buf, somesize, SV_SMAGIC | SV_HAS_TRAILING_NUL); |
477 |
/* buf now belongs to perl, don't release it */ |
478 |
|
479 |
=begin original |
480 |
|
481 |
If you have an SV and want to know what kind of data Perl thinks is stored |
482 |
in it, you can use the following macros to check the type of SV you have. |
483 |
|
484 |
=end original |
485 |
|
486 |
ある SV があって、それに保管されているデータの種類が何であると |
487 |
Perl が考えているかを知りたいなら、 |
488 |
その SV の型をチェックするのに次のようなマクロが使えます。 |
489 |
|
490 |
SvIOK(SV*) |
491 |
SvNOK(SV*) |
492 |
SvPOK(SV*) |
493 |
|
494 |
=begin original |
495 |
|
496 |
You can get and set the current length of the string stored in an SV with |
497 |
the following macros: |
498 |
|
499 |
=end original |
500 |
|
501 |
SV に納められた文字列の現在の長さを取得したり設定したりするのには以下の |
502 |
マクロが使えます。 |
503 |
|
504 |
SvCUR(SV*) |
505 |
SvCUR_set(SV*, I32 val) |
506 |
|
507 |
=begin original |
508 |
|
509 |
You can also get a pointer to the end of the string stored in the SV |
510 |
with the macro: |
511 |
|
512 |
=end original |
513 |
|
514 |
同様に、SV に格納されている文字列の終端へのポインタを以下のマクロを |
515 |
使って得ることができます。 |
516 |
|
517 |
SvEND(SV*) |
518 |
|
519 |
=begin original |
520 |
|
521 |
But note that these last three macros are valid only if C<SvPOK()> is true. |
522 |
|
523 |
=end original |
524 |
|
525 |
ただし、これらは C<SvPOK()> が真のときだけ有効だということに気を |
526 |
つけてください。 |
527 |
|
528 |
=begin original |
529 |
|
530 |
If you want to append something to the end of string stored in an C<SV*>, |
531 |
you can use the following functions: |
532 |
|
533 |
=end original |
534 |
|
535 |
C<SV*> に格納されている文字列の末尾になにかを追加したいときに以下のような |
536 |
関数が使えます。 |
537 |
|
538 |
void sv_catpv(SV*, const char*); |
539 |
void sv_catpvn(SV*, const char*, STRLEN); |
540 |
void sv_catpvf(SV*, const char*, ...); |
541 |
void sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **, |
542 |
I32, bool); |
543 |
void sv_catsv(SV*, SV*); |
544 |
|
545 |
=begin original |
546 |
|
547 |
The first function calculates the length of the string to be appended by |
548 |
using C<strlen>. In the second, you specify the length of the string |
549 |
yourself. The third function processes its arguments like C<sprintf> and |
550 |
appends the formatted output. The fourth function works like C<vsprintf>. |
551 |
You can specify the address and length of an array of SVs instead of the |
552 |
va_list argument. The fifth function |
553 |
extends the string stored in the first |
554 |
SV with the string stored in the second SV. It also forces the second SV |
555 |
to be interpreted as a string. |
556 |
|
557 |
=end original |
558 |
|
559 |
最初の関数は C<strlen> を使って追加する文字列の長さを計算します。 |
560 |
二番目の関数では、関数を使用する人が文字列の長さを指定します。 |
561 |
三番目の関数はその引数を C<sprintf> の様に処理し、整形された結果を追加します。 |
562 |
四番目の関数は C<vsprintf> のように動作します。 |
563 |
va_list 引数の代わりに、SV の配列のアドレスと長さを指定できます。 |
564 |
五番目の関数は最初の SV にある文字列を二番目の SV にある文字列で拡張します。 |
565 |
また、この関数は二番目の SV を強制的に文字列として解釈します。 |
566 |
|
567 |
=begin original |
568 |
|
569 |
The C<sv_cat*()> functions are not generic enough to operate on values that |
570 |
have "magic". See L<Magic Virtual Tables> later in this document. |
571 |
|
572 |
=end original |
573 |
|
574 |
C<sv_cat*()> 関数群は "magic" を持っている値に対する |
575 |
操作に対して充分に一般化されたものではありません。 |
576 |
後述する L<Magic Virtual Tables> を参照してください。 |
577 |
|
578 |
=begin original |
579 |
|
580 |
If you know the name of a scalar variable, you can get a pointer to its SV |
581 |
by using the following: |
582 |
|
583 |
=end original |
584 |
|
585 |
スカラ変数の名前がわかれば、その SV へのポインタは以下のようにして |
586 |
得られます: |
587 |
|
588 |
SV* get_sv("package::varname", 0); |
589 |
|
590 |
=begin original |
591 |
|
592 |
This returns NULL if the variable does not exist. |
593 |
|
594 |
=end original |
595 |
|
596 |
これは変数が存在していない場合には NULL を返します。 |
597 |
|
598 |
=begin original |
599 |
|
600 |
If you want to know if this variable (or any other SV) is actually C<defined>, |
601 |
you can call: |
602 |
|
603 |
=end original |
604 |
|
605 |
その変数 (もしくは他の任意の SV) が、実際に B<定義されているか> を |
606 |
知りたいならば、 |
607 |
|
608 |
SvOK(SV*) |
609 |
|
610 |
=begin original |
611 |
|
612 |
The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>. |
613 |
|
614 |
=end original |
615 |
|
616 |
スカラの C<undef> 値は、C<PL_sv_undef> という SV のインスタンスに |
617 |
納められています。 |
618 |
|
619 |
=begin original |
620 |
|
621 |
Its address can be used whenever an C<SV*> is needed. Make sure that |
622 |
you don't try to compare a random sv with C<&PL_sv_undef>. For example |
623 |
when interfacing Perl code, it'll work correctly for: |
624 |
|
625 |
=end original |
626 |
|
627 |
そのアドレスは、C<SV*> が必要とされるところで使用することができます。 |
628 |
任意の sv を C<&PL_sv_undef> を比較しようとしないように気をつけてください。 |
629 |
例えば、Perl コードとのインターフェースで、以下は正しく動きます: |
630 |
|
631 |
foo(undef); |
632 |
|
633 |
=begin original |
634 |
|
635 |
But won't work when called as: |
636 |
|
637 |
=end original |
638 |
|
639 |
しかし、以下のように呼び出すと動作しません: |
640 |
|
641 |
$x = undef; |
642 |
foo($x); |
643 |
|
644 |
=begin original |
645 |
|
646 |
So to repeat always use SvOK() to check whether an sv is defined. |
647 |
|
648 |
=end original |
649 |
|
650 |
従って、sv が定義されているかをチェックするために、毎回繰り返して |
651 |
SvOK() を使ってください。 |
652 |
|
653 |
=begin original |
654 |
|
655 |
Also you have to be careful when using C<&PL_sv_undef> as a value in |
656 |
AVs or HVs (see L<AVs, HVs and undefined values>). |
657 |
|
658 |
=end original |
659 |
|
660 |
また、AV や HV の値として C<&PL_sv_undef> を使うときにも |
661 |
注意しなければなりません (L<AVs, HVs and undefined values> を |
662 |
参照してください)。 |
663 |
|
664 |
=begin original |
665 |
|
666 |
There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain |
667 |
boolean TRUE and FALSE values, respectively. Like C<PL_sv_undef>, their |
668 |
addresses can be used whenever an C<SV*> is needed. |
669 |
|
670 |
=end original |
671 |
|
672 |
真偽値の真と偽を表わす、C<PL_sv_yes> や C<PL_sv_no> という値もあります。 |
673 |
C<PL_sv_undef> と同様に、これらのアドレスも C<SV*> が必要なところで |
674 |
使うことができます。 |
675 |
|
676 |
=begin original |
677 |
|
678 |
Do not be fooled into thinking that C<(SV *) 0> is the same as C<&PL_sv_undef>. |
679 |
Take this code: |
680 |
|
681 |
=end original |
682 |
|
683 |
C<(SV *0)> と C<&PL_sv_undef> が同じであると考えて、だまされてはいけません。 |
684 |
次のようなコードを見てください: |
685 |
|
686 |
SV* sv = (SV*) 0; |
687 |
if (I-am-to-return-a-real-value) { |
688 |
sv = sv_2mortal(newSViv(42)); |
689 |
} |
690 |
sv_setsv(ST(0), sv); |
691 |
|
692 |
=begin original |
693 |
|
694 |
This code tries to return a new SV (which contains the value 42) if it should |
695 |
return a real value, or undef otherwise. Instead it has returned a NULL |
696 |
pointer which, somewhere down the line, will cause a segmentation violation, |
697 |
bus error, or just weird results. Change the zero to C<&PL_sv_undef> in the |
698 |
first line and all will be well. |
699 |
|
700 |
=end original |
701 |
|
702 |
このコードは、実値を返さなければならないときには、(値として 42 を |
703 |
持つ) 新しい SV を返そうとし、さもなくば undef を返そうとします。 |
704 |
ですが、どこかの行でヌルポインタを返して、セグメントバイオレーションが |
705 |
起こるか、何かおかしな結果になってしまいます。 |
706 |
最初の行の 0 を C<&PL_sv_undef> に変えれば、すべてがうまくいきます。 |
707 |
|
708 |
=begin original |
709 |
|
710 |
To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this |
711 |
call is not necessary (see L<Reference Counts and Mortality>). |
712 |
|
713 |
=end original |
714 |
|
715 |
生成した SV を解放するためには、C<SvREFCNT_dec(SV*)> を呼びます。 |
716 |
普通は、この呼び出しは必要ありません(L<Reference Counts and Mortality> を |
717 |
参照してください)。 |
718 |
|
719 |
=head2 Offsets |
720 |
|
721 |
(オフセット) |
722 |
|
723 |
=begin original |
724 |
|
725 |
Perl provides the function C<sv_chop> to efficiently remove characters |
726 |
from the beginning of a string; you give it an SV and a pointer to |
727 |
somewhere inside the PV, and it discards everything before the |
728 |
pointer. The efficiency comes by means of a little hack: instead of |
729 |
actually removing the characters, C<sv_chop> sets the flag C<OOK> |
730 |
(offset OK) to signal to other functions that the offset hack is in |
731 |
effect, and it moves the PV pointer (called C<SvPVX>) forward |
732 |
by the number of bytes chopped off, and adjusts C<SvCUR> and C<SvLEN> |
733 |
accordingly. (A portion of the space between the old and new PV |
734 |
pointers is used to store the count of chopped bytes.) |
735 |
|
736 |
=end original |
737 |
|
738 |
Perl は文字列の先頭から効率的に文字を削除するための関数 C<sv_chop> を |
739 |
提供されています; これに SV と、PV の内側のどこかへのポインタを渡すと、 |
740 |
そのポインタより手前の全てを削除します。 |
741 |
効率性はちょっとしたハックによるものです: 実際に文字を削除する代わりに、 |
742 |
C<sv_chop> は、他の関数にオフセットハックが有効であることを示す C<OOK> |
743 |
(offset OK) フラグを設定して、 |
744 |
切り落としたバイト数だけ (C<SvPVX> と呼ばれる) PV ポインタを前に進め、 |
745 |
C<SvCUR> と C<SvLEN> をそれぞれ調整します。 |
746 |
(新旧の PV ポインタの間のスペースの部分は、切り落としたバイト数を |
747 |
保管するために使われます。) |
748 |
|
749 |
=begin original |
750 |
|
751 |
Hence, at this point, the start of the buffer that we allocated lives |
752 |
at C<SvPVX(sv) - SvIV(sv)> in memory and the PV pointer is pointing |
753 |
into the middle of this allocated storage. |
754 |
|
755 |
=end original |
756 |
|
757 |
従って、この時点で、割り当てられたバッファの先頭はメモリ中の |
758 |
C<SvPVX(sv) - SvIV(sv)> であり、PV ポインタは割り当てられた保管領域の中間を |
759 |
指しています。 |
760 |
|
761 |
=begin original |
762 |
|
763 |
This is best demonstrated by example: |
764 |
|
765 |
=end original |
766 |
|
767 |
これは例による最良の実演です: |
768 |
|
769 |
% ./perl -Ilib -MDevel::Peek -le '$a="12345"; $a=~s/.//; Dump($a)' |
770 |
SV = PVIV(0x8128450) at 0x81340f0 |
771 |
REFCNT = 1 |
772 |
FLAGS = (POK,OOK,pPOK) |
773 |
IV = 1 (OFFSET) |
774 |
PV = 0x8135781 ( "1" . ) "2345"\0 |
775 |
CUR = 4 |
776 |
LEN = 5 |
777 |
|
778 |
=begin original |
779 |
|
780 |
Here the number of bytes chopped off (1) is put into IV, and |
781 |
C<Devel::Peek::Dump> helpfully reminds us that this is an offset. The |
782 |
portion of the string between the "real" and the "fake" beginnings is |
783 |
shown in parentheses, and the values of C<SvCUR> and C<SvLEN> reflect |
784 |
the fake beginning, not the real one. |
785 |
|
786 |
=end original |
787 |
|
788 |
ここで切り落とされたバイト数 (1) は IV に設定され、C<Devel::Peek::Dump> は |
789 |
これがオフセットであることを示す助けをしてくれます。 |
790 |
「実際」と「偽物」の開始の間の文字列の部分はかっこで示され、 |
791 |
C<SvCUR> と C<SvLEN> の値は実際のものではなく偽物の先頭を反映します。 |
792 |
|
793 |
=begin original |
794 |
|
795 |
Something similar to the offset hack is performed on AVs to enable |
796 |
efficient shifting and splicing off the beginning of the array; while |
797 |
C<AvARRAY> points to the first element in the array that is visible from |
798 |
Perl, C<AvALLOC> points to the real start of the C array. These are |
799 |
usually the same, but a C<shift> operation can be carried out by |
800 |
increasing C<AvARRAY> by one and decreasing C<AvFILL> and C<AvMAX>. |
801 |
Again, the location of the real start of the C array only comes into |
802 |
play when freeing the array. See C<av_shift> in F<av.c>. |
803 |
|
804 |
=end original |
805 |
|
806 |
オフセットハックと似たようなものは、配列の先頭の効率的なシフトと切り落としを |
807 |
有効にするために AV に対しても行われます; |
808 |
C<AvARRAY> は Perl から見える配列の最初の要素を指していますが、C<AvALLOC> は |
809 |
C の配列の実際の先頭を指しています。 |
810 |
これらは普通は同じですが、C<shift> 演算子は C<AvARRAY> を一つ増やして、 |
811 |
C<AvFILL> と C<AvMAX> を一つ減らします。 |
812 |
再び、C の配列の実際の先頭の一は、配列を解放するときにだけ使われます。 |
813 |
F<av.c> の C<av_shift> を参照してください。 |
814 |
|
815 |
=head2 What's Really Stored in an SV? |
816 |
|
817 |
(SV に実際に格納されているものは何ですか?) |
818 |
|
819 |
=begin original |
820 |
|
821 |
Recall that the usual method of determining the type of scalar you have is |
822 |
to use C<Sv*OK> macros. Because a scalar can be both a number and a string, |
823 |
usually these macros will always return TRUE and calling the C<Sv*V> |
824 |
macros will do the appropriate conversion of string to integer/double or |
825 |
integer/double to string. |
826 |
|
827 |
=end original |
828 |
|
829 |
自分で保持しているスカラの型を決定する通常の方法は、マクロ C<Sv*OK> を |
830 |
使うものでした。 |
831 |
スカラは数値にも文字列にもなり得ますから、普通、これらのマクロはいつも真を |
832 |
返します; そして C<Sv*V> マクロを呼ぶことで、文字列から整数/倍精度、 |
833 |
整数/倍精度から文字列への変換を行ないます。 |
834 |
|
835 |
=begin original |
836 |
|
837 |
If you I<really> need to know if you have an integer, double, or string |
838 |
pointer in an SV, you can use the following three macros instead: |
839 |
|
840 |
=end original |
841 |
|
842 |
もし、本当に SV にあるのが整数か、倍精度か、文字列ポインタかを |
843 |
知りたいのであれば、以下のようなマクロを代わりに使えます: |
844 |
|
845 |
SvIOKp(SV*) |
846 |
SvNOKp(SV*) |
847 |
SvPOKp(SV*) |
848 |
|
849 |
=begin original |
850 |
|
851 |
These will tell you if you truly have an integer, double, or string pointer |
852 |
stored in your SV. The "p" stands for private. |
853 |
|
854 |
=end original |
855 |
|
856 |
これらのマクロは、実際に SV に入っているものが整数か、倍精度か、 |
857 |
文字列ポインタかを教えてくれます。 |
858 |
"p" はプライベートの意味です。 |
859 |
|
860 |
=begin original |
861 |
|
862 |
There are various ways in which the private and public flags may differ. |
863 |
For example, in perl 5.16 and earlier a tied SV may have a valid |
864 |
underlying value in the IV slot (so SvIOKp is true), but the data |
865 |
should be accessed via the FETCH routine rather than directly, |
866 |
so SvIOK is false. (In perl 5.18 onwards, tied scalars use |
867 |
the flags the same way as untied scalars.) Another is when |
868 |
numeric conversion has occurred and precision has been lost: only the |
869 |
private flag is set on 'lossy' values. So when an NV is converted to an |
870 |
IV with loss, SvIOKp, SvNOKp and SvNOK will be set, while SvIOK wont be. |
871 |
|
872 |
=end original |
873 |
|
874 |
プライベートと公的なフラグが異なるのは様々な方法があります。 |
875 |
例えば、perl 5.16 以前では、tie された SV は IV スロットに妥当な値を |
876 |
保持している(従って SvIOKp は真) かもしれませんが、データは直接ではなく |
877 |
FETCH ルーチンを通してアクセスされるべきなため、SvIOK は偽です。 |
878 |
(perl 5.18 以降では、tie されたスカラは tie されていないスカラと同じように |
879 |
フラグを使います。) |
880 |
他の例としては数値変換が起こり、精度が落ちた場合です:プライベートな |
881 |
フラグのみが「精度が落ちた」値に設定されます。 |
882 |
それで、NV が精度が落ちる形で IV に変換されると、SvIOKp, SvNOKp, SvNOK は |
883 |
設定されますが、SvIOK は設定されません。 |
884 |
|
885 |
=begin original |
886 |
|
887 |
In general, though, it's best to use the C<Sv*V> macros. |
888 |
|
889 |
=end original |
890 |
|
891 |
しかし一般的には、C<Sv*V> マクロを使うだけにした方が良いでしょう。 |
892 |
|
893 |
=head2 Working with AVs |
894 |
|
895 |
(AV に対する作業) |
896 |
|
897 |
=begin original |
898 |
|
899 |
There are two ways to create and load an AV. The first method creates an |
900 |
empty AV: |
901 |
|
902 |
=end original |
903 |
|
904 |
AV を生成して値を設定するのには、二つの方法があります。 |
905 |
最初の方法は、単に空の AV を作るものです: |
906 |
|
907 |
AV* newAV(); |
908 |
|
909 |
=begin original |
910 |
|
911 |
The second method both creates the AV and initially populates it with SVs: |
912 |
|
913 |
=end original |
914 |
|
915 |
ふたつめの方法は、AV を生成した上で、初期値として SV の値を入れます: |
916 |
|
917 |
AV* av_make(SSize_t num, SV **ptr); |
918 |
|
919 |
=begin original |
920 |
|
921 |
The second argument points to an array containing C<num> C<SV*>'s. Once the |
922 |
AV has been created, the SVs can be destroyed, if so desired. |
923 |
|
924 |
=end original |
925 |
|
926 |
二番目の引数は num 個の SV* の配列を指しています。 |
927 |
AV が生成されてしまえば、SV は(それを望むのなら)破棄することができます。 |
928 |
|
929 |
=begin original |
930 |
|
931 |
Once the AV has been created, the following operations are possible on it: |
932 |
|
933 |
=end original |
934 |
|
935 |
いったん AV が生成されると、以下のような操作が行えます: |
936 |
|
937 |
|
938 |
void av_push(AV*, SV*); |
939 |
SV* av_pop(AV*); |
940 |
SV* av_shift(AV*); |
941 |
void av_unshift(AV*, SSize_t num); |
942 |
|
943 |
=begin original |
944 |
|
945 |
These should be familiar operations, with the exception of C<av_unshift>. |
946 |
This routine adds C<num> elements at the front of the array with the C<undef> |
947 |
value. You must then use C<av_store> (described below) to assign values |
948 |
to these new elements. |
949 |
|
950 |
=end original |
951 |
|
952 |
これらは、C<av_unshift> を除いては、お馴染みの演算でしょう。 |
953 |
C<av_unshift> は、配列の先頭に C<num> 個の C<undef> 値の要素を付け加えます。 |
954 |
その後で、(後述する) C<av_store> を使って新しい要素に値を |
955 |
代入しなければなりません。 |
956 |
|
957 |
=begin original |
958 |
|
959 |
Here are some other functions: |
960 |
|
961 |
=end original |
962 |
|
963 |
他にもいくつか関数があります: |
964 |
|
965 |
SSize_t av_top_index(AV*); |
966 |
SV** av_fetch(AV*, SSize_t key, I32 lval); |
967 |
SV** av_store(AV*, SSize_t key, SV* val); |
968 |
|
969 |
=begin original |
970 |
|
971 |
The C<av_top_index> function returns the highest index value in an array (just |
972 |
like $#array in Perl). If the array is empty, -1 is returned. The |
973 |
C<av_fetch> function returns the value at index C<key>, but if C<lval> |
974 |
is non-zero, then C<av_fetch> will store an undef value at that index. |
975 |
The C<av_store> function stores the value C<val> at index C<key>, and does |
976 |
not increment the reference count of C<val>. Thus the caller is responsible |
977 |
for taking care of that, and if C<av_store> returns NULL, the caller will |
978 |
have to decrement the reference count to avoid a memory leak. Note that |
979 |
C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s as their |
980 |
return value. |
981 |
|
982 |
=end original |
983 |
|
984 |
関数 C<av_top_index> は配列における最高位の添え字を(ちょうど Perl の $#array と |
985 |
同じように)返します。 |
986 |
もし配列が空であれば、-1 を返します。 |
987 |
関数 C<av_fetch> は添え字 C<key> の位置にある値を返しますが、C<lval> が |
988 |
非ゼロであれば、C<av_fetch> はその位置に undef を格納しようとします。 |
989 |
関数 C<av_store> は添え字 C<key> の位置に値 C<val> を格納し、C<val> の |
990 |
参照カウントをインクリメントしません。 |
991 |
従って、呼び出し側はこの振る舞いに注意して対処し、C<av_store> が |
992 |
NULL を返した場合には、メモリリークを防ぐために参照カウントの |
993 |
デクリメントを行う必要があるでしょう。 |
994 |
C<av_fetch> と C<av_store> の両方ともがその戻り値として |
995 |
C<SV*> ではなく、C<SV**> を返すということに注意してください。 |
996 |
|
997 |
=begin original |
998 |
|
999 |
A few more: |
1000 |
|
1001 |
=end original |
1002 |
|
1003 |
もう少しあります: |
1004 |
|
1005 |
void av_clear(AV*); |
1006 |
void av_undef(AV*); |
1007 |
void av_extend(AV*, SSize_t key); |
1008 |
|
1009 |
=begin original |
1010 |
|
1011 |
The C<av_clear> function deletes all the elements in the AV* array, but |
1012 |
does not actually delete the array itself. The C<av_undef> function will |
1013 |
delete all the elements in the array plus the array itself. The |
1014 |
C<av_extend> function extends the array so that it contains at least C<key+1> |
1015 |
elements. If C<key+1> is less than the currently allocated length of the array, |
1016 |
then nothing is done. |
1017 |
|
1018 |
=end original |
1019 |
|
1020 |
関数 C<av_clear> は、配列 AV* にあるすべての要素を削除しますが、 |
1021 |
配列自身の削除は行いません。 |
1022 |
関数 C<av_undef> は配列にあるすべての要素に加え、配列自身の削除も行います。 |
1023 |
関数 C<av_extend> は配列を C<key+1> 要素だけ拡張します。 |
1024 |
C<key+1> が配列のその時点での長さより短ければ、何も行なわれません。 |
1025 |
|
1026 |
=begin original |
1027 |
|
1028 |
If you know the name of an array variable, you can get a pointer to its AV |
1029 |
by using the following: |
1030 |
|
1031 |
=end original |
1032 |
|
1033 |
配列変数の名前がわかっているのであれば、次のようにしてその配列に |
1034 |
対応する AV へのポインタが得られます: |
1035 |
|
1036 |
AV* get_av("package::varname", 0); |
1037 |
|
1038 |
=begin original |
1039 |
|
1040 |
This returns NULL if the variable does not exist. |
1041 |
|
1042 |
=end original |
1043 |
|
1044 |
これは変数が存在していない場合には NULL を返します。 |
1045 |
|
1046 |
=begin original |
1047 |
|
1048 |
See L<Understanding the Magic of Tied Hashes and Arrays> for more |
1049 |
information on how to use the array access functions on tied arrays. |
1050 |
|
1051 |
=end original |
1052 |
|
1053 |
tie された配列における配列アクセス関数の使い方についての詳細は |
1054 |
L<Understanding the Magic of Tied Hashes and Arrays> を参照してください。 |
1055 |
|
1056 |
=head2 Working with HVs |
1057 |
|
1058 |
(HV に対する作業) |
1059 |
|
1060 |
=begin original |
1061 |
|
1062 |
To create an HV, you use the following routine: |
1063 |
|
1064 |
=end original |
1065 |
|
1066 |
HV を生成するには、以下のようなルーチンを使います: |
1067 |
|
1068 |
HV* newHV(); |
1069 |
|
1070 |
=begin original |
1071 |
|
1072 |
Once the HV has been created, the following operations are possible on it: |
1073 |
|
1074 |
=end original |
1075 |
|
1076 |
いったん HV が生成されると、以下のような操作が行えます: |
1077 |
|
1078 |
SV** hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash); |
1079 |
SV** hv_fetch(HV*, const char* key, U32 klen, I32 lval); |
1080 |
|
1081 |
=begin original |
1082 |
|
1083 |
The C<klen> parameter is the length of the key being passed in (Note that |
1084 |
you cannot pass 0 in as a value of C<klen> to tell Perl to measure the |
1085 |
length of the key). The C<val> argument contains the SV pointer to the |
1086 |
scalar being stored, and C<hash> is the precomputed hash value (zero if |
1087 |
you want C<hv_store> to calculate it for you). The C<lval> parameter |
1088 |
indicates whether this fetch is actually a part of a store operation, in |
1089 |
which case a new undefined value will be added to the HV with the supplied |
1090 |
key and C<hv_fetch> will return as if the value had already existed. |
1091 |
|
1092 |
=end original |
1093 |
|
1094 |
引数 C<klen> は、渡される key の長さです |
1095 |
(Perl にキーの長さを計算させるために、C<klen> の値として 0 を渡すことは |
1096 |
できないということに注意してください)。 |
1097 |
引数 C<val> は、設定されるスカラへの SV ポインタを入れ、hash は、 |
1098 |
あらかじめ計算したハッシュ値 (C<hv_store> に計算させる場合にはゼロ) です。 |
1099 |
引数 C<lval> で、このフェッチ操作が実はストア操作の一部であるかどうかを |
1100 |
示します; ストア操作であれば、新たな未定義値が与えられたキーを伴って |
1101 |
HV に追加され、C<hv_fetch> はその値が既に存在していたかのように |
1102 |
リターンします。 |
1103 |
|
1104 |
=begin original |
1105 |
|
1106 |
Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just |
1107 |
C<SV*>. To access the scalar value, you must first dereference the return |
1108 |
value. However, you should check to make sure that the return value is |
1109 |
not NULL before dereferencing it. |
1110 |
|
1111 |
=end original |
1112 |
|
1113 |
C<hv_store> や C<hv_fetch> は、C<SV**> を返すもので、C<SV*> ではないことに |
1114 |
注意してください。 |
1115 |
スカラ値をアクセスするには、まず戻り値の参照外し(dereference)をする |
1116 |
必要があります。 |
1117 |
しかし、その前に返却値が NULL でないことを確認すべきです。 |
1118 |
|
1119 |
=begin original |
1120 |
|
1121 |
The first of these two functions checks if a hash table entry exists, and the |
1122 |
second deletes it. |
1123 |
|
1124 |
=end original |
1125 |
|
1126 |
これら二つの関数の一つ目はハッシュテーブルのエントリが存在するかをチェックし、 |
1127 |
二つ目は削除を行います。 |
1128 |
|
1129 |
bool hv_exists(HV*, const char* key, U32 klen); |
1130 |
SV* hv_delete(HV*, const char* key, U32 klen, I32 flags); |
1131 |
|
1132 |
=begin original |
1133 |
|
1134 |
If C<flags> does not include the C<G_DISCARD> flag then C<hv_delete> will |
1135 |
create and return a mortal copy of the deleted value. |
1136 |
|
1137 |
=end original |
1138 |
|
1139 |
C<flag> に C<G_DISCARD> フラグが含まれていなければ、C<hv_delete> は |
1140 |
削除された値の揮発性のコピー(mortal copy)を生成し、それを返します。 |
1141 |
|
1142 |
=begin original |
1143 |
|
1144 |
And more miscellaneous functions: |
1145 |
|
1146 |
=end original |
1147 |
|
1148 |
さらに様々な関数があります: |
1149 |
|
1150 |
void hv_clear(HV*); |
1151 |
void hv_undef(HV*); |
1152 |
|
1153 |
=begin original |
1154 |
|
1155 |
Like their AV counterparts, C<hv_clear> deletes all the entries in the hash |
1156 |
table but does not actually delete the hash table. The C<hv_undef> deletes |
1157 |
both the entries and the hash table itself. |
1158 |
|
1159 |
=end original |
1160 |
|
1161 |
引数に AV を取る似たような関数と同様、C<hv_clear> はハッシュテーブルにある |
1162 |
すべてのエントリーを削除しますがハッシュテーブル自身は削除しません。 |
1163 |
C<hv_undef> はエントリーとハッシュテーブル自身の両方を削除します。 |
1164 |
|
1165 |
=begin original |
1166 |
|
1167 |
Perl keeps the actual data in a linked list of structures with a typedef of HE. |
1168 |
These contain the actual key and value pointers (plus extra administrative |
1169 |
overhead). The key is a string pointer; the value is an C<SV*>. However, |
1170 |
once you have an C<HE*>, to get the actual key and value, use the routines |
1171 |
specified below. |
1172 |
|
1173 |
=end original |
1174 |
|
1175 |
Perl は実際のデータを HE と typedef された構造体のリンクリストを使って |
1176 |
保持しています。 |
1177 |
これらは実際のキーと値のポインタ(それに加えて管理のための |
1178 |
ちょっとしたもの)を保持しています。 |
1179 |
キーは文字列へのポインタであり、値は C<SV*> です。 |
1180 |
しかしながら、一度 C<HE*> を持てば、実際のキーと値とを取得するためには |
1181 |
以下に挙げるようなルーチンを使います。 |
1182 |
|
1183 |
=begin original |
1184 |
|
1185 |
I32 hv_iterinit(HV*); |
1186 |
/* Prepares starting point to traverse hash table */ |
1187 |
HE* hv_iternext(HV*); |
1188 |
/* Get the next entry, and return a pointer to a |
1189 |
structure that has both the key and value */ |
1190 |
char* hv_iterkey(HE* entry, I32* retlen); |
1191 |
/* Get the key from an HE structure and also return |
1192 |
the length of the key string */ |
1193 |
SV* hv_iterval(HV*, HE* entry); |
1194 |
/* Return an SV pointer to the value of the HE |
1195 |
structure */ |
1196 |
SV* hv_iternextsv(HV*, char** key, I32* retlen); |
1197 |
/* This convenience routine combines hv_iternext, |
1198 |
hv_iterkey, and hv_iterval. The key and retlen |
1199 |
arguments are return values for the key and its |
1200 |
length. The value is returned in the SV* argument */ |
1201 |
|
1202 |
=end original |
1203 |
|
1204 |
I32 hv_iterinit(HV*); |
1205 |
/* ハッシュテーブルをたどるための開始点を準備 */ |
1206 |
HE* hv_iternext(HV*); |
1207 |
/* 次のエントリーを取得して、キーと値両方を持つ構造 |
1208 |
体へのポインタを返す */ |
1209 |
char* hv_iterkey(HE* entry, I32* retlen); |
1210 |
/* HE 構造体からキーを取得し、そのキー文字列の長さを |
1211 |
返す */ |
1212 |
SV* hv_iterval(HV*, HE* entry); |
1213 |
/* HE 構造体の値に対する SV ポインタを返す */ |
1214 |
SV* hv_iternextsv(HV*, char** key, I32* retlen); |
1215 |
/* この便利なルーチンは、hv_iternext、hv_iterkey、 |
1216 |
hv_itervalを組み合わせたものです。 |
1217 |
引数keyとretlenは、キーとその長さを表わす戻り値です。 |
1218 |
関数の戻り値はSV* で返されます */ |
1219 |
|
1220 |
=begin original |
1221 |
|
1222 |
If you know the name of a hash variable, you can get a pointer to its HV |
1223 |
by using the following: |
1224 |
|
1225 |
=end original |
1226 |
|
1227 |
配列変数の名前がわかるのであれば、以下のようにしてその変数の HV への |
1228 |
ポインタが得られます: |
1229 |
|
1230 |
HV* get_hv("package::varname", 0); |
1231 |
|
1232 |
=begin original |
1233 |
|
1234 |
This returns NULL if the variable does not exist. |
1235 |
|
1236 |
=end original |
1237 |
|
1238 |
これは変数が存在していない場合には NULL を返します。 |
1239 |
|
1240 |
=begin original |
1241 |
|
1242 |
The hash algorithm is defined in the C<PERL_HASH> macro: |
1243 |
|
1244 |
=end original |
1245 |
|
1246 |
ハッシュアルゴリズムは C<PERL_HASH> というマクロで定義されています。 |
1247 |
|
1248 |
PERL_HASH(hash, key, klen) |
1249 |
|
1250 |
=begin original |
1251 |
|
1252 |
The exact implementation of this macro varies by architecture and version |
1253 |
of perl, and the return value may change per invocation, so the value |
1254 |
is only valid for the duration of a single perl process. |
1255 |
|
1256 |
=end original |
1257 |
|
1258 |
このマクロの正確な実装はアーキテクチャと perl のバージョンによって異なり、 |
1259 |
返り値は起動毎に変わる可能性があります; 従って値は単一の perl プロセスの |
1260 |
間でのみ有効です。 |
1261 |
|
1262 |
=begin original |
1263 |
|
1264 |
See L<Understanding the Magic of Tied Hashes and Arrays> for more |
1265 |
information on how to use the hash access functions on tied hashes. |
1266 |
|
1267 |
=end original |
1268 |
|
1269 |
tie されたハッシュに対するハッシュアクセス関数の使い方に関する詳細は、 |
1270 |
L<Understanding the Magic of Tied Hashes and Arrays> を参照してください。 |
1271 |
|
1272 |
=head2 Hash API Extensions |
1273 |
|
1274 |
(ハッシュ API 拡張) |
1275 |
|
1276 |
=begin original |
1277 |
|
1278 |
Beginning with version 5.004, the following functions are also supported: |
1279 |
|
1280 |
=end original |
1281 |
|
1282 |
バージョン 5.004 から、以下の関数がサポートされました。 |
1283 |
|
1284 |
HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash); |
1285 |
HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash); |
1286 |
|
1287 |
bool hv_exists_ent (HV* tb, SV* key, U32 hash); |
1288 |
SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash); |
1289 |
|
1290 |
SV* hv_iterkeysv (HE* entry); |
1291 |
|
1292 |
=begin original |
1293 |
|
1294 |
Note that these functions take C<SV*> keys, which simplifies writing |
1295 |
of extension code that deals with hash structures. These functions |
1296 |
also allow passing of C<SV*> keys to C<tie> functions without forcing |
1297 |
you to stringify the keys (unlike the previous set of functions). |
1298 |
|
1299 |
=end original |
1300 |
|
1301 |
これらの関数が、ハッシュ構造を扱うエクステンションの記述を単純にする |
1302 |
C<SV*> キーを引数にとることに注意してください。 |
1303 |
これらの関数はまた、C<SV*> キーを(先に挙げた関数群とは異なり) |
1304 |
文字列化することなしに C<tie> 関数に渡すことを許しています。 |
1305 |
|
1306 |
=begin original |
1307 |
|
1308 |
They also return and accept whole hash entries (C<HE*>), making their |
1309 |
use more efficient (since the hash number for a particular string |
1310 |
doesn't have to be recomputed every time). See L<perlapi> for detailed |
1311 |
descriptions. |
1312 |
|
1313 |
=end original |
1314 |
|
1315 |
これらの関数はまた、ハッシュエントリー全体 (C<HE*>) を返したり受け付けて、 |
1316 |
より効率良く使用します(特定の文字列に対するハッシュ番号は |
1317 |
毎回計算しなおす必要はないからです)。 |
1318 |
詳しくは L<perlapi> を参照してください。 |
1319 |
|
1320 |
=begin original |
1321 |
|
1322 |
The following macros must always be used to access the contents of hash |
1323 |
entries. Note that the arguments to these macros must be simple |
1324 |
variables, since they may get evaluated more than once. See |
1325 |
L<perlapi> for detailed descriptions of these macros. |
1326 |
|
1327 |
=end original |
1328 |
|
1329 |
以下に挙げるマクロは、ハッシュエントリーの内容にアクセスするのに |
1330 |
常に使わなければならないものです。 |
1331 |
これらのマクロはその引数を二度以上評価する可能性があるので、マクロに |
1332 |
対する引数は単純な変数でなければならないということに注意してください。 |
1333 |
これらのマクロに関する詳細は L<perlapi> を参照してください。 |
1334 |
|
1335 |
HePV(HE* he, STRLEN len) |
1336 |
HeVAL(HE* he) |
1337 |
HeHASH(HE* he) |
1338 |
HeSVKEY(HE* he) |
1339 |
HeSVKEY_force(HE* he) |
1340 |
HeSVKEY_set(HE* he, SV* sv) |
1341 |
|
1342 |
=begin original |
1343 |
|
1344 |
These two lower level macros are defined, but must only be used when |
1345 |
dealing with keys that are not C<SV*>s: |
1346 |
|
1347 |
=end original |
1348 |
|
1349 |
低レベルマクロが二つ定義されていますが、これらは C<SV*> ではないキーを |
1350 |
扱うときにのみ使わなければならないものです。 |
1351 |
|
1352 |
HeKEY(HE* he) |
1353 |
HeKLEN(HE* he) |
1354 |
|
1355 |
=begin original |
1356 |
|
1357 |
Note that both C<hv_store> and C<hv_store_ent> do not increment the |
1358 |
reference count of the stored C<val>, which is the caller's responsibility. |
1359 |
If these functions return a NULL value, the caller will usually have to |
1360 |
decrement the reference count of C<val> to avoid a memory leak. |
1361 |
|
1362 |
=end original |
1363 |
|
1364 |
C<hv_store> と C<hv_store_ent> の両方ともが、C<val> に格納されている |
1365 |
参照カウントのインクリメントをしないということに注意してください; |
1366 |
それは呼び出し側の責任です。 |
1367 |
これらの関数が NULL を返した場合、呼び出し側はメモリリークを防ぐために、 |
1368 |
C<val> の参照カウントのデクリメントを行う必要が一般にはあるでしょう。 |
1369 |
|
1370 |
=head2 AVs, HVs and undefined values |
1371 |
|
1372 |
(AV, HV と未定義値) |
1373 |
|
1374 |
=begin original |
1375 |
|
1376 |
Sometimes you have to store undefined values in AVs or HVs. Although |
1377 |
this may be a rare case, it can be tricky. That's because you're |
1378 |
used to using C<&PL_sv_undef> if you need an undefined SV. |
1379 |
|
1380 |
=end original |
1381 |
|
1382 |
AV や HV に未定義値を保管しなければならないこともあります。 |
1383 |
これは珍しい場合ですが、手の込んだものになります。 |
1384 |
なぜなら、未定義の SV が必要なら、C<&PL_sv_undef> を使うことになるからです。 |
1385 |
|
1386 |
=begin original |
1387 |
|
1388 |
For example, intuition tells you that this XS code: |
1389 |
|
1390 |
=end original |
1391 |
|
1392 |
例えば、直感ではこの XS コードは: |
1393 |
|
1394 |
AV *av = newAV(); |
1395 |
av_store( av, 0, &PL_sv_undef ); |
1396 |
|
1397 |
=begin original |
1398 |
|
1399 |
is equivalent to this Perl code: |
1400 |
|
1401 |
=end original |
1402 |
|
1403 |
以下の Perl コードと等価です: |
1404 |
|
1405 |
my @av; |
1406 |
$av[0] = undef; |
1407 |
|
1408 |
=begin original |
1409 |
|
1410 |
Unfortunately, this isn't true. In perl 5.18 and earlier, AVs use C<&PL_sv_undef> as a marker |
1411 |
for indicating that an array element has not yet been initialized. |
1412 |
Thus, C<exists $av[0]> would be true for the above Perl code, but |
1413 |
false for the array generated by the XS code. In perl 5.20, storing |
1414 |
&PL_sv_undef will create a read-only element, because the scalar |
1415 |
&PL_sv_undef itself is stored, not a copy. |
1416 |
|
1417 |
=end original |
1418 |
|
1419 |
残念ながら、これは正しくありません。 |
1420 |
perl 5.18 以前では、AV は、配列要素がまだ初期化されていないことを示すための |
1421 |
印として C<&PL_sv_undef> を使います。 |
1422 |
従って、上述の Perl コードは C<exists $av[0]> は真ですが、 |
1423 |
XS コードによって生成された配列では偽です。 |
1424 |
perl 5.20 では、&PL_sv_undef を保管すると読み込み専用要素が作られます; |
1425 |
コピーではなく &PL_sv_undef 自体が保管されるからです。 |
1426 |
|
1427 |
=begin original |
1428 |
|
1429 |
Similar problems can occur when storing C<&PL_sv_undef> in HVs: |
1430 |
|
1431 |
=end original |
1432 |
|
1433 |
HV に C<&PL_sv_undef> を保管する時にも同様な問題が起こりえます: |
1434 |
|
1435 |
hv_store( hv, "key", 3, &PL_sv_undef, 0 ); |
1436 |
|
1437 |
=begin original |
1438 |
|
1439 |
This will indeed make the value C<undef>, but if you try to modify |
1440 |
the value of C<key>, you'll get the following error: |
1441 |
|
1442 |
=end original |
1443 |
|
1444 |
実際これは C<undef> 値を作りますが、C<key> の値を変更しようとすると、 |
1445 |
以下のようなエラーが出ます: |
1446 |
|
1447 |
Modification of non-creatable hash value attempted |
1448 |
|
1449 |
=begin original |
1450 |
|
1451 |
In perl 5.8.0, C<&PL_sv_undef> was also used to mark placeholders |
1452 |
in restricted hashes. This caused such hash entries not to appear |
1453 |
when iterating over the hash or when checking for the keys |
1454 |
with the C<hv_exists> function. |
1455 |
|
1456 |
=end original |
1457 |
|
1458 |
perl 5.8.0 では、C<&PL_sv_undef> は制限ハッシュのプレースホルダを |
1459 |
マークするためにも使われていました。 |
1460 |
これは、ハッシュを反復するときや C<hv_exists> 関数でキーを |
1461 |
チェックするときには、そのようなハッシュエントリは現れないということです。 |
1462 |
|
1463 |
=begin original |
1464 |
|
1465 |
You can run into similar problems when you store C<&PL_sv_yes> or |
1466 |
C<&PL_sv_no> into AVs or HVs. Trying to modify such elements |
1467 |
will give you the following error: |
1468 |
|
1469 |
=end original |
1470 |
|
1471 |
C<&PL_sv_yes> や C<&PL_sv_no> を AV や HV に保管するときにも同じような |
1472 |
問題が起こります。 |
1473 |
このような要素を修正しようとすると、以下のようなエラーが出ます: |
1474 |
|
1475 |
Modification of a read-only value attempted |
1476 |
|
1477 |
=begin original |
1478 |
|
1479 |
To make a long story short, you can use the special variables |
1480 |
C<&PL_sv_undef>, C<&PL_sv_yes> and C<&PL_sv_no> with AVs and |
1481 |
HVs, but you have to make sure you know what you're doing. |
1482 |
|
1483 |
=end original |
1484 |
|
1485 |
長い物語を短くすると、特殊変数 C<&PL_sv_undef>, C<&PL_sv_yes>, |
1486 |
C<&PL_sv_no> を AV や HV に使えますが、何をしているかを知っている必要が |
1487 |
あります。 |
1488 |
|
1489 |
=begin original |
1490 |
|
1491 |
Generally, if you want to store an undefined value in an AV |
1492 |
or HV, you should not use C<&PL_sv_undef>, but rather create a |
1493 |
new undefined value using the C<newSV> function, for example: |
1494 |
|
1495 |
=end original |
1496 |
|
1497 |
一般的に、AV や HV に未定義値を保管したいなら、C<&PL_sv_undef> を使わず、 |
1498 |
C<newSV> 関数を使って新しい未定義値を使ってください; 例えば: |
1499 |
|
1500 |
av_store( av, 42, newSV(0) ); |
1501 |
hv_store( hv, "foo", 3, newSV(0), 0 ); |
1502 |
|
1503 |
=head2 References |
1504 |
|
1505 |
(リファレンス) |
1506 |
|
1507 |
=begin original |
1508 |
|
1509 |
References are a special type of scalar that point to other data types |
1510 |
(including other references). |
1511 |
|
1512 |
=end original |
1513 |
|
1514 |
リファレンスは、(その他リファレンスを含む) 他のスカラ型を指す特別な |
1515 |
スカラ型です。 |
1516 |
|
1517 |
=begin original |
1518 |
|
1519 |
To create a reference, use either of the following functions: |
1520 |
|
1521 |
=end original |
1522 |
|
1523 |
リファレンスを生成するには、 |
1524 |
|
1525 |
SV* newRV_inc((SV*) thing); |
1526 |
SV* newRV_noinc((SV*) thing); |
1527 |
|
1528 |
=begin original |
1529 |
|
1530 |
The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. The |
1531 |
functions are identical except that C<newRV_inc> increments the reference |
1532 |
count of the C<thing>, while C<newRV_noinc> does not. For historical |
1533 |
reasons, C<newRV> is a synonym for C<newRV_inc>. |
1534 |
|
1535 |
=end original |
1536 |
|
1537 |
C<thing> には、C<SV*>, C<AV*>, C<HV*> のいずれかを置くことができます。 |
1538 |
これら二つの関数は、C<newRV_inc> が C<thing> の参照カウントを |
1539 |
インクリメントするけれども C<newRV_noinc> はインクリメントしないという点を |
1540 |
除き、同一です。 |
1541 |
歴史的な理由により、C<newRV> は C<newRV_inc> の同義語となっています。 |
1542 |
|
1543 |
=begin original |
1544 |
|
1545 |
Once you have a reference, you can use the following macro to dereference |
1546 |
the reference: |
1547 |
|
1548 |
=end original |
1549 |
|
1550 |
リファレンスができれば、以下のマクロを使ってリファレンスの参照外し |
1551 |
(dereference)ができます。 |
1552 |
|
1553 |
SvRV(SV*) |
1554 |
|
1555 |
=begin original |
1556 |
|
1557 |
then call the appropriate routines, casting the returned C<SV*> to either an |
1558 |
C<AV*> or C<HV*>, if required. |
1559 |
|
1560 |
=end original |
1561 |
|
1562 |
というマクロが使うことができ、返された C<SV*> を C<AV*> か C<HV*> に |
1563 |
キャストして、適切なルーチンを呼ぶことになります。 |
1564 |
|
1565 |
=begin original |
1566 |
|
1567 |
To determine if an SV is a reference, you can use the following macro: |
1568 |
|
1569 |
=end original |
1570 |
|
1571 |
SV がリファレンスであるかどうかを確認するために、以下のマクロを |
1572 |
使うことができます。 |
1573 |
|
1574 |
SvROK(SV*) |
1575 |
|
1576 |
=begin original |
1577 |
|
1578 |
To discover what type of value the reference refers to, use the following |
1579 |
macro and then check the return value. |
1580 |
|
1581 |
=end original |
1582 |
|
1583 |
リファレンスが参照している型を見つけるために、以下のマクロを使いその戻り値を |
1584 |
チェックします。 |
1585 |
|
1586 |
SvTYPE(SvRV(SV*)) |
1587 |
|
1588 |
=begin original |
1589 |
|
1590 |
The most useful types that will be returned are: |
1591 |
|
1592 |
=end original |
1593 |
|
1594 |
戻り値として返される型で有益なものは以下の通りです。 |
1595 |
|
1596 |
=begin original |
1597 |
|
1598 |
< SVt_PVAV Scalar |
1599 |
SVt_PVAV Array |
1600 |
SVt_PVHV Hash |
1601 |
SVt_PVCV Code |
1602 |
SVt_PVGV Glob (possibly a file handle) |
1603 |
|
1604 |
=end original |
1605 |
|
1606 |
< SVt_PVAV スカラ |
1607 |
SVt_PVAV 配列 |
1608 |
SVt_PVHV ハッシュ |
1609 |
SVt_PVCV コード |
1610 |
SVt_PVGV グロブ (ファイルハンドルかも) |
1611 |
|
1612 |
=begin original |
1613 |
|
1614 |
See L<perlapi/svtype> for more details. |
1615 |
|
1616 |
=end original |
1617 |
|
1618 |
詳しくは L<perlapi/svtype> を参照してください。 |
1619 |
|
1620 |
=head2 Blessed References and Class Objects |
1621 |
|
1622 |
(bless されたリファレンスとクラスオブジェクト) |
1623 |
|
1624 |
=begin original |
1625 |
|
1626 |
References are also used to support object-oriented programming. In perl's |
1627 |
OO lexicon, an object is simply a reference that has been blessed into a |
1628 |
package (or class). Once blessed, the programmer may now use the reference |
1629 |
to access the various methods in the class. |
1630 |
|
1631 |
=end original |
1632 |
|
1633 |
リファレンスはオブジェクト指向プログラミングをサポートするためにも使われます。 |
1634 |
perl のオブジェクト指向用語では、オブジェクトとはパッケージ |
1635 |
(もしくはクラス)に bless された単純なリファレンスです。 |
1636 |
一度 bless されれば、プログラマーはそのリファレンスをクラスにおける様々な |
1637 |
メソッドにアクセスするために使うことができます。 |
1638 |
|
1639 |
=begin original |
1640 |
|
1641 |
A reference can be blessed into a package with the following function: |
1642 |
|
1643 |
=end original |
1644 |
|
1645 |
以下の関数を使って、リファレンスをパッケージに bless することができます。 |
1646 |
|
1647 |
SV* sv_bless(SV* sv, HV* stash); |
1648 |
|
1649 |
=begin original |
1650 |
|
1651 |
The C<sv> argument must be a reference value. The C<stash> argument |
1652 |
specifies which class the reference will belong to. See |
1653 |
L<Stashes and Globs> for information on converting class names into stashes. |
1654 |
|
1655 |
=end original |
1656 |
|
1657 |
引数 C<sv> はリファレンス値でなければなりません。 |
1658 |
引数 C<stash> はリファレンスが属するクラスを指定します。 |
1659 |
クラス名のstashへの変換についての詳細は L<Stashes and Globs> を |
1660 |
参照してください。 |
1661 |
|
1662 |
=begin original |
1663 |
|
1664 |
/* Still under construction */ |
1665 |
|
1666 |
=end original |
1667 |
|
1668 |
/* Still under construction */ |
1669 |
|
1670 |
=begin original |
1671 |
|
1672 |
The following function upgrades rv to reference if not already one. |
1673 |
Creates a new SV for rv to point to. If C<classname> is non-null, the SV |
1674 |
is blessed into the specified class. SV is returned. |
1675 |
|
1676 |
=end original |
1677 |
|
1678 |
以下の関数は、まだ存在していなければ、rv をリファレンスにアップグレードします。 |
1679 |
rv が指し示すための新たな SV を生成します。 |
1680 |
C<classname> がヌルでなければ、SV は指定されたクラスに bless されます。 |
1681 |
SV が返されます。 |
1682 |
|
1683 |
SV* newSVrv(SV* rv, const char* classname); |
1684 |
|
1685 |
=begin original |
1686 |
|
1687 |
The following three functions copy integer, unsigned integer or double |
1688 |
into an SV whose reference is C<rv>. SV is blessed if C<classname> is |
1689 |
non-null. |
1690 |
|
1691 |
=end original |
1692 |
|
1693 |
以下の三つの関数は、整数、符号なし整数、倍精度実数を C<rv> が参照している SV へ |
1694 |
コピーします。 |
1695 |
SV は C<classname> がヌルでなければ bless されます。 |
1696 |
|
1697 |
SV* sv_setref_iv(SV* rv, const char* classname, IV iv); |
1698 |
SV* sv_setref_uv(SV* rv, const char* classname, UV uv); |
1699 |
SV* sv_setref_nv(SV* rv, const char* classname, NV iv); |
1700 |
|
1701 |
=begin original |
1702 |
|
1703 |
The following function copies the pointer value (I<the address, not the |
1704 |
string!>) into an SV whose reference is rv. SV is blessed if C<classname> |
1705 |
is non-null. |
1706 |
|
1707 |
=end original |
1708 |
|
1709 |
以下の関数は、ポインタ値(B<アドレスであって、文字列ではありません!>)を rv が |
1710 |
参照している SV へコピーします。 |
1711 |
SV は C<classname> がヌルでなければ bless されます。 |
1712 |
|
1713 |
SV* sv_setref_pv(SV* rv, const char* classname, void* pv); |
1714 |
|
1715 |
=begin original |
1716 |
|
1717 |
The following function copies a string into an SV whose reference is C<rv>. |
1718 |
Set length to 0 to let Perl calculate the string length. SV is blessed if |
1719 |
C<classname> is non-null. |
1720 |
|
1721 |
=end original |
1722 |
|
1723 |
以下の関数は、文字列を C<rv> が参照している SV へコピーします。 |
1724 |
length に 0 を設定すると、Perl が文字列の長さを計算します。 |
1725 |
SV は C<classname> がヌルでなければ bless されます。 |
1726 |
|
1727 |
SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, |
1728 |
STRLEN length); |
1729 |
|
1730 |
=begin original |
1731 |
|
1732 |
The following function tests whether the SV is blessed into the specified |
1733 |
class. It does not check inheritance relationships. |
1734 |
|
1735 |
=end original |
1736 |
|
1737 |
以下の関数は、SV が特定のクラスに bless されているかどうかを検査します。 |
1738 |
これは継承の関係のチェックはしません。 |
1739 |
|
1740 |
int sv_isa(SV* sv, const char* name); |
1741 |
|
1742 |
=begin original |
1743 |
|
1744 |
The following function tests whether the SV is a reference to a blessed object. |
1745 |
|
1746 |
=end original |
1747 |
|
1748 |
以下の関数は、SV が bless されたオブジェクトのリファレンスであるかどうかを |
1749 |
検査します。 |
1750 |
|
1751 |
int sv_isobject(SV* sv); |
1752 |
|
1753 |
=begin original |
1754 |
|
1755 |
The following function tests whether the SV is derived from the specified |
1756 |
class. SV can be either a reference to a blessed object or a string |
1757 |
containing a class name. This is the function implementing the |
1758 |
C<UNIVERSAL::isa> functionality. |
1759 |
|
1760 |
=end original |
1761 |
|
1762 |
以下の関数は、SV が特定のクラスから派生したものがどうかを検査します。 |
1763 |
SV は bless されたオブジェクトのリファレンスでも、 |
1764 |
クラス名を保持している文字列であってもかまいません。 |
1765 |
これは C<UNIVERSAL::isa> の機能を実装している関数です。 |
1766 |
|
1767 |
bool sv_derived_from(SV* sv, const char* name); |
1768 |
|
1769 |
=begin original |
1770 |
|
1771 |
To check if you've got an object derived from a specific class you have |
1772 |
to write: |
1773 |
|
1774 |
=end original |
1775 |
|
1776 |
ある特定のクラスの派生オブジェクトを受け取ったかどうか検査するには、 |
1777 |
以下のように書く必要があります。 |
1778 |
|
1779 |
if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... } |
1780 |
|
1781 |
=head2 Creating New Variables |
1782 |
|
1783 |
(新しい変数の作成) |
1784 |
|
1785 |
=begin original |
1786 |
|
1787 |
To create a new Perl variable with an undef value which can be accessed from |
1788 |
your Perl script, use the following routines, depending on the variable type. |
1789 |
|
1790 |
=end original |
1791 |
|
1792 |
Perl スクリプトからアクセスできる未定義値を持つ新たな Perl の変数を |
1793 |
生成するには、以下に示すルーチンを変数の型に応じて使います。 |
1794 |
|
1795 |
SV* get_sv("package::varname", GV_ADD); |
1796 |
AV* get_av("package::varname", GV_ADD); |
1797 |
HV* get_hv("package::varname", GV_ADD); |
1798 |
|
1799 |
=begin original |
1800 |
|
1801 |
Notice the use of GV_ADD as the second parameter. The new variable can now |
1802 |
be set, using the routines appropriate to the data type. |
1803 |
|
1804 |
=end original |
1805 |
|
1806 |
二番目のパラメータとして GV_ADD を使っているということに注意してください。 |
1807 |
新しい変数はここでデータ型に対する適切なルーチンを使うことで設定できます。 |
1808 |
|
1809 |
=begin original |
1810 |
|
1811 |
There are additional macros whose values may be bitwise OR'ed with the |
1812 |
C<GV_ADD> argument to enable certain extra features. Those bits are: |
1813 |
|
1814 |
=end original |
1815 |
|
1816 |
C<GV_ADD> 引数とビット和を取って、幾つかの追加機能を有効とするような |
1817 |
二つのマクロがあります。 |
1818 |
ビットは以下の通りです: |
1819 |
|
1820 |
=over |
1821 |
|
1822 |
=item GV_ADDMULTI |
1823 |
|
1824 |
=begin original |
1825 |
|
1826 |
Marks the variable as multiply defined, thus preventing the: |
1827 |
|
1828 |
=end original |
1829 |
|
1830 |
変数に多重定義 (multiply defined) であると印を付け: |
1831 |
|
1832 |
Name <varname> used only once: possible typo |
1833 |
|
1834 |
=begin original |
1835 |
|
1836 |
warning. |
1837 |
|
1838 |
=end original |
1839 |
|
1840 |
警告を防ぎます。 |
1841 |
|
1842 |
=item GV_ADDWARN |
1843 |
|
1844 |
=begin original |
1845 |
|
1846 |
Issues the warning: |
1847 |
|
1848 |
=end original |
1849 |
|
1850 |
以下の警告を: |
1851 |
|
1852 |
Had to create <varname> unexpectedly |
1853 |
|
1854 |
=begin original |
1855 |
|
1856 |
if the variable did not exist before the function was called. |
1857 |
|
1858 |
=end original |
1859 |
|
1860 |
変数が、その関数の呼び出し以前に存在してなかった場合に発生させます。 |
1861 |
|
1862 |
=back |
1863 |
|
1864 |
=begin original |
1865 |
|
1866 |
If you do not specify a package name, the variable is created in the current |
1867 |
package. |
1868 |
|
1869 |
=end original |
1870 |
|
1871 |
パッケージ名を指定しなかった場合、変数はカレントパッケージで生成されます。 |
1872 |
|
1873 |
=head2 Reference Counts and Mortality |
1874 |
|
1875 |
(参照カウントと揮発性) |
1876 |
|
1877 |
=begin original |
1878 |
|
1879 |
Perl uses a reference count-driven garbage collection mechanism. SVs, |
1880 |
AVs, or HVs (xV for short in the following) start their life with a |
1881 |
reference count of 1. If the reference count of an xV ever drops to 0, |
1882 |
then it will be destroyed and its memory made available for reuse. |
1883 |
|
1884 |
=end original |
1885 |
|
1886 |
Perl は参照カウント駆動(reference count-driven)のガベージコレクション |
1887 |
機構を使用しています。 |
1888 |
SV、AV、そしてHV(以下 xV と省略します) |
1889 |
はその一生を参照カウント 1 から始めます。 |
1890 |
xV の参照カウントが 0 まで落ちた場合、そのリファレンスは破棄されて、 |
1891 |
それが使っていたメモリは再利用できるようにされます。 |
1892 |
|
1893 |
=begin original |
1894 |
|
1895 |
This normally doesn't happen at the Perl level unless a variable is |
1896 |
undef'ed or the last variable holding a reference to it is changed or |
1897 |
overwritten. At the internal level, however, reference counts can be |
1898 |
manipulated with the following macros: |
1899 |
|
1900 |
=end original |
1901 |
|
1902 |
これは、Perl レベルにおいては、変数が undef されるとかリファレンスを |
1903 |
保持している最後の変数が変更されたとか上書きされるということがない限りは |
1904 |
起こりません。 |
1905 |
しかし内部的には、参照カウントは以下に挙げるマクロを使って操作できます。 |
1906 |
|
1907 |
int SvREFCNT(SV* sv); |
1908 |
SV* SvREFCNT_inc(SV* sv); |
1909 |
void SvREFCNT_dec(SV* sv); |
1910 |
|
1911 |
=begin original |
1912 |
|
1913 |
However, there is one other function which manipulates the reference |
1914 |
count of its argument. The C<newRV_inc> function, you will recall, |
1915 |
creates a reference to the specified argument. As a side effect, |
1916 |
it increments the argument's reference count. If this is not what |
1917 |
you want, use C<newRV_noinc> instead. |
1918 |
|
1919 |
=end original |
1920 |
|
1921 |
その引数の参照カウントを操作する別の関数が一つあります。 |
1922 |
C<newRV_inc> という関数がそれです。 |
1923 |
これは指定された引数の参照を生成して、その副作用として引数の |
1924 |
参照カウントをインクリメントします。 |
1925 |
もしこの副作用が邪魔であれば、C<newRV_noinc> を代わりに使ってください。 |
1926 |
|
1927 |
=begin original |
1928 |
|
1929 |
For example, imagine you want to return a reference from an XSUB function. |
1930 |
Inside the XSUB routine, you create an SV which initially has a reference |
1931 |
count of one. Then you call C<newRV_inc>, passing it the just-created SV. |
1932 |
This returns the reference as a new SV, but the reference count of the |
1933 |
SV you passed to C<newRV_inc> has been incremented to two. Now you |
1934 |
return the reference from the XSUB routine and forget about the SV. |
1935 |
But Perl hasn't! Whenever the returned reference is destroyed, the |
1936 |
reference count of the original SV is decreased to one and nothing happens. |
1937 |
The SV will hang around without any way to access it until Perl itself |
1938 |
terminates. This is a memory leak. |
1939 |
|
1940 |
=end original |
1941 |
|
1942 |
たとえば、XSUB 関数からリファレンスを返したいと思ったとしましょう。 |
1943 |
XSUB ルーチンの中で、初期値として参照カウント 1 を持つ SV を生成します。 |
1944 |
それから今作成した SV を引数にして C<newRV_inc> を呼びます。 |
1945 |
これは新たな SV としての参照を返しますが、C<newRV_inc> に引数として渡した |
1946 |
SV の参照カウントは 2 にインクリメントされます。 |
1947 |
ここで XSUB ルーチンからそのリファレンスを戻り値として返し、SV のことは |
1948 |
忘れましょう。 |
1949 |
けれども Perl は忘れてません! |
1950 |
戻り値で返されたリファレンスが破棄されたときにはいつも、元々の SV の |
1951 |
参照カウントが 1 へと減じられ、そして何事もおこりません。 |
1952 |
その SV は、Perl 自身が終了するまではそれにアクセスするなんの手段も |
1953 |
持たずに中ぶらりんになります。 |
1954 |
これはメモリリークです。 |
1955 |
|
1956 |
=begin original |
1957 |
|
1958 |
The correct procedure, then, is to use C<newRV_noinc> instead of |
1959 |
C<newRV_inc>. Then, if and when the last reference is destroyed, |
1960 |
the reference count of the SV will go to zero and it will be destroyed, |
1961 |
stopping any memory leak. |
1962 |
|
1963 |
=end original |
1964 |
|
1965 |
ここでの正しい手順は、C<newRV_inc> ではなく C<newRV_noinc> を |
1966 |
使うということです。 |
1967 |
これによって、最後のリファレンスが破棄されたときに SV の参照カウントは |
1968 |
0 となってその SV が破棄されて、メモリリークを食い止めます。 |
1969 |
|
1970 |
=begin original |
1971 |
|
1972 |
There are some convenience functions available that can help with the |
1973 |
destruction of xVs. These functions introduce the concept of "mortality". |
1974 |
An xV that is mortal has had its reference count marked to be decremented, |
1975 |
but not actually decremented, until "a short time later". Generally the |
1976 |
term "short time later" means a single Perl statement, such as a call to |
1977 |
an XSUB function. The actual determinant for when mortal xVs have their |
1978 |
reference count decremented depends on two macros, SAVETMPS and FREETMPS. |
1979 |
See L<perlcall> and L<perlxs> for more details on these macros. |
1980 |
|
1981 |
=end original |
1982 |
|
1983 |
xV を破棄するのを助けるような便利な関数が幾つかあります。 |
1984 |
これらの関数は「揮発性」(mortality) のコンセプトを導入します。 |
1985 |
ある揮発性の xV はその参照カウントをデクリメントするようにマークしますが、 |
1986 |
実際には「ちょっと後」(a short time later)までデクリメントが行なわれません。 |
1987 |
一般的には、「ちょっと後」とは、XSUB 関数の呼び出しのような |
1988 |
Perl の一つの文です。 |
1989 |
揮発性の xV が持っている参照カウントのデクリメントを行うタイミングの決定は |
1990 |
二つのマクロ、SAVETMPS と FREETMPS に依存しています。 |
1991 |
これら二つのマクロについての説明は |
1992 |
L<perlcall> と L<perlxs> を参照してください。 |
1993 |
|
1994 |
=begin original |
1995 |
|
1996 |
"Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>. |
1997 |
However, if you mortalize a variable twice, the reference count will |
1998 |
later be decremented twice. |
1999 |
|
2000 |
=end original |
2001 |
|
2002 |
「揮発化」("Mortalization") はそれから、C<SvREFCNT_dec> に決定権を委ねます。 |
2003 |
しかし、ある変数を二度揮発的にした場合、その参照カウントは後で |
2004 |
二度デクリメントされます。 |
2005 |
|
2006 |
=begin original |
2007 |
|
2008 |
"Mortal" SVs are mainly used for SVs that are placed on perl's stack. |
2009 |
For example an SV which is created just to pass a number to a called sub |
2010 |
is made mortal to have it cleaned up automatically when it's popped off |
2011 |
the stack. Similarly, results returned by XSUBs (which are pushed on the |
2012 |
stack) are often made mortal. |
2013 |
|
2014 |
=end original |
2015 |
|
2016 |
「揮発性」SV は主に、perl のスタックに置かれる SV に対して使われます。 |
2017 |
例えば、単に数値を呼び出したサブルーチンに渡すために作られた SV は |
2018 |
スタックからポップされたときに自動的に片付けられるように揮発性になります。 |
2019 |
同様に、(スタックにプッシュされた) XSUB から返された結果はしばしば |
2020 |
揮発性となります。 |
2021 |
|
2022 |
=begin original |
2023 |
|
2024 |
To create a mortal variable, use the functions: |
2025 |
|
2026 |
=end original |
2027 |
|
2028 |
揮発性の変数を生成するには、以下の関数を使います: |
2029 |
|
2030 |
SV* sv_newmortal() |
2031 |
SV* sv_2mortal(SV*) |
2032 |
SV* sv_mortalcopy(SV*) |
2033 |
|
2034 |
=begin original |
2035 |
|
2036 |
The first call creates a mortal SV (with no value), the second converts an existing |
2037 |
SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the |
2038 |
third creates a mortal copy of an existing SV. |
2039 |
Because C<sv_newmortal> gives the new SV no value, it must normally be given one |
2040 |
via C<sv_setpv>, C<sv_setiv>, etc. : |
2041 |
|
2042 |
=end original |
2043 |
|
2044 |
最初のものは(値のない)揮発性の SV を生成し、ふたつめは既にある SV を |
2045 |
揮発性の SV に変換します(そして、このために C<SvREFCNT_dec> を呼び出しを |
2046 |
遅らせます); 三つめは、既に存在する SV の揮発性のコピーを生成します。 |
2047 |
C<sv_newmortal> は値のない新しい SV を作るので、普通は |
2048 |
C<sv_setpv>, C<sv_setiv> などを使って作らなければなりません: |
2049 |
|
2050 |
SV *tmp = sv_newmortal(); |
2051 |
sv_setiv(tmp, an_integer); |
2052 |
|
2053 |
=begin original |
2054 |
|
2055 |
As that is multiple C statements it is quite common so see this idiom instead: |
2056 |
|
2057 |
=end original |
2058 |
|
2059 |
これは C の複数文なので、代わりにこの慣用法がとても一般的です: |
2060 |
|
2061 |
SV *tmp = sv_2mortal(newSViv(an_integer)); |
2062 |
|
2063 |
=begin original |
2064 |
|
2065 |
You should be careful about creating mortal variables. Strange things |
2066 |
can happen if you make the same value mortal within multiple contexts, |
2067 |
or if you make a variable mortal multiple |
2068 |
times. Thinking of "Mortalization" |
2069 |
as deferred C<SvREFCNT_dec> should help to minimize such problems. |
2070 |
For example if you are passing an SV which you I<know> has a high enough REFCNT |
2071 |
to survive its use on the stack you need not do any mortalization. |
2072 |
If you are not sure then doing an C<SvREFCNT_inc> and C<sv_2mortal>, or |
2073 |
making a C<sv_mortalcopy> is safer. |
2074 |
|
2075 |
=end original |
2076 |
|
2077 |
揮発性の変数を生成するに当たっては十分注意すべきです。 |
2078 |
もし、同じ変数を複合コンテキストの中で揮発性にしたり、ある変数を複数回 |
2079 |
揮発性にしてしまったりすればおかしな自体が起こるかもしれません。 |
2080 |
保留した C<SvREFCNT_dec> として「揮発化」を考えるとこのような問題を |
2081 |
最小化する助けになるでしょう。 |
2082 |
例えば、スタック上で使っても生き残るのに十分に大きな REFCNT を持つと |
2083 |
I<知っている> SV を渡す場合、揮発化は不要です。 |
2084 |
C<SvREFCNT_inc> と C<sv_2mortal> をするかどうかはっきりしないときは、 |
2085 |
C<sv_mortalcopy> を作るのがより安全です。 |
2086 |
|
2087 |
=begin original |
2088 |
|
2089 |
The mortal routines are not just for SVs; AVs and HVs can be |
2090 |
made mortal by passing their address (type-casted to C<SV*>) to the |
2091 |
C<sv_2mortal> or C<sv_mortalcopy> routines. |
2092 |
|
2093 |
=end original |
2094 |
|
2095 |
揮発性のルーチンは、単に SV のためだけではありません; |
2096 |
AV や HV も、C<sv_2mortal> や C<sv_mortalcopy> ルーチンに、アドレスを |
2097 |
(C<SV*> にキャストして) 渡すことで、揮発性にすることができます。 |
2098 |
|
2099 |
=head2 Stashes and Globs |
2100 |
|
2101 |
(スタッシュとグロブ) |
2102 |
|
2103 |
=begin original |
2104 |
|
2105 |
A B<stash> is a hash that contains all variables that are defined |
2106 |
within a package. Each key of the stash is a symbol |
2107 |
name (shared by all the different types of objects that have the same |
2108 |
name), and each value in the hash table is a GV (Glob Value). This GV |
2109 |
in turn contains references to the various objects of that name, |
2110 |
including (but not limited to) the following: |
2111 |
|
2112 |
=end original |
2113 |
|
2114 |
B<スタッシュ> ("stash")とは、パッケージ内で定義された全ての変数が |
2115 |
入っているハッシュのことです。 |
2116 |
ハッシュテーブルにあるそれぞれの key は、(同じ名前のすべての異なる型の |
2117 |
オブジェクトで共有される) シンボル名で、ハッシュテーブルの個々の |
2118 |
値は、(グローバル値のための) GV と呼ばれます。 |
2119 |
GV には、以下のものを含む (これらに限りませんが)、その名前の様々な |
2120 |
オブジェクトへのリファレンスが次々に入ることになります。 |
2121 |
|
2122 |
Scalar Value |
2123 |
Array Value |
2124 |
Hash Value |
2125 |
I/O Handle |
2126 |
Format |
2127 |
Subroutine |
2128 |
|
2129 |
=begin original |
2130 |
|
2131 |
There is a single stash called C<PL_defstash> that holds the items that exist |
2132 |
in the C<main> package. To get at the items in other packages, append the |
2133 |
string "::" to the package name. The items in the C<Foo> package are in |
2134 |
the stash C<Foo::> in PL_defstash. The items in the C<Bar::Baz> package are |
2135 |
in the stash C<Baz::> in C<Bar::>'s stash. |
2136 |
|
2137 |
=end original |
2138 |
|
2139 |
C<main> パッケージにあるアイテムを保持する C<PL_defstash> と呼ばれる |
2140 |
スタッシュがあります。 |
2141 |
他のパッケージにあるアイテムを取得するには、パッケージ名に「::」を付加します。 |
2142 |
C<Foo> というパッケージにあるアイテムは PL_defstash の C<Foo::> という |
2143 |
スタッシュの中にあります。 |
2144 |
パッケージ C<Bar::Baz> にあるアイテムは C<Bar::> のスタッシュの中の |
2145 |
C<Baz::> のスタッシュの中にあります。 |
2146 |
|
2147 |
=begin original |
2148 |
|
2149 |
To get the stash pointer for a particular package, use the function: |
2150 |
|
2151 |
=end original |
2152 |
|
2153 |
特定のパッケージの HV ポインタの入手には、以下の関数が使えます: |
2154 |
|
2155 |
HV* gv_stashpv(const char* name, I32 flags) |
2156 |
HV* gv_stashsv(SV*, I32 flags) |
2157 |
|
2158 |
=begin original |
2159 |
|
2160 |
The first function takes a literal string, the second uses the string stored |
2161 |
in the SV. Remember that a stash is just a hash table, so you get back an |
2162 |
C<HV*>. The C<flags> flag will create a new package if it is set to GV_ADD. |
2163 |
|
2164 |
=end original |
2165 |
|
2166 |
最初の関数が、リテラル文字列をとり、二番目が SV に入れた文字列を使います。 |
2167 |
stash は単なるハッシュなので、C<HV*> を受け取るということを |
2168 |
忘れないでください。 |
2169 |
C<flags> フラグが GV_ADD にセットされている場合には新たなパッケージを |
2170 |
生成します。 |
2171 |
|
2172 |
=begin original |
2173 |
|
2174 |
The name that C<gv_stash*v> wants is the name of the package whose symbol table |
2175 |
you want. The default package is called C<main>. If you have multiply nested |
2176 |
packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl |
2177 |
language itself. |
2178 |
|
2179 |
=end original |
2180 |
|
2181 |
C<gv_stash*v> が要求する name はシンボルテーブルを手に入れようとする |
2182 |
パッケージの名前です。 |
2183 |
デフォルトのパッケージは、C<main> というものです。 |
2184 |
多重にネストしたパッケージであれば、Perl での場合と同様に、 |
2185 |
C<::> で区切って C<gv_stash*v> に名前を渡すのが正しい方法です。 |
2186 |
|
2187 |
=begin original |
2188 |
|
2189 |
Alternately, if you have an SV that is a blessed reference, you can find |
2190 |
out the stash pointer by using: |
2191 |
|
2192 |
=end original |
2193 |
|
2194 |
あるいは、もし bless されたリファレンスである SV があれば、 |
2195 |
以下のようにしてを使ってもスタッシュポインタを探すことができ: |
2196 |
|
2197 |
HV* SvSTASH(SvRV(SV*)); |
2198 |
|
2199 |
=begin original |
2200 |
|
2201 |
then use the following to get the package name itself: |
2202 |
|
2203 |
=end original |
2204 |
|
2205 |
パッケージ名自身は、以下のようにして得られます: |
2206 |
|
2207 |
char* HvNAME(HV* stash); |
2208 |
|
2209 |
=begin original |
2210 |
|
2211 |
If you need to bless or re-bless an object you can use the following |
2212 |
function: |
2213 |
|
2214 |
=end original |
2215 |
|
2216 |
Perl スクリプトへ bless された値を返す必要があれば、以下の関数が使えます: |
2217 |
|
2218 |
SV* sv_bless(SV*, HV* stash) |
2219 |
|
2220 |
=begin original |
2221 |
|
2222 |
where the first argument, an C<SV*>, must be a reference, and the second |
2223 |
argument is a stash. The returned C<SV*> can now be used in the same way |
2224 |
as any other SV. |
2225 |
|
2226 |
=end original |
2227 |
|
2228 |
最初の引数 C<SV*> はリファレンスで、二番目の引数がスタッシュです。 |
2229 |
返された C<SV*> は、他の SV と同様に使うことができます。 |
2230 |
|
2231 |
=begin original |
2232 |
|
2233 |
For more information on references and blessings, consult L<perlref>. |
2234 |
|
2235 |
=end original |
2236 |
|
2237 |
リファレンスと bless についてのより詳しい情報は L<perlref> を |
2238 |
参照してください。 |
2239 |
|
2240 |
=head2 Double-Typed SVs |
2241 |
|
2242 |
(二重型 SV) |
2243 |
|
2244 |
=begin original |
2245 |
|
2246 |
Scalar variables normally contain only one type of value, an integer, |
2247 |
double, pointer, or reference. Perl will automatically convert the |
2248 |
actual scalar data from the stored type into the requested type. |
2249 |
|
2250 |
=end original |
2251 |
|
2252 |
スカラ変数は通常、整数、倍精度、ポインタ、リファレンスのうちの |
2253 |
いずれか一つの型をとります。 |
2254 |
Perl は実際のデータに対して、蓄積されている型から要求されている型へ、 |
2255 |
自動的に変換を行ないます。 |
2256 |
|
2257 |
=begin original |
2258 |
|
2259 |
Some scalar variables contain more than one type of scalar data. For |
2260 |
example, the variable C<$!> contains either the numeric value of C<errno> |
2261 |
or its string equivalent from either C<strerror> or C<sys_errlist[]>. |
2262 |
|
2263 |
=end original |
2264 |
|
2265 |
ある種のスカラ変数は、複数の型のスカラデータを持つようになっています。 |
2266 |
たとえば変数 C<$!> は、C<errno> の数値としての値と、 |
2267 |
C<strerror> や C<sys_errlist[]> から得たのと同値な文字列を持っています。 |
2268 |
|
2269 |
=begin original |
2270 |
|
2271 |
To force multiple data values into an SV, you must do two things: use the |
2272 |
C<sv_set*v> routines to add the additional scalar type, then set a flag |
2273 |
so that Perl will believe it contains more than one type of data. The |
2274 |
four macros to set the flags are: |
2275 |
|
2276 |
=end original |
2277 |
|
2278 |
SV に複数のデータ値を入れるようにするには、二つのことをしなくてはなりません: |
2279 |
スカラ型を別に追加するために C<sv_set*v> ルーチンを使用すること; それから、 |
2280 |
フラグを設定して Perl に複数のデータを持っていることを知らせることです。 |
2281 |
フラグを設定するための四つのマクロは以下のものです: |
2282 |
|
2283 |
SvIOK_on |
2284 |
SvNOK_on |
2285 |
SvPOK_on |
2286 |
SvROK_on |
2287 |
|
2288 |
=begin original |
2289 |
|
2290 |
The particular macro you must use depends on which C<sv_set*v> routine |
2291 |
you called first. This is because every C<sv_set*v> routine turns on |
2292 |
only the bit for the particular type of data being set, and turns off |
2293 |
all the rest. |
2294 |
|
2295 |
=end original |
2296 |
|
2297 |
使用するマクロは、最初にどの C<sv_set*v> ルーチンを呼ぶのかに |
2298 |
関わってきます。 |
2299 |
これは、C<sv_set*v> ルーチンはすべて特定のデータ型のビットだけを |
2300 |
設定して、他をクリアしてしまうからです。 |
2301 |
|
2302 |
=begin original |
2303 |
|
2304 |
For example, to create a new Perl variable called "dberror" that contains |
2305 |
both the numeric and descriptive string error values, you could use the |
2306 |
following code: |
2307 |
|
2308 |
=end original |
2309 |
|
2310 |
たとえば、"dberror" という新しい Perl 変数を作って、エラー値を数値と |
2311 |
メッセージ文字列で持つようにするには、以下のように書きます: |
2312 |
|
2313 |
extern int dberror; |
2314 |
extern char *dberror_list; |
2315 |
|
2316 |
SV* sv = get_sv("dberror", GV_ADD); |
2317 |
sv_setiv(sv, (IV) dberror); |
2318 |
sv_setpv(sv, dberror_list[dberror]); |
2319 |
SvIOK_on(sv); |
2320 |
|
2321 |
=begin original |
2322 |
|
2323 |
If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the |
2324 |
macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>. |
2325 |
|
2326 |
=end original |
2327 |
|
2328 |
C<sv_setiv> と C<sv_setpv> の順序が逆であった場合、C<SvIOK_on> マクロの |
2329 |
代わりに C<SvPOK_on> マクロを呼ばなければなりません。 |
2330 |
|
2331 |
=head2 Read-Only Values |
2332 |
|
2333 |
(読み込み専用値) |
2334 |
|
2335 |
=begin original |
2336 |
|
2337 |
In Perl 5.16 and earlier, copy-on-write (see the next section) shared a |
2338 |
flag bit with read-only scalars. So the only way to test whether |
2339 |
C<sv_setsv>, etc., will raise a "Modification of a read-only value" error |
2340 |
in those versions is: |
2341 |
|
2342 |
=end original |
2343 |
|
2344 |
Perl 5.16 以前では、コピーオンライト (次章参照) は読み込み専用スカラと |
2345 |
フラグビットを共有していました。 |
2346 |
従って、これらのバージョンで C<sv_setsv> などが |
2347 |
"Modification of a read-only value" エラーを発生させるかどうかを |
2348 |
テストする唯一の方法は次のようなものです: |
2349 |
|
2350 |
SvREADONLY(sv) && !SvIsCOW(sv) |
2351 |
|
2352 |
=begin original |
2353 |
|
2354 |
Under Perl 5.18 and later, SvREADONLY only applies to read-only variables, |
2355 |
and, under 5.20, copy-on-write scalars can also be read-only, so the above |
2356 |
check is incorrect. You just want: |
2357 |
|
2358 |
=end original |
2359 |
|
2360 |
Perl 5.18 以降では、SvREADONLY は読み込み専用変数にのみ適用され、 |
2361 |
5.20 では、コピーオンライトスカラもまた読み込み専用なので、 |
2362 |
前述のチェックは正しくありません。 |
2363 |
単に次のようにしてください: |
2364 |
|
2365 |
SvREADONLY(sv) |
2366 |
|
2367 |
=begin original |
2368 |
|
2369 |
If you need to do this check often, define your own macro like this: |
2370 |
|
2371 |
=end original |
2372 |
|
2373 |
これをチェックをしょっちゅう行う必要がある場合、次のようにして |
2374 |
独自のマクロをチェックしてください: |
2375 |
|
2376 |
#if PERL_VERSION >= 18 |
2377 |
# define SvTRULYREADONLY(sv) SvREADONLY(sv) |
2378 |
#else |
2379 |
# define SvTRULYREADONLY(sv) (SvREADONLY(sv) && !SvIsCOW(sv)) |
2380 |
#endif |
2381 |
|
2382 |
=head2 Copy on Write |
2383 |
|
2384 |
(コピーオンライト) |
2385 |
|
2386 |
=begin original |
2387 |
|
2388 |
Perl implements a copy-on-write (COW) mechanism for scalars, in which |
2389 |
string copies are not immediately made when requested, but are deferred |
2390 |
until made necessary by one or the other scalar changing. This is mostly |
2391 |
transparent, but one must take care not to modify string buffers that are |
2392 |
shared by multiple SVs. |
2393 |
|
2394 |
=end original |
2395 |
|
2396 |
Perl は、スカラに関してコピーオンライト (COW) 機構を実装しています; |
2397 |
これは、文字列のコピーは要求されたときにすぐに行うのではなく、 |
2398 |
どちらかのスカラが変更されることによって必要になるまで遅延させます。 |
2399 |
これはほとんど透過ですが、複数の SV で共有されている文字列バッファを |
2400 |
変更しないように注意しなければなりません。 |
2401 |
|
2402 |
=begin original |
2403 |
|
2404 |
You can test whether an SV is using copy-on-write with C<SvIsCOW(sv)>. |
2405 |
|
2406 |
=end original |
2407 |
|
2408 |
ある SV がコピーオンライトを使っているかどうかは C<SvIsCOW(sv)> で |
2409 |
テストできます。 |
2410 |
|
2411 |
=begin original |
2412 |
|
2413 |
You can force an SV to make its own copy of its string buffer by calling C<sv_force_normal(sv)> or SvPV_force_nolen(sv). |
2414 |
|
2415 |
=end original |
2416 |
|
2417 |
C<sv_force_normal(sv)> か SvPV_force_nolen(sv) を呼び出すことで、 |
2418 |
SV が文字列に関して自分自身のコピーを持つように強制できます。 |
2419 |
|
2420 |
=begin original |
2421 |
|
2422 |
If you want to make the SV drop its string buffer, use |
2423 |
C<sv_force_normal_flags(sv, SV_COW_DROP_PV)> or simply |
2424 |
C<sv_setsv(sv, NULL)>. |
2425 |
|
2426 |
=end original |
2427 |
|
2428 |
SV に自分自身の文字列バッファを捨てさせたい場合は、 |
2429 |
C<sv_force_normal_flags(sv, SV_COW_DROP_PV)> か、単に |
2430 |
C<sv_setsv(sv, NULL)> を使います。 |
2431 |
|
2432 |
=begin original |
2433 |
|
2434 |
All of these functions will croak on read-only scalars (see the previous |
2435 |
section for more on those). |
2436 |
|
2437 |
=end original |
2438 |
|
2439 |
これら全ての関数は、読み込み専用スカラに対しては croak します |
2440 |
(これに関する詳細は前の節を参照してください)。 |
2441 |
|
2442 |
=begin original |
2443 |
|
2444 |
To test that your code is behaving correctly and not modifying COW buffers, |
2445 |
on systems that support L<mmap(2)> (i.e., Unix) you can configure perl with |
2446 |
C<-Accflags=-DPERL_DEBUG_READONLY_COW> and it will turn buffer violations |
2447 |
into crashes. You will find it to be marvellously slow, so you may want to |
2448 |
skip perl's own tests. |
2449 |
|
2450 |
=end original |
2451 |
|
2452 |
あなたのコードが正しく振る舞って、COW バッファを変更していないことを |
2453 |
テストするには、 |
2454 |
L<mmap(2)> に対応しているシステム (例えば Unix) では、 |
2455 |
C<-Accflags=-DPERL_DEBUG_READONLY_COW> を有効にした perl を設定すると、 |
2456 |
バッファ違反でクラッシュするようになります。 |
2457 |
これは驚くほど遅いので、perl 自身のテストは飛ばした方が良いでしょう。 |
2458 |
|
2459 |
=head2 Magic Variables |
2460 |
|
2461 |
(マジック変数) |
2462 |
|
2463 |
=begin original |
2464 |
|
2465 |
[This section still under construction. Ignore everything here. Post no |
2466 |
bills. Everything not permitted is forbidden.] |
2467 |
|
2468 |
=end original |
2469 |
|
2470 |
[この節はまだ作成中です。 |
2471 |
ここにある全ては無視してください。 |
2472 |
張り紙禁止。 |
2473 |
許可されていないこと全ては禁止。] |
2474 |
|
2475 |
=begin original |
2476 |
|
2477 |
Any SV may be magical, that is, it has special features that a normal |
2478 |
SV does not have. These features are stored in the SV structure in a |
2479 |
linked list of C<struct magic>'s, typedef'ed to C<MAGIC>. |
2480 |
|
2481 |
=end original |
2482 |
|
2483 |
すべての SV は magical、つまり、通常の SV が持っていないような特殊な |
2484 |
属性を持つようにすることができます。 |
2485 |
これらの属性は C<MAGIC> として typedef されている C<struct magic> の |
2486 |
リンクリストにある SV 構造体に格納されます。 |
2487 |
|
2488 |
struct magic { |
2489 |
MAGIC* mg_moremagic; |
2490 |
MGVTBL* mg_virtual; |
2491 |
U16 mg_private; |
2492 |
char mg_type; |
2493 |
U8 mg_flags; |
2494 |
I32 mg_len; |
2495 |
SV* mg_obj; |
2496 |
char* mg_ptr; |
2497 |
}; |
2498 |
|
2499 |
=begin original |
2500 |
|
2501 |
Note this is current as of patchlevel 0, and could change at any time. |
2502 |
|
2503 |
=end original |
2504 |
|
2505 |
これは、パッチレベル 0 の時点でのものです; 変更される可能性があります。 |
2506 |
|
2507 |
=head2 Assigning Magic |
2508 |
|
2509 |
(マジックの代入) |
2510 |
|
2511 |
=begin original |
2512 |
|
2513 |
Perl adds magic to an SV using the sv_magic function: |
2514 |
|
2515 |
=end original |
2516 |
|
2517 |
Perl は sv_magic 関数を使った SV にマジックを追加します。 |
2518 |
|
2519 |
void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen); |
2520 |
|
2521 |
=begin original |
2522 |
|
2523 |
The C<sv> argument is a pointer to the SV that is to acquire a new magical |
2524 |
feature. |
2525 |
|
2526 |
=end original |
2527 |
|
2528 |
引数 C<sv> は、新たにマジック機能を獲得する SV へのポインタです。 |
2529 |
|
2530 |
=begin original |
2531 |
|
2532 |
If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to |
2533 |
convert C<sv> to type C<SVt_PVMG>. |
2534 |
Perl then continues by adding new magic |
2535 |
to the beginning of the linked list of magical features. Any prior entry |
2536 |
of the same type of magic is deleted. Note that this can be overridden, |
2537 |
and multiple instances of the same type of magic can be associated with an |
2538 |
SV. |
2539 |
|
2540 |
=end original |
2541 |
|
2542 |
C<sv> がまだマジカルでなければ、Perl は C<sv> を C<SVt_PVMG> に |
2543 |
変換するために C<SvUPGRADE> を使います。 |
2544 |
Perl はそれから、マジック機能のリンクリストの先頭にそれを追加します。 |
2545 |
以前に存在していた同じタイプのマジックは削除されます。 |
2546 |
これはオーバーライドすることができ、複数の同じ型のマジックのインスタンスを |
2547 |
一つの SV に結び付けることができるということに注意してください。 |
2548 |
|
2549 |
=begin original |
2550 |
|
2551 |
The C<name> and C<namlen> arguments are used to associate a string with |
2552 |
the magic, typically the name of a variable. C<namlen> is stored in the |
2553 |
C<mg_len> field and if C<name> is non-null then either a C<savepvn> copy of |
2554 |
C<name> or C<name> itself is stored in the C<mg_ptr> field, depending on |
2555 |
whether C<namlen> is greater than zero or equal to zero respectively. As a |
2556 |
special case, if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed |
2557 |
to contain an C<SV*> and is stored as-is with its REFCNT incremented. |
2558 |
|
2559 |
=end original |
2560 |
|
2561 |
引数 C<name> と C<namlen> はある文字列と magic とを結び付けるために |
2562 |
使われます; 典型的には変数の名前です。 |
2563 |
C<namlen> は C<mg_len> フィールドに格納され、C<name> がヌルなら、 |
2564 |
C<namlen> が 0 より大きいか、0 かに依存して、それぞれ |
2565 |
C<name> の C<savepvn> コピーか、C<name> 自身に保管されます。 |
2566 |
特殊な場合として、C<(name && namlen == HEf_SVKEY)> なら |
2567 |
C<name> は C<SV*> を含んでいるものと仮定して REFCNT をインクリメントして |
2568 |
そのままの形で保管されます。 |
2569 |
|
2570 |
=begin original |
2571 |
|
2572 |
The sv_magic function uses C<how> to determine which, if any, predefined |
2573 |
"Magic Virtual Table" should be assigned to the C<mg_virtual> field. |
2574 |
See the L<Magic Virtual Tables> section below. The C<how> argument is also |
2575 |
stored in the C<mg_type> field. The value of |
2576 |
C<how> should be chosen from the set of macros |
2577 |
C<PERL_MAGIC_foo> found in F<perl.h>. Note that before |
2578 |
these macros were added, Perl internals used to directly use character |
2579 |
literals, so you may occasionally come across old code or documentation |
2580 |
referring to 'U' magic rather than C<PERL_MAGIC_uvar> for example. |
2581 |
|
2582 |
=end original |
2583 |
|
2584 |
関数 sv_magic は C<how> を、あらかじめ定義されている |
2585 |
マジック仮想テーブル("Magic Virtual Table") のどれを |
2586 |
C<mg_virtual> フィールドに設定するかを決定するのに使います。 |
2587 |
後述する L<Magic Virtual Tables> の節を参照してください。 |
2588 |
C<how> 引数もまた C<mg_type> フィールドに保管されます。 |
2589 |
C<how> の値は F<perl.h> にある C<PERL_MAGIC_foo> マクロの集合から |
2590 |
選ばれるべきです。 |
2591 |
これらのマクロが追加される前は、Perl の内部では文字リテラルを直接 |
2592 |
使っていたので、古いコードや文書では例えば C<PERL_MAGIC_uvar> の |
2593 |
代わりに 'U' マジックを使っているものに出会うことがあるかもしれません。 |
2594 |
|
2595 |
=begin original |
2596 |
|
2597 |
The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC> |
2598 |
structure. If it is not the same as the C<sv> argument, the reference |
2599 |
count of the C<obj> object is incremented. If it is the same, or if |
2600 |
the C<how> argument is C<PERL_MAGIC_arylen>, or if it is a NULL pointer, |
2601 |
then C<obj> is merely stored, without the reference count being incremented. |
2602 |
|
2603 |
=end original |
2604 |
|
2605 |
引数 C<obj> は C<MAGIC> 構造体の C<mg_obj> フィールドに格納されます。 |
2606 |
これが C<sv> 引数と同じでなかった場合、C<obj> の参照カウントは |
2607 |
インクリメントされます。 |
2608 |
同じであった場合、もしくは引数 C<how> が |
2609 |
C<PERL_MAGIC_arylen> かヌルポインタであった場合には、C<obj> は |
2610 |
参照カウントのインクリメントをさせることなく格納されます。 |
2611 |
|
2612 |
=begin original |
2613 |
|
2614 |
See also C<sv_magicext> in L<perlapi> for a more flexible way to add magic |
2615 |
to an SV. |
2616 |
|
2617 |
=end original |
2618 |
|
2619 |
SV にマジックを追加する、より柔軟な方法については L<perlapi> の |
2620 |
C<sv_magicext> も参照してください。 |
2621 |
|
2622 |
=begin original |
2623 |
|
2624 |
There is also a function to add magic to an C<HV>: |
2625 |
|
2626 |
=end original |
2627 |
|
2628 |
同様に C<HV> にマジックを付加する関数があります。 |
2629 |
|
2630 |
void hv_magic(HV *hv, GV *gv, int how); |
2631 |
|
2632 |
=begin original |
2633 |
|
2634 |
This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>. |
2635 |
|
2636 |
=end original |
2637 |
|
2638 |
これは単純に C<sv_magic> を呼び出し、引数 C<gv> を強制的に C<SV> にします。 |
2639 |
|
2640 |
=begin original |
2641 |
|
2642 |
To remove the magic from an SV, call the function sv_unmagic: |
2643 |
|
2644 |
=end original |
2645 |
|
2646 |
SV からマジックを取り除くには、sv_unmagic という関数を呼び出します。 |
2647 |
|
2648 |
int sv_unmagic(SV *sv, int type); |
2649 |
|
2650 |
=begin original |
2651 |
|
2652 |
The C<type> argument should be equal to the C<how> value when the C<SV> |
2653 |
was initially made magical. |
2654 |
|
2655 |
=end original |
2656 |
|
2657 |
引数 C<type> は、C<SV> が magical にされたときの C<how> の値と同じに |
2658 |
なるようにすべきです。 |
2659 |
|
2660 |
=begin original |
2661 |
|
2662 |
However, note that C<sv_unmagic> removes all magic of a certain C<type> from the |
2663 |
C<SV>. If you want to remove only certain |
2664 |
magic of a C<type> based on the magic |
2665 |
virtual table, use C<sv_unmagicext> instead: |
2666 |
|
2667 |
=end original |
2668 |
|
2669 |
しかし、C<sv_unmagic> は C<SV> から、ある C<type> の全てのマジックを |
2670 |
削除することに注意してください。 |
2671 |
マジック下層テーブルを基に C<type> の特定のマジックのみを削除したい場合は、 |
2672 |
代わりに C<sv_unmagicext> を使ってください: |
2673 |
|
2674 |
int sv_unmagicext(SV *sv, int type, MGVTBL *vtbl); |
2675 |
|
2676 |
=head2 Magic Virtual Tables |
2677 |
|
2678 |
(マジック仮想テーブル) |
2679 |
|
2680 |
=begin original |
2681 |
|
2682 |
The C<mg_virtual> field in the C<MAGIC> structure is a pointer to an |
2683 |
C<MGVTBL>, which is a structure of function pointers and stands for |
2684 |
"Magic Virtual Table" to handle the various operations that might be |
2685 |
applied to that variable. |
2686 |
|
2687 |
=end original |
2688 |
|
2689 |
C<MAGIC> 構造体の C<mg_virtual> フィールドは C<MGVTBL> へのポインタで、 |
2690 |
これは関数ポインタの構造体であり、また対応する変数に対して |
2691 |
適用される可能性のあるさまざまな操作を扱うための |
2692 |
「マジック仮想テーブル」("Magic Virtual Table") を意味しています。 |
2693 |
|
2694 |
=begin original |
2695 |
|
2696 |
The C<MGVTBL> has five (or sometimes eight) pointers to the following |
2697 |
routine types: |
2698 |
|
2699 |
=end original |
2700 |
|
2701 |
C<MGVTBL> は、以下に挙げる 5 種類(あるいは時々 8 種類)の |
2702 |
ポインタを持っています。 |
2703 |
|
2704 |
int (*svt_get)(SV* sv, MAGIC* mg); |
2705 |
int (*svt_set)(SV* sv, MAGIC* mg); |
2706 |
U32 (*svt_len)(SV* sv, MAGIC* mg); |
2707 |
int (*svt_clear)(SV* sv, MAGIC* mg); |
2708 |
int (*svt_free)(SV* sv, MAGIC* mg); |
2709 |
|
2710 |
int (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv, |
2711 |
const char *name, I32 namlen); |
2712 |
int (*svt_dup)(MAGIC *mg, CLONE_PARAMS *param); |
2713 |
int (*svt_local)(SV *nsv, MAGIC *mg); |
2714 |
|
2715 |
=begin original |
2716 |
|
2717 |
This MGVTBL structure is set at compile-time in F<perl.h> and there are |
2718 |
currently 32 types. These different structures contain pointers to various |
2719 |
routines that perform additional actions depending on which function is |
2720 |
being called. |
2721 |
|
2722 |
=end original |
2723 |
|
2724 |
この MGVTBL は F<perl.h> の中でコンパイル時に設定され、現在 32 の型が |
2725 |
あります。 |
2726 |
これらの異なった構造体は、関数が呼び出されたときに依存して追加動作を |
2727 |
行うような様々なルーチンへのポインタを保持しています。 |
2728 |
|
2729 |
=begin original |
2730 |
|
2731 |
Function pointer Action taken |
2732 |
---------------- ------------ |
2733 |
svt_get Do something before the value of the SV is |
2734 |
retrieved. |
2735 |
svt_set Do something after the SV is assigned a value. |
2736 |
svt_len Report on the SV's length. |
2737 |
svt_clear Clear something the SV represents. |
2738 |
svt_free Free any extra storage associated with the SV. |
2739 |
|
2740 |
=end original |
2741 |
|
2742 |
関数ポインタ その振る舞い |
2743 |
---------------- ------------ |
2744 |
svt_get SV の値が取得された前に何かを行う。 |
2745 |
svt_set SV に値を代入した後で何かを行う。 |
2746 |
svt_len SV の長さを報告する。 |
2747 |
svt_clear SV が表わしているものををクリアする。 |
2748 |
svt_free SV に結び付けられてい領域を解放する。 |
2749 |
|
2750 |
=begin original |
2751 |
|
2752 |
svt_copy copy tied variable magic to a tied element |
2753 |
svt_dup duplicate a magic structure during thread cloning |
2754 |
svt_local copy magic to local value during 'local' |
2755 |
|
2756 |
=end original |
2757 |
|
2758 |
svt_copy tie された変数のマジックを tie された要素にコピーする |
2759 |
svt_dup スレッドのクローン化中にマジック構造体を複製する |
2760 |
svt_local 'local' 中にマジックをローカル変数にコピーする |
2761 |
|
2762 |
=begin original |
2763 |
|
2764 |
For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds |
2765 |
to an C<mg_type> of C<PERL_MAGIC_sv>) contains: |
2766 |
|
2767 |
=end original |
2768 |
|
2769 |
たとえば、C<vtbl_sv> (C<PERL_MAGIC_sv> の C<mg_type> に対応します)と |
2770 |
呼ばれる MGVTBL 構造体の内容は以下の様になっています。 |
2771 |
|
2772 |
{ magic_get, magic_set, magic_len, 0, 0 } |
2773 |
|
2774 |
=begin original |
2775 |
|
2776 |
Thus, when an SV is determined to be magical and of type C<PERL_MAGIC_sv>, |
2777 |
if a get operation is being performed, the routine C<magic_get> is |
2778 |
called. All the various routines for the various magical types begin |
2779 |
with C<magic_>. NOTE: the magic routines are not considered part of |
2780 |
the Perl API, and may not be exported by the Perl library. |
2781 |
|
2782 |
=end original |
2783 |
|
2784 |
したがって、ある SV がマジカルであると決定されてその型が |
2785 |
C<PERL_MAGIC_sv> であったとき、操作が実行されたならば、C<magic_get> が |
2786 |
呼び出されます。 |
2787 |
マジカル型に対するルーチンはすべて、C<magic_> で始まります。 |
2788 |
NOTE: マジックルーチンは Perl API の一部として扱われず、 |
2789 |
Perl ライブラリによってエクスポートされません。 |
2790 |
|
2791 |
=begin original |
2792 |
|
2793 |
The last three slots are a recent addition, and for source code |
2794 |
compatibility they are only checked for if one of the three flags |
2795 |
MGf_COPY, MGf_DUP or MGf_LOCAL is set in mg_flags. |
2796 |
This means that most code can continue declaring |
2797 |
a vtable as a 5-element value. These three are |
2798 |
currently used exclusively by the threading code, and are highly subject |
2799 |
to change. |
2800 |
|
2801 |
=end original |
2802 |
|
2803 |
末尾の三つのスロットは最近追加されたもので、ソースコードの互換性のために、 |
2804 |
mg_flags に MGf_COPY, MGf_DUP, MGf_LOCAL のいずれか一つが設定されている |
2805 |
場合にのみチェックされます。 |
2806 |
これは、ほとんどのコードは vtable を 5 要素の値として定義したままで |
2807 |
よいということです。 |
2808 |
これらの三つは現在のところスレッドのコードのみで使われていて、 |
2809 |
変更される可能性が高いです。 |
2810 |
|
2811 |
=begin original |
2812 |
|
2813 |
The current kinds of Magic Virtual Tables are: |
2814 |
|
2815 |
=end original |
2816 |
|
2817 |
現時点でのMagic Virtual Tables の種類は以下の通りです。 |
2818 |
|
2819 |
=for comment |
2820 |
This table is generated by regen/mg_vtable.pl. Any changes made here |
2821 |
will be lost. |
2822 |
|
2823 |
=for mg_vtable.pl begin |
2824 |
|
2825 |
=begin original |
2826 |
|
2827 |
mg_type |
2828 |
(old-style char and macro) MGVTBL Type of magic |
2829 |
-------------------------- ------ ------------- |
2830 |
\0 PERL_MAGIC_sv vtbl_sv Special scalar variable |
2831 |
# PERL_MAGIC_arylen vtbl_arylen Array length ($#ary) |
2832 |
% PERL_MAGIC_rhash (none) extra data for restricted |
2833 |
hashes |
2834 |
& PERL_MAGIC_proto (none) my sub prototype CV |
2835 |
. PERL_MAGIC_pos vtbl_pos pos() lvalue |
2836 |
: PERL_MAGIC_symtab (none) extra data for symbol |
2837 |
tables |
2838 |
< PERL_MAGIC_backref vtbl_backref for weak ref data |
2839 |
@ PERL_MAGIC_arylen_p (none) to move arylen out of XPVAV |
2840 |
B PERL_MAGIC_bm vtbl_regexp Boyer-Moore |
2841 |
(fast string search) |
2842 |
c PERL_MAGIC_overload_table vtbl_ovrld Holds overload table |
2843 |
(AMT) on stash |
2844 |
D PERL_MAGIC_regdata vtbl_regdata Regex match position data |
2845 |
(@+ and @- vars) |
2846 |
d PERL_MAGIC_regdatum vtbl_regdatum Regex match position data |
2847 |
element |
2848 |
E PERL_MAGIC_env vtbl_env %ENV hash |
2849 |
e PERL_MAGIC_envelem vtbl_envelem %ENV hash element |
2850 |
f PERL_MAGIC_fm vtbl_regexp Formline |
2851 |
('compiled' format) |
2852 |
g PERL_MAGIC_regex_global vtbl_mglob m//g target |
2853 |
H PERL_MAGIC_hints vtbl_hints %^H hash |
2854 |
h PERL_MAGIC_hintselem vtbl_hintselem %^H hash element |
2855 |
I PERL_MAGIC_isa vtbl_isa @ISA array |
2856 |
i PERL_MAGIC_isaelem vtbl_isaelem @ISA array element |
2857 |
k PERL_MAGIC_nkeys vtbl_nkeys scalar(keys()) lvalue |
2858 |
L PERL_MAGIC_dbfile (none) Debugger %_<filename |
2859 |
l PERL_MAGIC_dbline vtbl_dbline Debugger %_<filename |
2860 |
element |
2861 |
N PERL_MAGIC_shared (none) Shared between threads |
2862 |
n PERL_MAGIC_shared_scalar (none) Shared between threads |
2863 |
o PERL_MAGIC_collxfrm vtbl_collxfrm Locale transformation |
2864 |
P PERL_MAGIC_tied vtbl_pack Tied array or hash |
2865 |
p PERL_MAGIC_tiedelem vtbl_packelem Tied array or hash element |
2866 |
q PERL_MAGIC_tiedscalar vtbl_packelem Tied scalar or handle |
2867 |
r PERL_MAGIC_qr vtbl_regexp precompiled qr// regex |
2868 |
S PERL_MAGIC_sig (none) %SIG hash |
2869 |
s PERL_MAGIC_sigelem vtbl_sigelem %SIG hash element |
2870 |
t PERL_MAGIC_taint vtbl_taint Taintedness |
2871 |
U PERL_MAGIC_uvar vtbl_uvar Available for use by |
2872 |
extensions |
2873 |
u PERL_MAGIC_uvar_elem (none) Reserved for use by |
2874 |
extensions |
2875 |
V PERL_MAGIC_vstring (none) SV was vstring literal |
2876 |
v PERL_MAGIC_vec vtbl_vec vec() lvalue |
2877 |
w PERL_MAGIC_utf8 vtbl_utf8 Cached UTF-8 information |
2878 |
x PERL_MAGIC_substr vtbl_substr substr() lvalue |
2879 |
y PERL_MAGIC_defelem vtbl_defelem Shadow "foreach" iterator |
2880 |
variable / smart parameter |
2881 |
vivification |
2882 |
] PERL_MAGIC_checkcall vtbl_checkcall inlining/mutation of call |
2883 |
to this CV |
2884 |
~ PERL_MAGIC_ext (none) Available for use by |
2885 |
extensions |
2886 |
|
2887 |
=end original |
2888 |
|
2889 |
mg_type |
2890 |
(old-style char and macro) MGVTBL Type of magic |
2891 |
-------------------------- ------ ------------- |
2892 |
\0 PERL_MAGIC_sv vtbl_sv 特殊スカラ変数 |
2893 |
# PERL_MAGIC_arylen vtbl_arylen 配列の長さ ($#ary) |
2894 |
% PERL_MAGIC_rhash (none) 制限ハッシュの追加データ |
2895 |
& PERL_MAGIC_proto (none) my サブルーチンプロトタイプ CV |
2896 |
. PERL_MAGIC_pos vtbl_pos pos() 左辺値 |
2897 |
: PERL_MAGIC_symtab (none) シンボルテーブルの追加データ |
2898 |
< PERL_MAGIC_backref vtbl_backref 弱いリファレンス用 |
2899 |
@ PERL_MAGIC_arylen_p (none) arylen を XPVAV の外に動かす用 |
2900 |
B PERL_MAGIC_bm vtbl_regexp Boyer-Moore (高速文字列検索) |
2901 |
c PERL_MAGIC_overload_table vtbl_ovrld スタッシュのオーバーロード |
2902 |
テーブル(AMT) を保持 |
2903 |
D PERL_MAGIC_regdata vtbl_regdata 正規表現マッチング位置データ |
2904 |
(@+ と @- の変数) |
2905 |
d PERL_MAGIC_regdatum vtbl_regdatum 正規表現マッチング位置データ |
2906 |
要素 |
2907 |
E PERL_MAGIC_env vtbl_env %ENV ハッシュ |
2908 |
e PERL_MAGIC_envelem vtbl_envelem %ENV ハッシュ要素 |
2909 |
f PERL_MAGIC_fm vtbl_regexp フォーム行(「コンパイル済み」 |
2910 |
フォーマット) |
2911 |
g PERL_MAGIC_regex_global vtbl_mglob m//g のターゲット |
2912 |
H PERL_MAGIC_hints vtbl_hints %^H ハッシュ |
2913 |
h PERL_MAGIC_hintselem vtbl_hintselem %^H ハッシュ要素 |
2914 |
I PERL_MAGIC_isa vtbl_isa @ISA 配列 |
2915 |
i PERL_MAGIC_isaelem vtbl_isaelem @ISA 配列要素 |
2916 |
k PERL_MAGIC_nkeys vtbl_nkeys scalar(keys()) 左辺値 |
2917 |
L PERL_MAGIC_dbfile (none) デバッガの %_<filename |
2918 |
l PERL_MAGIC_dbline vtbl_dbline デバッガの %_<filename 要素 |
2919 |
N PERL_MAGIC_shared (none) スレッド間で共有される |
2920 |
n PERL_MAGIC_shared_scalar (none) スレッド間で共有される |
2921 |
o PERL_MAGIC_collxfrm vtbl_collxfrm ロケール変換 |
2922 |
P PERL_MAGIC_tied vtbl_pack tie された配列やハッシュ |
2923 |
p PERL_MAGIC_tiedelem vtbl_packelem tie された配列やハッシュの要素 |
2924 |
q PERL_MAGIC_tiedscalar vtbl_packelem tie されたスカラやハンドル |
2925 |
r PERL_MAGIC_qr vtbl_regexp 事前コンパイルされた qr// 正規表現 |
2926 |
S PERL_MAGIC_sig (none) %SIG ハッシュ |
2927 |
s PERL_MAGIC_sigelem vtbl_sigelem %SIG ハッシュ要素 |
2928 |
t PERL_MAGIC_taint vtbl_taint 汚染性 |
2929 |
U PERL_MAGIC_uvar vtbl_uvar エクステンションで使用可能 |
2930 |
u PERL_MAGIC_uvar_elem (none) エクステンションが使うために |
2931 |
予約 |
2932 |
V PERL_MAGIC_vstring (none) SV はv-文字列リテラル |
2933 |
v PERL_MAGIC_vec vtbl_vec vec() 左辺値 |
2934 |
w PERL_MAGIC_utf8 vtbl_utf8 キャッシュされた UTF-8 情報 |
2935 |
x PERL_MAGIC_substr vtbl_substr substr() 左辺値 |
2936 |
y PERL_MAGIC_defelem vtbl_defelem 影の "foreach" 反復子 |
2937 |
変数 / スマート引数 |
2938 |
自動有効化 |
2939 |
] PERL_MAGIC_checkcall vtbl_checkcall この CV の呼び出しのインライン化/ |
2940 |
ミューテーション |
2941 |
~ PERL_MAGIC_ext (none) エクステンションで使用可能 |
2942 |
|
2943 |
=for mg_vtable.pl end |
2944 |
|
2945 |
=begin original |
2946 |
|
2947 |
When an uppercase and lowercase letter both exist in the table, then the |
2948 |
uppercase letter is typically used to represent some kind of composite type |
2949 |
(a list or a hash), and the lowercase letter is used to represent an element |
2950 |
of that composite type. Some internals code makes use of this case |
2951 |
relationship. However, 'v' and 'V' (vec and v-string) are in no way related. |
2952 |
|
2953 |
=end original |
2954 |
|
2955 |
テーブル中で大文字小文字の両方が存在していた場合、大文字は典型的には複合型 |
2956 |
(リストもしくはハッシュ)の種類を表わすのに使われ、小文字はその複合型の |
2957 |
要素を表わすのに使われます。 |
2958 |
内部コードにはこの大文字小文字の関係を使っているものもあります。 |
2959 |
しかし、'v' と 'V' (ベクタと v-文字列) は全く関係がありません。 |
2960 |
|
2961 |
=begin original |
2962 |
|
2963 |
The C<PERL_MAGIC_ext> and C<PERL_MAGIC_uvar> magic types are defined |
2964 |
specifically for use by extensions and will not be used by perl itself. |
2965 |
Extensions can use C<PERL_MAGIC_ext> magic to 'attach' private information |
2966 |
to variables (typically objects). This is especially useful because |
2967 |
there is no way for normal perl code to corrupt this private information |
2968 |
(unlike using extra elements of a hash object). |
2969 |
|
2970 |
=end original |
2971 |
|
2972 |
マジック型 C<PERL_MAGIC_ext> と C<PERL_MAGIC_uvar> はエクステンションから |
2973 |
使われ、Perl 自身からは使われないように特別に定義されています。 |
2974 |
エクステンションは C<PERL_MAGIC_ext> マジックを、 |
2975 |
プライベート情報を変数(典型的なオブジェクト)に「アタッチ」(attach) |
2976 |
するために使うことができます。 |
2977 |
これは、通常の perl コードが(ハッシュオブジェクトの要素を使うのとは違って) |
2978 |
そのプライベート情報を壊す恐れがないのでとても便利です。 |
2979 |
|
2980 |
=begin original |
2981 |
|
2982 |
Similarly, C<PERL_MAGIC_uvar> magic can be used much like tie() to call a |
2983 |
C function any time a scalar's value is used or changed. The C<MAGIC>'s |
2984 |
C<mg_ptr> field points to a C<ufuncs> structure: |
2985 |
|
2986 |
=end original |
2987 |
|
2988 |
同様に、C<PERL_MAGIC_uvar> マジックは、スカラの値が使われたり |
2989 |
変更されたりしたときに C 関数を呼び出すという、tie() とよく似た形で使えます。 |
2990 |
C<MAGIC> の C<mg_ptr> フィールドは C<ufuncs> 構造体へのポインタです: |
2991 |
|
2992 |
struct ufuncs { |
2993 |
I32 (*uf_val)(pTHX_ IV, SV*); |
2994 |
I32 (*uf_set)(pTHX_ IV, SV*); |
2995 |
IV uf_index; |
2996 |
}; |
2997 |
|
2998 |
=begin original |
2999 |
|
3000 |
When the SV is read from or written to, the C<uf_val> or C<uf_set> |
3001 |
function will be called with C<uf_index> as the first arg and a pointer to |
3002 |
the SV as the second. A simple example of how to add C<PERL_MAGIC_uvar> |
3003 |
magic is shown below. Note that the ufuncs structure is copied by |
3004 |
sv_magic, so you can safely allocate it on the stack. |
3005 |
|
3006 |
=end original |
3007 |
|
3008 |
SV が読み書きされたとき、C<uf_index> を最初の引数、SV へのポインタを |
3009 |
2 番目の引数として C<uf_val> または C<uf_set> 関数が呼び出されます。 |
3010 |
どのように C<PERL_MAGIC_uvar> マジックを追加するかの簡単な例を以下に示します。 |
3011 |
ufuncs 構造体は sv_magic によってコピーされるので、スタック上に安全に |
3012 |
割り当てられることに注意してください。 |
3013 |
|
3014 |
void |
3015 |
Umagic(sv) |
3016 |
SV *sv; |
3017 |
PREINIT: |
3018 |
struct ufuncs uf; |
3019 |
CODE: |
3020 |
uf.uf_val = &my_get_fn; |
3021 |
uf.uf_set = &my_set_fn; |
3022 |
uf.uf_index = 0; |
3023 |
sv_magic(sv, 0, PERL_MAGIC_uvar, (char*)&uf, sizeof(uf)); |
3024 |
|
3025 |
=begin original |
3026 |
|
3027 |
Attaching C<PERL_MAGIC_uvar> to arrays is permissible but has no effect. |
3028 |
|
3029 |
=end original |
3030 |
|
3031 |
C<PERL_MAGIC_uvar> を配列にアタッチすることは可能ですが、何の意味も |
3032 |
ありません。 |
3033 |
|
3034 |
=begin original |
3035 |
|
3036 |
For hashes there is a specialized hook that gives control over hash |
3037 |
keys (but not values). This hook calls C<PERL_MAGIC_uvar> 'get' magic |
3038 |
if the "set" function in the C<ufuncs> structure is NULL. The hook |
3039 |
is activated whenever the hash is accessed with a key specified as |
3040 |
an C<SV> through the functions C<hv_store_ent>, C<hv_fetch_ent>, |
3041 |
C<hv_delete_ent>, and C<hv_exists_ent>. Accessing the key as a string |
3042 |
through the functions without the C<..._ent> suffix circumvents the |
3043 |
hook. See L<Hash::Util::FieldHash/GUTS> for a detailed description. |
3044 |
|
3045 |
=end original |
3046 |
|
3047 |
ハッシュについては、ハッシュのキー(値ではありません)の制御をするための |
3048 |
専門化されたフックがあります。 |
3049 |
このフックは、C<ufuncs> 構造体の "set" 関数が NULL のとき、 |
3050 |
C<PERL_MAGIC_uvar> 'get' マジックを呼び出します。 |
3051 |
このフックは、C<hv_store_ent>, C<hv_fetch_ent>, C<hv_delete_ent>, |
3052 |
C<hv_exists_ent> 関数を通して C<SV> で指定されたキーでハッシュに |
3053 |
アクセスされたときに有効になります。 |
3054 |
C<..._ent> 接尾辞を持たない関数を等して文字列としてキーにアクセスすると、 |
3055 |
フックを通りません。 |
3056 |
詳細な説明については L<Hash::Util::FieldHash/GUTS> を参照してください。 |
3057 |
|
3058 |
=begin original |
3059 |
|
3060 |
Note that because multiple extensions may be using C<PERL_MAGIC_ext> |
3061 |
or C<PERL_MAGIC_uvar> magic, it is important for extensions to take |
3062 |
extra care to avoid conflict. Typically only using the magic on |
3063 |
objects blessed into the same class as the extension is sufficient. |
3064 |
For C<PERL_MAGIC_ext> magic, it is usually a good idea to define an |
3065 |
C<MGVTBL>, even if all its fields will be C<0>, so that individual |
3066 |
C<MAGIC> pointers can be identified as a particular kind of magic |
3067 |
using their magic virtual table. C<mg_findext> provides an easy way |
3068 |
to do that: |
3069 |
|
3070 |
=end original |
3071 |
|
3072 |
複数のエクステンションが C<PERL_MAGIC_ext> や C<PERL_MAGIC_uvar> マジックを |
3073 |
使う可能性があるので、エクステンションがそれを扱うには気をつけることが |
3074 |
重要であることに注意してください。 |
3075 |
典型的には、これはオブジェクトをエクステンションが扱えるように同じクラスに |
3076 |
bless するときにのみ使います。 |
3077 |
C<PERL_MAGIC_ext> マジックでは、たとえ全てのフィールドが C<0> でも、 |
3078 |
C<MGVTBL> を定義するのが普通はよい考えです; 個々の C<MAGIC> ポインタは |
3079 |
それぞれのマジック仮想テーブルを使ったある種のマジックとして |
3080 |
識別されるからです。 |
3081 |
C<mg_findext> はそうするための簡単な方法を提供します: |
3082 |
|
3083 |
STATIC MGVTBL my_vtbl = { 0, 0, 0, 0, 0, 0, 0, 0 }; |
3084 |
|
3085 |
MAGIC *mg; |
3086 |
if ((mg = mg_findext(sv, PERL_MAGIC_ext, &my_vtbl))) { |
3087 |
/* this is really ours, not another module's PERL_MAGIC_ext */ |
3088 |
my_priv_data_t *priv = (my_priv_data_t *)mg->mg_ptr; |
3089 |
... |
3090 |
} |
3091 |
|
3092 |
=begin original |
3093 |
|
3094 |
Also note that the C<sv_set*()> and C<sv_cat*()> functions described |
3095 |
earlier do B<not> invoke 'set' magic on their targets. This must |
3096 |
be done by the user either by calling the C<SvSETMAGIC()> macro after |
3097 |
calling these functions, or by using one of the C<sv_set*_mg()> or |
3098 |
C<sv_cat*_mg()> functions. Similarly, generic C code must call the |
3099 |
C<SvGETMAGIC()> macro to invoke any 'get' magic if they use an SV |
3100 |
obtained from external sources in functions that don't handle magic. |
3101 |
See L<perlapi> for a description of these functions. |
3102 |
For example, calls to the C<sv_cat*()> functions typically need to be |
3103 |
followed by C<SvSETMAGIC()>, but they don't need a prior C<SvGETMAGIC()> |
3104 |
since their implementation handles 'get' magic. |
3105 |
|
3106 |
=end original |
3107 |
|
3108 |
C<sv_set*()> と C<sv_cat*()> といった関数群はそのターゲットに対して |
3109 |
'set' マジックを B<起動しない> ということにも注意してください。 |
3110 |
これには、ユーザーが C<svSETMAGIC> マクロを呼び出した後でこれらの関数を |
3111 |
呼び出すか、あるいは C<sv_set*_mg()> か |
3112 |
C<sv_cat*_mg()> の何れかの関数を使わなければなりません。 |
3113 |
同様に、一般的な C コードは、それがマジックを扱っていないような関数から |
3114 |
得られたSV を使っているのであれば、'get' マジックを起動するために |
3115 |
C<SvGETMAGIC> を呼び出さなければなりません。 |
3116 |
これらの関数については L<perlapi> を参照してください。 |
3117 |
例えば、C<sv_cat*()> 関数群の呼び出しは通常引き続いて C<SvSETMAGIC()> を |
3118 |
呼び出す必要がありますが、 C<SvGETMAGIC> が先行している必要はありません; |
3119 |
なぜなら、その実装は 'get' マジックを扱うからです。 |
3120 |
|
3121 |
=head2 Finding Magic |
3122 |
|
3123 |
(マジックを見つけだす) |
3124 |
|
3125 |
MAGIC *mg_find(SV *sv, int type); /* Finds the magic pointer of that |
3126 |
* type */ |
3127 |
|
3128 |
=begin original |
3129 |
|
3130 |
This routine returns a pointer to a C<MAGIC> structure stored in the SV. |
3131 |
If the SV does not have that magical |
3132 |
feature, C<NULL> is returned. If the |
3133 |
SV has multiple instances of that magical feature, the first one will be |
3134 |
returned. C<mg_findext> can be used |
3135 |
to find a C<MAGIC> structure of an SV |
3136 |
based on both its magic type and its magic virtual table: |
3137 |
|
3138 |
=end original |
3139 |
|
3140 |
このルーチンは SV に格納されている C<MAGIC> 構造体へのポインタを返します。 |
3141 |
SV がマジカル機能を持っていなければ、C<NULL> が返されます。 |
3142 |
SV にマジカル機能を複数持っている場合、最初の物が返されます。 |
3143 |
C<mg_findext> は、マジック型とマジック仮想表の両方を元とする SV の |
3144 |
C<MAGIC> 構造体を探すのに使えます: |
3145 |
|
3146 |
MAGIC *mg_findext(SV *sv, int type, MGVTBL *vtbl); |
3147 |
|
3148 |
=begin original |
3149 |
|
3150 |
Also, if the SV passed to C<mg_find> or C<mg_findext> is not of type |
3151 |
SVt_PVMG, Perl may core dump. |
3152 |
|
3153 |
=end original |
3154 |
|
3155 |
また、C<mg_find> や C<mg_findext> に渡された SV が Svt_PVMG の型でなければ |
3156 |
Perl はコアダンプするかもしれません。 |
3157 |
|
3158 |
int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen); |
3159 |
|
3160 |
=begin original |
3161 |
|
3162 |
This routine checks to see what types of magic C<sv> has. If the mg_type |
3163 |
field is an uppercase letter, then the mg_obj is copied to C<nsv>, but |
3164 |
the mg_type field is changed to be the lowercase letter. |
3165 |
|
3166 |
=end original |
3167 |
|
3168 |
このルーチンは C<sv> が持っているマジックの型を検査します。 |
3169 |
mg_type フィールドが大文字であれば、mg_obj が C<nsv> にコピーされますが、 |
3170 |
mg_type フィールドは小文字に変更されます。 |
3171 |
|
3172 |
=head2 Understanding the Magic of Tied Hashes and Arrays |
3173 |
|
3174 |
(tie されたハッシュと配列のマジックを理解する) |
3175 |
|
3176 |
=begin original |
3177 |
|
3178 |
Tied hashes and arrays are magical beasts of the C<PERL_MAGIC_tied> |
3179 |
magic type. |
3180 |
|
3181 |
=end original |
3182 |
|
3183 |
tie されたハッシュと配列は C<PERL_MAGIC_tied> マジック型の magical beast です。 |
3184 |
|
3185 |
=begin original |
3186 |
|
3187 |
WARNING: As of the 5.004 release, proper usage of the array and hash |
3188 |
access functions requires understanding a few caveats. Some |
3189 |
of these caveats are actually considered bugs in the API, to be fixed |
3190 |
in later releases, and are bracketed with [MAYCHANGE] below. If |
3191 |
you find yourself actually applying such information in this section, be |
3192 |
aware that the behavior may change in the future, umm, without warning. |
3193 |
|
3194 |
=end original |
3195 |
|
3196 |
警告: リリース 5.004 以降、配列やハッシュに対するアクセス関数の正しい使い方は、 |
3197 |
幾つかの注意点を理解していることを要求しています。 |
3198 |
これら幾つかの注意点は実際には API におけるバグとして |
3199 |
みなされるものであって、将来のリリースにおいては修正されます; |
3200 |
また、注意点は [MAYCHANGE] というブラケットで囲まれています。 |
3201 |
このセクションにある情報をあなたが実際に使おうというのであれば、 |
3202 |
将来それらは警告なしに変わる可能性があることに注意してください。 |
3203 |
|
3204 |
=begin original |
3205 |
|
3206 |
The perl tie function associates a variable with an object that implements |
3207 |
the various GET, SET, etc methods. To perform the equivalent of the perl |
3208 |
tie function from an XSUB, you must mimic this behaviour. The code below |
3209 |
carries out the necessary steps - firstly it creates a new hash, and then |
3210 |
creates a second hash which it blesses into the class which will implement |
3211 |
the tie methods. Lastly it ties the two hashes together, and returns a |
3212 |
reference to the new tied hash. Note that the code below does NOT call the |
3213 |
TIEHASH method in the MyTie class - |
3214 |
see L<Calling Perl Routines from within C Programs> for details on how |
3215 |
to do this. |
3216 |
|
3217 |
=end original |
3218 |
|
3219 |
perl の tie 関数は、ある変数と GET、SET 等といった様々なメソッドを |
3220 |
実装しているオブジェクトとを結び付けるものです。 |
3221 |
XSUB から perl の tie 関数と等価な働きをさせるには、ちょっとした |
3222 |
オマジナイをしなければなりません。 |
3223 |
以下の例が必要なステップです - まず最初にハッシュを作り、それから |
3224 |
tie メソッドを実装するクラスに bless した二番目のハッシュを作ります。 |
3225 |
最後に二つのハッシュを tie し、新たに生成した tie されたハッシュに対する |
3226 |
リファレンスを返します。 |
3227 |
以下の例では MyTie クラスの中で TIEHASH を呼び出していないということに |
3228 |
注意してください - この件に関する詳細は |
3229 |
L<Calling Perl Routines from within C Programs> を参照してください。 |
3230 |
|
3231 |
SV* |
3232 |
mytie() |
3233 |
PREINIT: |
3234 |
HV *hash; |
3235 |
HV *stash; |
3236 |
SV *tie; |
3237 |
CODE: |
3238 |
hash = newHV(); |
3239 |
tie = newRV_noinc((SV*)newHV()); |
3240 |
stash = gv_stashpv("MyTie", GV_ADD); |
3241 |
sv_bless(tie, stash); |
3242 |
hv_magic(hash, (GV*)tie, PERL_MAGIC_tied); |
3243 |
RETVAL = newRV_noinc(hash); |
3244 |
OUTPUT: |
3245 |
RETVAL |
3246 |
|
3247 |
=begin original |
3248 |
|
3249 |
The C<av_store> function, when given a tied array argument, merely |
3250 |
copies the magic of the array onto the value to be "stored", using |
3251 |
C<mg_copy>. It may also return NULL, indicating that the value did not |
3252 |
actually need to be stored in the array. [MAYCHANGE] After a call to |
3253 |
C<av_store> on a tied array, the caller will usually need to call |
3254 |
C<mg_set(val)> to actually invoke the perl level "STORE" method on the |
3255 |
TIEARRAY object. If C<av_store> did return NULL, a call to |
3256 |
C<SvREFCNT_dec(val)> will also be usually necessary to avoid a memory |
3257 |
leak. [/MAYCHANGE] |
3258 |
|
3259 |
=end original |
3260 |
|
3261 |
tie された配列を引数に与えられたときの C<av_store> 関数は、単に配列の |
3262 |
magic を C<mg_copy> を使って「保管」されるように値をコピーするだけです。 |
3263 |
この関数は、その値が実際には配列に格納する必要のないものであることを |
3264 |
示す NULL を返す可能性があります。 |
3265 |
[MAYCHANGE] |
3266 |
tie された配列に対して C<av_store> を呼び出した後、呼び出し側は TIEARRAY |
3267 |
オブジェクトに対して Perl レベルの "STORE" メソッドを起動するために |
3268 |
C<av_store> を呼び出すことが通常は必要となります。 |
3269 |
C<av_store> が NULL を返したならば、メモリリークを防ぐために |
3270 |
C<SvREFCNT_dec(val)> を呼び出すことが必要となります。 |
3271 |
[/MAYCHANGE] |
3272 |
|
3273 |
=begin original |
3274 |
|
3275 |
The previous paragraph is applicable verbatim to tied hash access using the |
3276 |
C<hv_store> and C<hv_store_ent> functions as well. |
3277 |
|
3278 |
=end original |
3279 |
|
3280 |
先の段落の説明は、tie されたハッシュにアクセスするのに使用する |
3281 |
C<hv_store> と C<hv_store_ent> についても同様です。 |
3282 |
|
3283 |
=begin original |
3284 |
|
3285 |
C<av_fetch> and the corresponding hash functions C<hv_fetch> and |
3286 |
C<hv_fetch_ent> actually return an undefined mortal value whose magic |
3287 |
has been initialized using C<mg_copy>. Note the value so returned does not |
3288 |
need to be deallocated, as it is already mortal. [MAYCHANGE] But you will |
3289 |
need to call C<mg_get()> on the returned value in order to actually invoke |
3290 |
the perl level "FETCH" method on the underlying TIE object. Similarly, |
3291 |
you may also call C<mg_set()> on the return value after possibly assigning |
3292 |
a suitable value to it using C<sv_setsv>, which will invoke the "STORE" |
3293 |
method on the TIE object. [/MAYCHANGE] |
3294 |
|
3295 |
=end original |
3296 |
|
3297 |
C<av_fetch> と、対応するハッシュ関数 C<hv_fetch> および C<hv_fetch_ent> は |
3298 |
実際には C<mg_copy> を使って初期化が行なわれている未定義の揮発値を返します。 |
3299 |
返された値はすでに揮発性なので、解放する必要がないことに注意してください。 |
3300 |
[MAYCHANGE] |
3301 |
しかし、TIE オブジェクトに対応した perl レベルの "FETCH" メソッドを |
3302 |
実行するには、返されたその値に対してC<mg_get()> を呼び出す必要があるでしょう。 |
3303 |
同様に、TIE オブジェクトに対する "STORE" メソッドの起動である |
3304 |
C<sv_setsv> を使って適切な値を代入した後で、返された値に対して |
3305 |
C<mg_set()> を呼び出すことができます。 |
3306 |
[/MAYCHANGE] |
3307 |
|
3308 |
=begin original |
3309 |
|
3310 |
[MAYCHANGE] |
3311 |
In other words, the array or hash fetch/store functions don't really |
3312 |
fetch and store actual values in the case of tied arrays and hashes. They |
3313 |
merely call C<mg_copy> to attach magic to the values that were meant to be |
3314 |
"stored" or "fetched". Later calls to C<mg_get> and C<mg_set> actually |
3315 |
do the job of invoking the TIE methods on the underlying objects. Thus |
3316 |
the magic mechanism currently implements a kind of lazy access to arrays |
3317 |
and hashes. |
3318 |
|
3319 |
=end original |
3320 |
|
3321 |
[MAYCHANGE] |
3322 |
言い換えれば、配列やハッシュをフェッチしたりストアする関数は、 |
3323 |
tie されている配列やハッシュに対する場合には実際に値をフェッチしたり |
3324 |
保管したりするわけではないということです。 |
3325 |
それらの関数は「保管」されたり「フェッチ」された値に対してマジックを |
3326 |
付加するために、単に C<mg_copy> を呼び出すだけです。 |
3327 |
その後の C<mg_get> と C<mg_set> の呼び出しは実際には元となっている |
3328 |
オブジェクトへの TIE メソッドの起動を行います。 |
3329 |
従って現在の所マジック機構は配列とハッシュへの一種の遅延アクセスを |
3330 |
実装しています。 |
3331 |
|
3332 |
=begin original |
3333 |
|
3334 |
Currently (as of perl version 5.004), use of the hash and array access |
3335 |
functions requires the user to be aware of whether they are operating on |
3336 |
"normal" hashes and arrays, or on their tied variants. The API may be |
3337 |
changed to provide more transparent access to both tied and normal data |
3338 |
types in future versions. |
3339 |
[/MAYCHANGE] |
3340 |
|
3341 |
=end original |
3342 |
|
3343 |
現在(バージョン 5.004)、ハッシュや配列に対するアクセス関数を使用する |
3344 |
際には、ユーザーが「通常の」ハッシュや配列なのか、あるいはそれが |
3345 |
tie されたものであるのかを気をつけることが要求されています。 |
3346 |
将来のバージョンでは、この API は tie されたデータに対するアクセスと |
3347 |
通常のデータに対するアクセスをより透過的にするために変更されるかも |
3348 |
しれません。 |
3349 |
[/MAYCHANGE] |
3350 |
|
3351 |
=begin original |
3352 |
|
3353 |
You would do well to understand that the TIEARRAY and TIEHASH interfaces |
3354 |
are mere sugar to invoke some perl method calls while using the uniform hash |
3355 |
and array syntax. The use of this sugar imposes some overhead (typically |
3356 |
about two to four extra opcodes per FETCH/STORE operation, in addition to |
3357 |
the creation of all the mortal variables required to invoke the methods). |
3358 |
This overhead will be comparatively small if the TIE methods are themselves |
3359 |
substantial, but if they are only a few statements long, the overhead |
3360 |
will not be insignificant. |
3361 |
|
3362 |
=end original |
3363 |
|
3364 |
TIEARRAY や TIEHASH といったインターフェースが、統一的な |
3365 |
ハッシュ/配列構文を使うための perl メソッドを起動をするための単なる |
3366 |
砂糖であることを良く理解したことでしょう。 |
3367 |
これらの砂糖の使用はいくらかのオーバーヘッド(通常、FETCH/STORE 操作 |
3368 |
当たり二つから四つの余分なオペコード、それに加えてメソッドを |
3369 |
起動するために必要なすべての揮発性変数の生成)を招きます。 |
3370 |
このオーバーヘッドは TIE メソッド自身がしっかりしたものであれば、ほぼ |
3371 |
同等なくらい小さなものでしかありませんが、ほんの少し文が長いだけでも |
3372 |
オーバーヘッドは無視できないものになります。 |
3373 |
|
3374 |
=head2 Localizing changes |
3375 |
|
3376 |
(変更をローカル化する) |
3377 |
|
3378 |
=begin original |
3379 |
|
3380 |
Perl has a very handy construction |
3381 |
|
3382 |
=end original |
3383 |
|
3384 |
Perl には非常に便利な構造があります。 |
3385 |
|
3386 |
{ |
3387 |
local $var = 2; |
3388 |
... |
3389 |
} |
3390 |
|
3391 |
=begin original |
3392 |
|
3393 |
This construction is I<approximately> equivalent to |
3394 |
|
3395 |
=end original |
3396 |
|
3397 |
この構造は以下のものと I<ほぼ> 同じです |
3398 |
|
3399 |
{ |
3400 |
my $oldvar = $var; |
3401 |
$var = 2; |
3402 |
... |
3403 |
$var = $oldvar; |
3404 |
} |
3405 |
|
3406 |
=begin original |
3407 |
|
3408 |
The biggest difference is that the first construction would |
3409 |
reinstate the initial value of $var, irrespective of how control exits |
3410 |
the block: C<goto>, C<return>, C<die>/C<eval>, etc. It is a little bit |
3411 |
more efficient as well. |
3412 |
|
3413 |
=end original |
3414 |
|
3415 |
両者の最も大きな違いは、最初のものが C<goto>、C<return>、C<die>/C<eval> など |
3416 |
どのようにブロックから脱出しようとも、$var の元々の値を |
3417 |
復帰するということです。 |
3418 |
効率といった面では大きな違いはありません。 |
3419 |
|
3420 |
=begin original |
3421 |
|
3422 |
There is a way to achieve a similar task from C via Perl API: create a |
3423 |
I<pseudo-block>, and arrange for some changes to be automatically |
3424 |
undone at the end of it, either explicit, or via a non-local exit (via |
3425 |
die()). A I<block>-like construct is created by a pair of |
3426 |
C<ENTER>/C<LEAVE> macros (see L<perlcall/"Returning a Scalar">). |
3427 |
Such a construct may be created specially for some important localized |
3428 |
task, or an existing one (like boundaries of enclosing Perl |
3429 |
subroutine/block, or an existing pair for freeing TMPs) may be |
3430 |
used. (In the second case the overhead of additional localization must |
3431 |
be almost negligible.) Note that any XSUB is automatically enclosed in |
3432 |
an C<ENTER>/C<LEAVE> pair. |
3433 |
|
3434 |
=end original |
3435 |
|
3436 |
Perl API を通して C から同様の処理を行う方法もあります: |
3437 |
I<擬似ブロック>(pseudo-block)を生成し、そのブロックの最後で自動的に |
3438 |
復帰するような幾つかの変更を行います。 |
3439 |
ブロックから抜けるのは、明示的に抜けるための指示があっても良いし、 |
3440 |
非局所的な脱出(die() を使ったもの)でもかまいません。 |
3441 |
ブロックに似たこの構造は C<ENTER>/C<LEAVE> マクロのペアによって |
3442 |
生成されます(L<perlcall/"Returning a Scalar"> を参照してください)。 |
3443 |
このような構造ではなにか重要なローカル化されたタスクのための特別なものを |
3444 |
作成したり、あるいは既に存在しているもの(Perl のサブルーチン/ブロックに |
3445 |
束縛されたものとか、あるいは解放する一時変数のペア)を使うことも可能です |
3446 |
(二番目のケースでは、ローカル化するためのオーバーヘッドはほとんど |
3447 |
無視できるものです)。 |
3448 |
すべての XSUB は自動的に C<ENTER>/C<LEAVE> の |
3449 |
ペアによって囲まれているということに注意してください。 |
3450 |
|
3451 |
=begin original |
3452 |
|
3453 |
Inside such a I<pseudo-block> the following service is available: |
3454 |
|
3455 |
=end original |
3456 |
|
3457 |
このような I<擬似ブロック> の中では以下のサービスが利用可能です: |
3458 |
|
3459 |
=over 4 |
3460 |
|
3461 |
=item C<SAVEINT(int i)> |
3462 |
|
3463 |
=item C<SAVEIV(IV i)> |
3464 |
|
3465 |
=item C<SAVEI32(I32 i)> |
3466 |
|
3467 |
=item C<SAVELONG(long i)> |
3468 |
|
3469 |
=begin original |
3470 |
|
3471 |
These macros arrange things to restore the value of integer variable |
3472 |
C<i> at the end of enclosing I<pseudo-block>. |
3473 |
|
3474 |
=end original |
3475 |
|
3476 |
これらのマクロはそれを囲む I<擬似ブロック> において |
3477 |
整数変数 C<i> の値をリストアするようにします。 |
3478 |
|
3479 |
=item C<SAVESPTR(s)> |
3480 |
|
3481 |
=item C<SAVEPPTR(p)> |
3482 |
|
3483 |
=begin original |
3484 |
|
3485 |
These macros arrange things to restore the value of pointers C<s> and |
3486 |
C<p>. C<s> must be a pointer of a type which survives conversion to |
3487 |
C<SV*> and back, C<p> should be able to survive conversion to C<char*> |
3488 |
and back. |
3489 |
|
3490 |
=end original |
3491 |
|
3492 |
これらのマクロは、ポインタC<s>もしくは C<p> の値をリストアします。 |
3493 |
C<s> は C<SV*> に対する型変換をできるポインタでなければなりません; |
3494 |
C<p> は C<char*> への型変換が可能であるべきものです。 |
3495 |
|
3496 |
=item C<SAVEFREESV(SV *sv)> |
3497 |
|
3498 |
=begin original |
3499 |
|
3500 |
The refcount of C<sv> would be decremented at the end of |
3501 |
I<pseudo-block>. This is similar to C<sv_2mortal> in that it is also a |
3502 |
mechanism for doing a delayed C<SvREFCNT_dec>. However, while C<sv_2mortal> |
3503 |
extends the lifetime of C<sv> until the beginning of the next statement, |
3504 |
C<SAVEFREESV> extends it until the end of the enclosing scope. These |
3505 |
lifetimes can be wildly different. |
3506 |
|
3507 |
=end original |
3508 |
|
3509 |
I<擬似ブロック> の終端において C<sv> の参照カウントはデクリメントされます。 |
3510 |
これは、遅延した C<SvREFCNT_dec> を行うための機構という意味で |
3511 |
C<sv_2motral> に似たものです。 |
3512 |
しかし、C<sv_2mortal> は C<sv> の生存時間を次の文の始めまで延ばす一方、 |
3513 |
C<SAVEFREESV> は囲まれているスコープの終わりまで延ばします。 |
3514 |
これらの生存時間は大きく異なるかもしれません。 |
3515 |
|
3516 |
=begin original |
3517 |
|
3518 |
Also compare C<SAVEMORTALIZESV>. |
3519 |
|
3520 |
=end original |
3521 |
|
3522 |
また、C<SAVEMORTALIZESV> を比較します。 |
3523 |
|
3524 |
=item C<SAVEMORTALIZESV(SV *sv)> |
3525 |
|
3526 |
=begin original |
3527 |
|
3528 |
Just like C<SAVEFREESV>, but mortalizes C<sv> at the end of the current |
3529 |
scope instead of decrementing its reference count. This usually has the |
3530 |
effect of keeping C<sv> alive until the statement that called the currently |
3531 |
live scope has finished executing. |
3532 |
|
3533 |
=end original |
3534 |
|
3535 |
C<SAVEFREESV> と同様ですが、参照カウントを減らすのではなく、現在のスコープの |
3536 |
終わりで C<sv> を揮発化します。 |
3537 |
これは普通、現在有効なスコープが実行を終了する文まで C<sv> を |
3538 |
生存させ続けます。 |
3539 |
|
3540 |
=item C<SAVEFREEOP(OP *op)> |
3541 |
|
3542 |
=begin original |
3543 |
|
3544 |
The C<OP *> is op_free()ed at the end of I<pseudo-block>. |
3545 |
|
3546 |
=end original |
3547 |
|
3548 |
C<OP *> は I<擬似ブロック> の終端において op_free() されます。 |
3549 |
|
3550 |
=item C<SAVEFREEPV(p)> |
3551 |
|
3552 |
=begin original |
3553 |
|
3554 |
The chunk of memory which is pointed to by C<p> is Safefree()ed at the |
3555 |
end of I<pseudo-block>. |
3556 |
|
3557 |
=end original |
3558 |
|
3559 |
C<p> によって指し示されているメモリの塊は I<擬似ブロック> の終端で |
3560 |
Safefree() されます。 |
3561 |
|
3562 |
=item C<SAVECLEARSV(SV *sv)> |
3563 |
|
3564 |
=begin original |
3565 |
|
3566 |
Clears a slot in the current scratchpad which corresponds to C<sv> at |
3567 |
the end of I<pseudo-block>. |
3568 |
|
3569 |
=end original |
3570 |
|
3571 |
B<擬似ブロック> の終端において、C<sv> に対応している |
3572 |
カレントのスクラッチパッドにおけるスロットをクリアします。 |
3573 |
|
3574 |
=item C<SAVEDELETE(HV *hv, char *key, I32 length)> |
3575 |
|
3576 |
=begin original |
3577 |
|
3578 |
The key C<key> of C<hv> is deleted at the end of I<pseudo-block>. The |
3579 |
string pointed to by C<key> is Safefree()ed. If one has a I<key> in |
3580 |
short-lived storage, the corresponding string may be reallocated like |
3581 |
this: |
3582 |
|
3583 |
=end original |
3584 |
|
3585 |
I<擬似ブロック> の終端で C<hv> にあるキー C<key> は削除されます。 |
3586 |
C<key> によって指し示されている文字列は Safefree() されます。 |
3587 |
short-lived storageにある I<key> を持っているものがあった場合には |
3588 |
以下のようにして対応する文字列が再割り当てされます。 |
3589 |
|
3590 |
SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf)); |
3591 |
|
3592 |
=item C<SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)> |
3593 |
|
3594 |
=begin original |
3595 |
|
3596 |
At the end of I<pseudo-block> the function C<f> is called with the |
3597 |
only argument C<p>. |
3598 |
|
3599 |
=end original |
3600 |
|
3601 |
I<擬似ブロック> の終端において関数 C<f> が呼び出されます; |
3602 |
この関数 C<f> は C<p> のみを引数に取ります。 |
3603 |
|
3604 |
=item C<SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)> |
3605 |
|
3606 |
=begin original |
3607 |
|
3608 |
At the end of I<pseudo-block> the function C<f> is called with the |
3609 |
implicit context argument (if any), and C<p>. |
3610 |
|
3611 |
=end original |
3612 |
|
3613 |
I<疑似ブロック> の最後に、関数 C<f> が(もしあれば)暗黙のコンテキスト |
3614 |
引数と C<p> で呼び出されます。 |
3615 |
|
3616 |
=item C<SAVESTACK_POS()> |
3617 |
|
3618 |
=begin original |
3619 |
|
3620 |
The current offset on the Perl internal stack (cf. C<SP>) is restored |
3621 |
at the end of I<pseudo-block>. |
3622 |
|
3623 |
=end original |
3624 |
|
3625 |
I<擬似ブロック> の終端において Perl の内部スタック(C<SP>)のカレント |
3626 |
オフセットがリストアされます。 |
3627 |
|
3628 |
=back |
3629 |
|
3630 |
=begin original |
3631 |
|
3632 |
The following API list contains functions, thus one needs to |
3633 |
provide pointers to the modifiable data explicitly (either C pointers, |
3634 |
or Perlish C<GV *>s). Where the above macros take C<int>, a similar |
3635 |
function takes C<int *>. |
3636 |
|
3637 |
=end original |
3638 |
|
3639 |
以下の API リストは、変更可能なデータを指し示すポインタ |
3640 |
(C のポインタか、Perl 的な C<GV *> のいずれか)を必要とする関数群です。 |
3641 |
前述の C<int> を引数に取るマクロに似て、 |
3642 |
C<int *> を引数に取る関数があります。 |
3643 |
|
3644 |
=over 4 |
3645 |
|
3646 |
=item C<SV* save_scalar(GV *gv)> |
3647 |
|
3648 |
=begin original |
3649 |
|
3650 |
Equivalent to Perl code C<local $gv>. |
3651 |
|
3652 |
=end original |
3653 |
|
3654 |
Perl コード C<local $gv> と等価です。 |
3655 |
|
3656 |
=item C<AV* save_ary(GV *gv)> |
3657 |
|
3658 |
=item C<HV* save_hash(GV *gv)> |
3659 |
|
3660 |
=begin original |
3661 |
|
3662 |
Similar to C<save_scalar>, but localize C<@gv> and C<%gv>. |
3663 |
|
3664 |
=end original |
3665 |
|
3666 |
C<save_scalar> に似ていますが、C<@gv> と C<%gv> の局所化を行います。 |
3667 |
|
3668 |
=item C<void save_item(SV *item)> |
3669 |
|
3670 |
=begin original |
3671 |
|
3672 |
Duplicates the current value of C<SV>, on the exit from the current |
3673 |
C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV> |
3674 |
using the stored value. It doesn't handle magic. Use C<save_scalar> if |
3675 |
magic is affected. |
3676 |
|
3677 |
=end original |
3678 |
|
3679 |
C<SV> のカレントの値を複製し、カレントの C<ENTER>/C<LEAVE> |
3680 |
B<擬似ブロック> を抜けるときに C<SV> の保存した値を復帰します。 |
3681 |
マジックを扱いません。 |
3682 |
マジックを有効にしたい場合は C<save_scalar> を使ってください。 |
3683 |
|
3684 |
=item C<void save_list(SV **sarg, I32 maxsarg)> |
3685 |
|
3686 |
=begin original |
3687 |
|
3688 |
A variant of C<save_item> which takes multiple arguments via an array |
3689 |
C<sarg> of C<SV*> of length C<maxsarg>. |
3690 |
|
3691 |
=end original |
3692 |
|
3693 |
複数の引数を長さ C<maxarg> の C<SV*> の配列 C<sarg> として取る |
3694 |
C<save_item> の複数の値を取るバリエーションです。 |
3695 |
|
3696 |
=item C<SV* save_svref(SV **sptr)> |
3697 |
|
3698 |
=begin original |
3699 |
|
3700 |
Similar to C<save_scalar>, but will reinstate an C<SV *>. |
3701 |
|
3702 |
=end original |
3703 |
|
3704 |
C<save_scalar> に似ていますが、C<SV *> の復帰を行います。 |
3705 |
|
3706 |
=item C<void save_aptr(AV **aptr)> |
3707 |
|
3708 |
=item C<void save_hptr(HV **hptr)> |
3709 |
|
3710 |
=begin original |
3711 |
|
3712 |
Similar to C<save_svref>, but localize C<AV *> and C<HV *>. |
3713 |
|
3714 |
=end original |
3715 |
|
3716 |
C<save_svref> に似ていますが、C<AV *> と C<HV *> のローカル化を行います。 |
3717 |
|
3718 |
=back |
3719 |
|
3720 |
=begin original |
3721 |
|
3722 |
The C<Alias> module implements localization of the basic types within the |
3723 |
I<caller's scope>. People who are interested in how to localize things in |
3724 |
the containing scope should take a look there too. |
3725 |
|
3726 |
=end original |
3727 |
|
3728 |
C<Alias> モジュールは B<呼び出し側のスコープ> 中での基本型のローカル化を |
3729 |
実装します。 |
3730 |
スコープを持った何かのローカル化に興味のある人は |
3731 |
そこに何があるかも見ておいた方が良いでしょう。 |
3732 |
|
3733 |
=head1 Subroutines |
3734 |
|
3735 |
(サブルーチン) |
3736 |
|
3737 |
=head2 XSUBs and the Argument Stack |
3738 |
|
3739 |
(XSUB と引数スタック) |
3740 |
|
3741 |
=begin original |
3742 |
|
3743 |
The XSUB mechanism is a simple way for Perl programs to access C subroutines. |
3744 |
An XSUB routine will have a stack that contains the arguments from the Perl |
3745 |
program, and a way to map from the Perl data structures to a C equivalent. |
3746 |
|
3747 |
=end original |
3748 |
|
3749 |
XSUB の仕組みは、Perl プログラムが C のサブルーチンを |
3750 |
アクセスするための単純な方法です。 |
3751 |
XSUB には、Perl プログラムからの引数を入れるスタックと、Perl のデータ |
3752 |
構造を C の等価なものにマッピングする方法を用意しています。 |
3753 |
|
3754 |
=begin original |
3755 |
|
3756 |
The stack arguments are accessible through the C<ST(n)> macro, which returns |
3757 |
the C<n>'th stack argument. Argument 0 is the first argument passed in the |
3758 |
Perl subroutine call. These arguments are C<SV*>, and can be used anywhere |
3759 |
an C<SV*> is used. |
3760 |
|
3761 |
=end original |
3762 |
|
3763 |
スタック引数は C<ST(n)> というマクロを使ってアクセスできます; |
3764 |
これは、C<n> 番目のスタック引数を返すものです。 |
3765 |
引数 0 は、Perl のサブルーチン呼び出しで渡された最初の引数です。 |
3766 |
これらの引数は C<SV*> で、C<SV*> が使われるところであればどこでも |
3767 |
使うことができます。 |
3768 |
|
3769 |
=begin original |
3770 |
|
3771 |
Most of the time, output from the C routine can be handled through use of |
3772 |
the RETVAL and OUTPUT directives. However, there are some cases where the |
3773 |
argument stack is not already long enough to handle all the return values. |
3774 |
An example is the POSIX tzname() call, which takes no arguments, but returns |
3775 |
two, the local time zone's standard and summer time abbreviations. |
3776 |
|
3777 |
=end original |
3778 |
|
3779 |
ほとんどの場合には、C ルーチンからの出力は RETVAL 指示子と |
3780 |
OUTPUT 指示子を使って扱うことができます。 |
3781 |
しかし、引数スタックのスペースがすべての返却値を扱うのに十分で |
3782 |
なくなる場合があります。 |
3783 |
例としては、引数をとらないでローカルなタイムゾーンと夏時間の省略形の |
3784 |
二つの返却値を返す、POSIX の tzname() の呼び出しがあります。 |
3785 |
|
3786 |
=begin original |
3787 |
|
3788 |
To handle this situation, the PPCODE directive is used and the stack is |
3789 |
extended using the macro: |
3790 |
|
3791 |
=end original |
3792 |
|
3793 |
このような状況を扱うためには、PPCODE ディレクティブを使い、さらに |
3794 |
スタックを以下のマクロを使って拡張します: |
3795 |
|
3796 |
EXTEND(SP, num); |
3797 |
|
3798 |
=begin original |
3799 |
|
3800 |
where C<SP> is the macro that represents the local copy of the stack pointer, |
3801 |
and C<num> is the number of elements the stack should be extended by. |
3802 |
|
3803 |
=end original |
3804 |
|
3805 |
ここで C<SP> はスタックポインタで、C<num> はスタックを拡張すべき |
3806 |
要素の数です。 |
3807 |
|
3808 |
=begin original |
3809 |
|
3810 |
Now that there is room on the stack, values can be pushed on it using C<PUSHs> |
3811 |
macro. The pushed values will often need to be "mortal" (See |
3812 |
L</Reference Counts and Mortality>): |
3813 |
|
3814 |
=end original |
3815 |
|
3816 |
スタック上に場所を確保したら、C<PUSHs> マクロを使って値をスタックへ |
3817 |
プッシュします。 |
3818 |
プッシュされた値はしばしば「揮発性」である必要があります( |
3819 |
L</Reference Counts and Mortality> を参照してください): |
3820 |
|
3821 |
PUSHs(sv_2mortal(newSViv(an_integer))) |
3822 |
PUSHs(sv_2mortal(newSVuv(an_unsigned_integer))) |
3823 |
PUSHs(sv_2mortal(newSVnv(a_double))) |
3824 |
PUSHs(sv_2mortal(newSVpv("Some String",0))) |
3825 |
/* Although the last example is better written as the more |
3826 |
* efficient: */ |
3827 |
PUSHs(newSVpvs_flags("Some String", SVs_TEMP)) |
3828 |
|
3829 |
=begin original |
3830 |
|
3831 |
And now the Perl program calling C<tzname>, the two values will be assigned |
3832 |
as in: |
3833 |
|
3834 |
=end original |
3835 |
|
3836 |
これで、C<tzname> を呼ぶ Perl プログラムでは、二つの値は |
3837 |
以下のように代入できます。 |
3838 |
|
3839 |
($standard_abbrev, $summer_abbrev) = POSIX::tzname; |
3840 |
|
3841 |
=begin original |
3842 |
|
3843 |
An alternate (and possibly simpler) method to pushing values on the stack is |
3844 |
to use the macro: |
3845 |
|
3846 |
=end original |
3847 |
|
3848 |
スタックに値を積む、別の (おそらくはより簡単な) 方法は、 |
3849 |
以下のマクロを使うことです。 |
3850 |
|
3851 |
XPUSHs(SV*) |
3852 |
|
3853 |
=begin original |
3854 |
|
3855 |
This macro automatically adjusts the stack for you, if needed. Thus, you |
3856 |
do not need to call C<EXTEND> to extend the stack. |
3857 |
|
3858 |
=end original |
3859 |
|
3860 |
こちらのマクロは、必要ならば自動的にスタックを調整してくれます。 |
3861 |
このため、C<EXTEND> をスタックを拡張するために呼ぶ必要はありません。 |
3862 |
|
3863 |
=begin original |
3864 |
|
3865 |
Despite their suggestions in earlier versions of this document the macros |
3866 |
C<(X)PUSH[iunp]> are I<not> suited to XSUBs which return multiple results. |
3867 |
For that, either stick to the C<(X)PUSHs> macros shown above, or use the new |
3868 |
C<m(X)PUSH[iunp]> macros instead; see L</Putting a C value on Perl stack>. |
3869 |
|
3870 |
=end original |
3871 |
|
3872 |
この文書の以前のバージョンでの推奨にも関わらず、マクロ C<(X)PUSH[iunp]> は |
3873 |
複数の結果を返す XSUB には向いて I<いません>。 |
3874 |
このためには、上述の C<(X)PUSHs> マクロにこだわるか、代わりに新しい |
3875 |
C<m(X)PUSH[iunp]> マクロを使ってください; |
3876 |
L</Putting a C value on Perl stack> を参照してください。 |
3877 |
|
3878 |
=begin original |
3879 |
|
3880 |
For more information, consult L<perlxs> and L<perlxstut>. |
3881 |
|
3882 |
=end original |
3883 |
|
3884 |
より詳しい情報は、L<perlxs> と L<perlxstut> を参照してください。 |
3885 |
|
3886 |
=head2 Autoloading with XSUBs |
3887 |
|
3888 |
(XSUB でのオートロード) |
3889 |
|
3890 |
=begin original |
3891 |
|
3892 |
If an AUTOLOAD routine is an XSUB, as with Perl subroutines, Perl puts the |
3893 |
fully-qualified name of the autoloaded subroutine in the $AUTOLOAD variable |
3894 |
of the XSUB's package. |
3895 |
|
3896 |
=end original |
3897 |
|
3898 |
AUTOLOAD ルーチンが XSUB の場合、Perl サブルーチンと同様に、Perl は XSUB の |
3899 |
パッケージの $AUTOLOAD 変数にオートロードされたサブルーチンの完全修飾名を |
3900 |
設定します。 |
3901 |
|
3902 |
=begin original |
3903 |
|
3904 |
But it also puts the same information in certain fields of the XSUB itself: |
3905 |
|
3906 |
=end original |
3907 |
|
3908 |
しかし、XSUB 自身の特定のフィールドにも同じ情報が設定されます: |
3909 |
|
3910 |
HV *stash = CvSTASH(cv); |
3911 |
const char *subname = SvPVX(cv); |
3912 |
STRLEN name_length = SvCUR(cv); /* in bytes */ |
3913 |
U32 is_utf8 = SvUTF8(cv); |
3914 |
|
3915 |
=begin original |
3916 |
|
3917 |
C<SvPVX(cv)> contains just the sub name itself, not including the package. |
3918 |
For an AUTOLOAD routine in UNIVERSAL or one of its superclasses, |
3919 |
C<CvSTASH(cv)> returns NULL during a method call on a nonexistent package. |
3920 |
|
3921 |
=end original |
3922 |
|
3923 |
C<SvPVX(cv)> には、パッケージを含まないサブルーチン名自身が入ります。 |
3924 |
UNIVERSAL やそのスーパークラスの AUTOLOAD ルーチンでは、C<CvSTASH(cv)> は |
3925 |
存在しないパッケージのメソッド呼び出しの間は NULL を返します。 |
3926 |
|
3927 |
=begin original |
3928 |
|
3929 |
B<Note>: Setting $AUTOLOAD stopped working in 5.6.1, which did not support |
3930 |
XS AUTOLOAD subs at all. Perl 5.8.0 introduced the use of fields in the |
3931 |
XSUB itself. Perl 5.16.0 restored the setting of $AUTOLOAD. If you need |
3932 |
to support 5.8-5.14, use the XSUB's fields. |
3933 |
|
3934 |
=end original |
3935 |
|
3936 |
B<注意>: $AUTOLOAD への設定は、XS AUTOLOAD サブルーチンに全く |
3937 |
対応していなかった 5.6.1 で動作しなくなりました。 |
3938 |
Perl 5.8.0 で XSUB 自身のフィールドの使用を導入しました。 |
3939 |
Perl 5.16.0 で $AUTOLOAD への設定が復旧されました。 |
3940 |
5.8-5.14 に対応する必要がある場合、XSUB のフィールドを使用してください。 |
3941 |
|
3942 |
=head2 Calling Perl Routines from within C Programs |
3943 |
|
3944 |
(C プログラムからの Perl ルーチンの呼び出し) |
3945 |
|
3946 |
=begin original |
3947 |
|
3948 |
There are four routines that can be used to call a Perl subroutine from |
3949 |
within a C program. These four are: |
3950 |
|
3951 |
=end original |
3952 |
|
3953 |
C プログラムから Perl サブルーチンを呼び出すために使用することのできる |
3954 |
ルーチンが 四つあります。 |
3955 |
その四つは: |
3956 |
|
3957 |
I32 call_sv(SV*, I32); |
3958 |
I32 call_pv(const char*, I32); |
3959 |
I32 call_method(const char*, I32); |
3960 |
I32 call_argv(const char*, I32, char**); |
3961 |
|
3962 |
=begin original |
3963 |
|
3964 |
The routine most often used is C<call_sv>. The C<SV*> argument |
3965 |
contains either the name of the Perl subroutine to be called, or a |
3966 |
reference to the subroutine. The second argument consists of flags |
3967 |
that control the context in which the subroutine is called, whether |
3968 |
or not the subroutine is being passed arguments, how errors should be |
3969 |
trapped, and how to treat return values. |
3970 |
|
3971 |
=end original |
3972 |
|
3973 |
最もよく使われるはずのものは、C<call_sv> です。 |
3974 |
引数 C<SV*> には呼び出される Perl サブルーチンの名前か、その |
3975 |
サブルーチンへのリファレンスが含まれます。 |
3976 |
二番目の引数には、そのサブルーチンが呼び出されたコンテキストを制御する |
3977 |
フラグが置かれます; これはサブルーチンに引数が渡されたか渡されていないか、 |
3978 |
エラーをどのようにトラップすべきなのか、どのように戻り値を返すのかを |
3979 |
制御するものです。 |
3980 |
|
3981 |
=begin original |
3982 |
|
3983 |
All four routines return the number of arguments that the subroutine returned |
3984 |
on the Perl stack. |
3985 |
|
3986 |
=end original |
3987 |
|
3988 |
四つのルーチンはいずれも、サブルーチンが Perl スタック上に返した |
3989 |
引数の数を返します。 |
3990 |
|
3991 |
=begin original |
3992 |
|
3993 |
These routines used to be called C<perl_call_sv>, etc., before Perl v5.6.0, |
3994 |
but those names are now deprecated; macros of the same name are provided for |
3995 |
compatibility. |
3996 |
|
3997 |
=end original |
3998 |
|
3999 |
これらのルーチンは Perl v5.6.0 以前では C<perl_call_sv> などと |
4000 |
呼ばれていましたが、しかしこれらの名前は現在では非推奨です; 同じ名前の |
4001 |
マクロが互換性のために提供されています。 |
4002 |
|
4003 |
=begin original |
4004 |
|
4005 |
When using any of these routines (except C<call_argv>), the programmer |
4006 |
must manipulate the Perl stack. These include the following macros and |
4007 |
functions: |
4008 |
|
4009 |
=end original |
4010 |
|
4011 |
これらのルーチンを使うときには(C<call_argv> を除いて)、プログラマが |
4012 |
Perl スタックを操作しなくてはなりません。 |
4013 |
以下のマクロと関数が用意されています: |
4014 |
|
4015 |
dSP |
4016 |
SP |
4017 |
PUSHMARK() |
4018 |
PUTBACK |
4019 |
SPAGAIN |
4020 |
ENTER |
4021 |
SAVETMPS |
4022 |
FREETMPS |
4023 |
LEAVE |
4024 |
XPUSH*() |
4025 |
POP*() |
4026 |
|
4027 |
=begin original |
4028 |
|
4029 |
For a detailed description of calling conventions from C to Perl, |
4030 |
consult L<perlcall>. |
4031 |
|
4032 |
=end original |
4033 |
|
4034 |
C から Perl を呼び出す約束ごとについての詳しい記述は |
4035 |
L<perlcall> を参照してください。 |
4036 |
|
4037 |
=head2 Putting a C value on Perl stack |
4038 |
|
4039 |
(C での値を Perl スタックに入れる) |
4040 |
|
4041 |
=begin original |
4042 |
|
4043 |
A lot of opcodes (this is an elementary operation in the internal perl |
4044 |
stack machine) put an SV* on the stack. However, as an optimization |
4045 |
the corresponding SV is (usually) not recreated each time. The opcodes |
4046 |
reuse specially assigned SVs (I<target>s) which are (as a corollary) |
4047 |
not constantly freed/created. |
4048 |
|
4049 |
=end original |
4050 |
|
4051 |
たくさんのオペコード(これは内部的な perl スタックマシンでの基本的な |
4052 |
操作です)が SV をスタックに置きます。 |
4053 |
しかしながら、SV に対する最適化のようなものは(通常は)毎回 |
4054 |
行なわれるわけではありません。 |
4055 |
オペコードは解放されたり、生成されることのない特別に割り当てられた |
4056 |
SV (I<target>) を再利用します。 |
4057 |
|
4058 |
=begin original |
4059 |
|
4060 |
Each of the targets is created only once (but see |
4061 |
L<Scratchpads and recursion> below), and when an opcode needs to put |
4062 |
an integer, a double, or a string on stack, it just sets the |
4063 |
corresponding parts of its I<target> and puts the I<target> on stack. |
4064 |
|
4065 |
=end original |
4066 |
|
4067 |
それぞれの targets は、一度だけ生成して(ただし、後述する |
4068 |
L<Scratchpads and recursion> を参照のこと)、オペコードがスタックに |
4069 |
整数値、倍精度実数値、文字列といったものを置くことを必要とするときに、 |
4070 |
スタックに I<target> を置きます。 |
4071 |
|
4072 |
=begin original |
4073 |
|
4074 |
The macro to put this target on stack is C<PUSHTARG>, and it is |
4075 |
directly used in some opcodes, as well as indirectly in zillions of |
4076 |
others, which use it via C<(X)PUSH[iunp]>. |
4077 |
|
4078 |
=end original |
4079 |
|
4080 |
この target をスタックに置くためのマクロが C<PUSHTARG> です; このマクロは、 |
4081 |
他の多くのマクロが C<(X)PUSH[iunp]> を通じて間接的に使っているのと同様に、 |
4082 |
幾つかのオペコードで直接使われています。 |
4083 |
|
4084 |
=begin original |
4085 |
|
4086 |
Because the target is reused, you must be careful when pushing multiple |
4087 |
values on the stack. The following code will not do what you think: |
4088 |
|
4089 |
=end original |
4090 |
|
4091 |
ターゲットは再利用されるので、スタックに複数の値をプッシュするときには |
4092 |
注意しなければなりません。 |
4093 |
以下のコードはあなたが考えているようには動作しません: |
4094 |
|
4095 |
XPUSHi(10); |
4096 |
XPUSHi(20); |
4097 |
|
4098 |
=begin original |
4099 |
|
4100 |
This translates as "set C<TARG> to 10, push a pointer to C<TARG> onto |
4101 |
the stack; set C<TARG> to 20, push a pointer to C<TARG> onto the stack". |
4102 |
At the end of the operation, the stack does not contain the values 10 |
4103 |
and 20, but actually contains two pointers to C<TARG>, which we have set |
4104 |
to 20. |
4105 |
|
4106 |
=end original |
4107 |
|
4108 |
これは、「C<TARG> に 10 を設定して、C<TARG> へのポインタをスタックに |
4109 |
プッシュする; C<TARG> に 20 を設定して、C<TARG> へのポインタをスタックに |
4110 |
プッシュする」と解釈されます。 |
4111 |
操作の終了時、スタックには値 10 と 20 はなく、値 を 20 に設定された |
4112 |
C<TARG> へのポインタが二つあります。 |
4113 |
|
4114 |
=begin original |
4115 |
|
4116 |
If you need to push multiple different values then you should either use |
4117 |
the C<(X)PUSHs> macros, or else use the new C<m(X)PUSH[iunp]> macros, |
4118 |
none of which make use of C<TARG>. The C<(X)PUSHs> macros simply push an |
4119 |
SV* on the stack, which, as noted under L</XSUBs and the Argument Stack>, |
4120 |
will often need to be "mortal". The new C<m(X)PUSH[iunp]> macros make |
4121 |
this a little easier to achieve by creating a new mortal for you (via |
4122 |
C<(X)PUSHmortal>), pushing that onto the stack (extending it if necessary |
4123 |
in the case of the C<mXPUSH[iunp]> macros), and then setting its value. |
4124 |
Thus, instead of writing this to "fix" the example above: |
4125 |
|
4126 |
=end original |
4127 |
|
4128 |
複数の異なった値をプッシュしたい場合、C<(X)PUSHs> マクロを使うか、新しい |
4129 |
C<m(X)PUSH[iunp]> マクロを使う必要があります; どちらもC<TARG> は使いません。 |
4130 |
C<(X)PUSHs> マクロは単に SV* をスタックにプッシュし、この値は、 |
4131 |
L</XSUBs and the Argument Stack> で注意されているように、 |
4132 |
しばしば「揮発性」である必要があります。 |
4133 |
新しい C<m(X)PUSH[iunp]> マクロは、新しい揮発性値を |
4134 |
(C<(X)PUSHmortal> を使って)作成し、それをスタックにプッシュし |
4135 |
(C<mXPUSH[iunp]> マクロの場合もし必要なら拡張して)、それから値を設定します。 |
4136 |
従って、前述の例を「修正」するのに以下のように書く代わりに: |
4137 |
|
4138 |
XPUSHs(sv_2mortal(newSViv(10))) |
4139 |
XPUSHs(sv_2mortal(newSViv(20))) |
4140 |
|
4141 |
=begin original |
4142 |
|
4143 |
you can simply write: |
4144 |
|
4145 |
=end original |
4146 |
|
4147 |
単純にこう書けます: |
4148 |
|
4149 |
mXPUSHi(10) |
4150 |
mXPUSHi(20) |
4151 |
|
4152 |
=begin original |
4153 |
|
4154 |
On a related note, if you do use C<(X)PUSH[iunp]>, then you're going to |
4155 |
need a C<dTARG> in your variable declarations so that the C<*PUSH*> |
4156 |
macros can make use of the local variable C<TARG>. See also C<dTARGET> |
4157 |
and C<dXSTARG>. |
4158 |
|
4159 |
=end original |
4160 |
|
4161 |
関連する注意として、C<(X)PUSH[iunp]> を使うなら、C<*PUSH*> マクロが |
4162 |
ローカル変数 C<TARG> を使うように、変数宣言に C<dTARG> が必要でしょう。 |
4163 |
C<dTARGET> と C<dXSTARG> も参照してください。 |
4164 |
|
4165 |
=head2 Scratchpads |
4166 |
|
4167 |
(スクラッチパッド) |
4168 |
|
4169 |
=begin original |
4170 |
|
4171 |
The question remains on when the SVs which are I<target>s for opcodes |
4172 |
are created. The answer is that they are created when the current |
4173 |
unit--a subroutine or a file (for opcodes for statements outside of |
4174 |
subroutines)--is compiled. During this time a special anonymous Perl |
4175 |
array is created, which is called a scratchpad for the current unit. |
4176 |
|
4177 |
=end original |
4178 |
|
4179 |
残っている疑問は、オペコードに対する I<target>s である SV をいつ |
4180 |
生成するのかということでしょう。 |
4181 |
その答えは、カレントユニット -- サブルーチンもしくは(サブルーチンの |
4182 |
外側にある文のためのオペコードのための)ファイル -- が |
4183 |
コンパイルされたときです。 |
4184 |
この間、特別な無名配列が生成されます; これはカレントユニットのための |
4185 |
スクラッチパッド (scrachpad) と呼ばれるものです。 |
4186 |
|
4187 |
=begin original |
4188 |
|
4189 |
A scratchpad keeps SVs which are lexicals for the current unit and are |
4190 |
targets for opcodes. A previous version of this document |
4191 |
stated that one can deduce that an SV lives on a scratchpad |
4192 |
by looking on its flags: lexicals have C<SVs_PADMY> set, and |
4193 |
I<target>s have C<SVs_PADTMP> set. But this have never been fully true. |
4194 |
C<SVs_PADMY> could be set on a variable that no longer resides in any pad. |
4195 |
While I<target>s do have C<SVs_PADTMP> set, it can also be set on variables |
4196 |
that have never resided in a pad, but nonetheless act like I<target>s. |
4197 |
|
4198 |
=end original |
4199 |
|
4200 |
スクラッチパッドはカレントユニットのためのレキシカルやオペコードのための |
4201 |
target である SV を保持します。 |
4202 |
この文書の以前の版では、SV があるスクラッチパッドを、SV のフラグを |
4203 |
見ることによって推測することができると書いていました: レキシカルでは |
4204 |
C<SVs_PADMY> が設定されていて、I<target> では C<SVs_PADTMP> が |
4205 |
設定されています。 |
4206 |
しかしこれは決して完全に真ではありません。 |
4207 |
C<SVs_PADMY> はもはやどのパッドにも存在しない変数に |
4208 |
セットされることがあります。 |
4209 |
I<target> は C<SVs_PADTMP> が設定されている一方、 |
4210 |
どのパッドにも存在しない変数に設定されることもありますが、 |
4211 |
それでも I<target> のように振る舞います。 |
4212 |
|
4213 |
=begin original |
4214 |
|
4215 |
The correspondence between OPs and I<target>s is not 1-to-1. Different |
4216 |
OPs in the compile tree of the unit can use the same target, if this |
4217 |
would not conflict with the expected life of the temporary. |
4218 |
|
4219 |
=end original |
4220 |
|
4221 |
オペコードと I<target>s の間の対応は一対一ではありません。 |
4222 |
あるユニットの翻訳木 (compile tree)にある異なるオペコードは、これが一時変数の |
4223 |
expected life と衝突していなければ同じ target を使うことができます。 |
4224 |
|
4225 |
=head2 Scratchpads and recursion |
4226 |
|
4227 |
(スクラッチパッドと再帰) |
4228 |
|
4229 |
=begin original |
4230 |
|
4231 |
In fact it is not 100% true that a compiled unit contains a pointer to |
4232 |
the scratchpad AV. In fact it contains a pointer to an AV of |
4233 |
(initially) one element, and this element is the scratchpad AV. Why do |
4234 |
we need an extra level of indirection? |
4235 |
|
4236 |
=end original |
4237 |
|
4238 |
コンパイルされたユニットがスクラッチパッド AV へのポインタを |
4239 |
保持しているということは、100% 本当のことではありません。 |
4240 |
実際は、(初期値では)一要素の AV へのポインタを保持していて、この要素が |
4241 |
スクラッチパッド AV なのです。 |
4242 |
なぜ、こういう余計な間接レベルを必要としているのでしょう? |
4243 |
|
4244 |
=begin original |
4245 |
|
4246 |
The answer is B<recursion>, and maybe B<threads>. Both |
4247 |
these can create several execution pointers going into the same |
4248 |
subroutine. For the subroutine-child not write over the temporaries |
4249 |
for the subroutine-parent (lifespan of which covers the call to the |
4250 |
child), the parent and the child should have different |
4251 |
scratchpads. (I<And> the lexicals should be separate anyway!) |
4252 |
|
4253 |
=end original |
4254 |
|
4255 |
その答えは B<再帰> と、おそらく B<スレッド> です。 |
4256 |
これら二つは同じサブルーチンに対する別々の実行ポインタを |
4257 |
生成しようとするかもしれません。 |
4258 |
子サブルーチンが(呼び出す子サブルーチンを覆っている寿命を持つ) |
4259 |
親サブルーチンの一時変数を上書きしてしまわないように、 |
4260 |
親と子では、異なるスクラッチパッドを持つようにすべきです。 |
4261 |
(I<かつ>、レキシカルは分けておくべきなのです!) |
4262 |
|
4263 |
=begin original |
4264 |
|
4265 |
So each subroutine is born with an array of scratchpads (of length 1). |
4266 |
On each entry to the subroutine it is checked that the current |
4267 |
depth of the recursion is not more than the length of this array, and |
4268 |
if it is, new scratchpad is created and pushed into the array. |
4269 |
|
4270 |
=end original |
4271 |
|
4272 |
各サブルーチンは、スクラッチパッドの(長さが 1 の)配列を伴って生成されます。 |
4273 |
サブルーチンに対する各エントリーはその時点での再帰の深さが |
4274 |
この配列の長さよりも大きくないことをチェックします; そして、もし |
4275 |
そうであれば、新たなスクラッチパッドが生成されて配列へとプッシュされます。 |
4276 |
|
4277 |
=begin original |
4278 |
|
4279 |
The I<target>s on this scratchpad are C<undef>s, but they are already |
4280 |
marked with correct flags. |
4281 |
|
4282 |
=end original |
4283 |
|
4284 |
このスクラッチパッドにある I<target>s は C<undef> ですが、これらはすでに |
4285 |
正しいフラグによってマークされています。 |
4286 |
|
4287 |
=head1 Memory Allocation |
4288 |
|
4289 |
(メモリ割り当て) |
4290 |
|
4291 |
=head2 Allocation |
4292 |
|
4293 |
(割り当て) |
4294 |
|
4295 |
=begin original |
4296 |
|
4297 |
All memory meant to be used with the Perl API functions should be manipulated |
4298 |
using the macros described in this section. The macros provide the necessary |
4299 |
transparency between differences in the actual malloc implementation that is |
4300 |
used within perl. |
4301 |
|
4302 |
=end original |
4303 |
|
4304 |
Perl API 関数と共に使うような全てのメモリはこのセクションで |
4305 |
説明されているマクロを使って扱うべきです。 |
4306 |
マクロは実際の malloc の |
4307 |
実装と、perl で使われているものとの差を透過的にします。 |
4308 |
|
4309 |
=begin original |
4310 |
|
4311 |
It is suggested that you enable the version of malloc that is distributed |
4312 |
with Perl. It keeps pools of various sizes of unallocated memory in |
4313 |
order to satisfy allocation requests more quickly. However, on some |
4314 |
platforms, it may cause spurious malloc or free errors. |
4315 |
|
4316 |
=end original |
4317 |
|
4318 |
Perl と一緒に配布されていて、あなたがこれを使うことを推奨されている |
4319 |
malloc の変種です。 |
4320 |
これは様々な大きさの未割り付けのメモリをプールしておき、 |
4321 |
より早く割り付け要求に応えようとするものです。 |
4322 |
しかしながら一部のプラットフォームでは、これは不法な malloc エラーや |
4323 |
free エラーを引き起こす可能性があります。 |
4324 |
|
4325 |
=begin original |
4326 |
|
4327 |
The following three macros are used to initially allocate memory : |
4328 |
|
4329 |
=end original |
4330 |
|
4331 |
これら三つのマクロはメモリの割り付けのために使われます: |
4332 |
|
4333 |
Newx(pointer, number, type); |
4334 |
Newxc(pointer, number, type, cast); |
4335 |
Newxz(pointer, number, type); |
4336 |
|
4337 |
=begin original |
4338 |
|
4339 |
The first argument C<pointer> should be the name of a variable that will |
4340 |
point to the newly allocated memory. |
4341 |
|
4342 |
=end original |
4343 |
|
4344 |
1 番目の引数 C<pointer> は、新たにメモリを割り付けられる変数の名前にします。 |
4345 |
|
4346 |
=begin original |
4347 |
|
4348 |
The second and third arguments C<number> and C<type> specify how many of |
4349 |
the specified type of data structure should be allocated. The argument |
4350 |
C<type> is passed to C<sizeof>. The final argument to C<Newxc>, C<cast>, |
4351 |
should be used if the C<pointer> argument is different from the C<type> |
4352 |
argument. |
4353 |
|
4354 |
=end original |
4355 |
|
4356 |
3 番目と 4 番目の引数 C<number> と C<type> は、指定された構造体を |
4357 |
どれだけ割り付けるのかを指定します。 |
4358 |
引数 C<type> は C<sizeof> に渡されます。 |
4359 |
C<Newxc>に対する最後の引数 C<cast>は、引数 C<pointer> が |
4360 |
引数 C<type> と異なるときに使うべきものです。 |
4361 |
|
4362 |
=begin original |
4363 |
|
4364 |
Unlike the C<Newx> and C<Newxc> macros, the C<Newxz> macro calls C<memzero> |
4365 |
to zero out all the newly allocated memory. |
4366 |
|
4367 |
=end original |
4368 |
|
4369 |
C<Newx> や C<Newxc> とは異なり、C<Newxz> は割り付けたメモリのすべてを |
4370 |
ゼロで埋めるために C<memzero> を呼び出します。 |
4371 |
|
4372 |
=head2 Reallocation |
4373 |
|
4374 |
(再割り当て) |
4375 |
|
4376 |
Renew(pointer, number, type); |
4377 |
Renewc(pointer, number, type, cast); |
4378 |
Safefree(pointer) |
4379 |
|
4380 |
=begin original |
4381 |
|
4382 |
These three macros are used to change a memory buffer size or to free a |
4383 |
piece of memory no longer needed. The arguments to C<Renew> and C<Renewc> |
4384 |
match those of C<New> and C<Newc> with the exception of not needing the |
4385 |
"magic cookie" argument. |
4386 |
|
4387 |
=end original |
4388 |
|
4389 |
上記の三つのマクロは、メモリのバッファーサイズを変更したりもう |
4390 |
使わなくなったメモリ領域を解放するために使われます。 |
4391 |
C<Renew> とC<Renewc> の引数は、"魔法のクッキー" 引数が必要ないと |
4392 |
いうことを除きそれぞれ C<New> と C<Newc> に一致します。 |
4393 |
|
4394 |
=head2 Moving |
4395 |
|
4396 |
(移動) |
4397 |
|
4398 |
Move(source, dest, number, type); |
4399 |
Copy(source, dest, number, type); |
4400 |
Zero(dest, number, type); |
4401 |
|
4402 |
=begin original |
4403 |
|
4404 |
These three macros are used to move, copy, or zero out previously allocated |
4405 |
memory. The C<source> and C<dest> arguments point to the source and |
4406 |
destination starting points. Perl will move, copy, or zero out C<number> |
4407 |
instances of the size of the C<type> data structure (using the C<sizeof> |
4408 |
function). |
4409 |
|
4410 |
=end original |
4411 |
|
4412 |
この三つのマクロは、それぞれ割り付けたメモリ領域に対する移動、 |
4413 |
複写、ゼロで埋めるといったことに使われます。 |
4414 |
C<source> と C<dest> という引数は、転送元と転送先の開始番地へのポインタです。 |
4415 |
Perl は、構造体 C<type> の大きさ (C<sizeof> 関数を使います)のインスタンスの |
4416 |
C<number> 個分だけ、移動、複写、ゼロ埋めを行います。 |
4417 |
|
4418 |
=head1 PerlIO |
4419 |
|
4420 |
=begin original |
4421 |
|
4422 |
The most recent development releases of Perl have been experimenting with |
4423 |
removing Perl's dependency on the "normal" standard I/O suite and allowing |
4424 |
other stdio implementations to be used. This involves creating a new |
4425 |
abstraction layer that then calls whichever implementation of stdio Perl |
4426 |
was compiled with. All XSUBs should now use the functions in the PerlIO |
4427 |
abstraction layer and not make any assumptions about what kind of stdio |
4428 |
is being used. |
4429 |
|
4430 |
=end original |
4431 |
|
4432 |
最新リリースの Perl の開発では、Perl の「通常の」標準入出力ライブラリに |
4433 |
依存している部分を取り除くことと、Perl で別の標準入出力の実装が |
4434 |
使えるようにすることが試みられました。 |
4435 |
これにより必然的に、Perl と共にコンパイルされた標準入出力の実装を |
4436 |
呼び出すような新しい抽象層が作られました。 |
4437 |
すべての XSUB は、今では PerlIO 抽象層の関数を使うべきで、 |
4438 |
これまで使っていた標準入出力に関してのすべての仮定はすべきではありません。 |
4439 |
|
4440 |
=begin original |
4441 |
|
4442 |
For a complete description of the PerlIO abstraction, consult L<perlapio>. |
4443 |
|
4444 |
=end original |
4445 |
|
4446 |
PerlIO 抽象化に関する詳しい記述は L<perlapio> を参照してください。 |
4447 |
|
4448 |
=head1 Compiled code |
4449 |
|
4450 |
(コンパイルされたコード) |
4451 |
|
4452 |
=head2 Code tree |
4453 |
|
4454 |
(コード木) |
4455 |
|
4456 |
=begin original |
4457 |
|
4458 |
Here we describe the internal form your code is converted to by |
4459 |
Perl. Start with a simple example: |
4460 |
|
4461 |
=end original |
4462 |
|
4463 |
ここで、Perl によって変換されたプログラムの内部形式を説明しましょう。 |
4464 |
簡単な例から始めます。 |
4465 |
|
4466 |
$a = $b + $c; |
4467 |
|
4468 |
=begin original |
4469 |
|
4470 |
This is converted to a tree similar to this one: |
4471 |
|
4472 |
=end original |
4473 |
|
4474 |
これは次のような木構造へ変換されます: |
4475 |
|
4476 |
assign-to |
4477 |
/ \ |
4478 |
+ $a |
4479 |
/ \ |
4480 |
$b $c |
4481 |
|
4482 |
=begin original |
4483 |
|
4484 |
(but slightly more complicated). This tree reflects the way Perl |
4485 |
parsed your code, but has nothing to do with the execution order. |
4486 |
There is an additional "thread" going through the nodes of the tree |
4487 |
which shows the order of execution of the nodes. In our simplified |
4488 |
example above it looks like: |
4489 |
|
4490 |
=end original |
4491 |
|
4492 |
(実際にはもっと複雑です)。 |
4493 |
この木構造は、Perl があなたのプログラムを解析したやり方を反映していますが、 |
4494 |
実行の順序については反映していません。 |
4495 |
ノードの実行順序を表わす木構造のノードを辿ろうとする別の |
4496 |
「スレッド」(thread) があります。 |
4497 |
先の簡単な例では、次のようになります。 |
4498 |
|
4499 |
$b ---> $c ---> + ---> $a ---> assign-to |
4500 |
|
4501 |
=begin original |
4502 |
|
4503 |
But with the actual compile tree for C<$a = $b + $c> it is different: |
4504 |
some nodes I<optimized away>. As a corollary, though the actual tree |
4505 |
contains more nodes than our simplified example, the execution order |
4506 |
is the same as in our example. |
4507 |
|
4508 |
=end original |
4509 |
|
4510 |
しかし、C<$a = $b + $c> に対する実際の解析木はこれと異なります: 一部の |
4511 |
ノードがI<最適化>されています。 |
4512 |
その結果として、実際の木構造が私たちの単純な例よりも多くのノードを |
4513 |
持っていたとしても、その実行順序は同じになります。 |
4514 |
|
4515 |
=head2 Examining the tree |
4516 |
|
4517 |
(木を検査する) |
4518 |
|
4519 |
=begin original |
4520 |
|
4521 |
If you have your perl compiled for debugging (usually done with |
4522 |
C<-DDEBUGGING> on the C<Configure> command line), you may examine the |
4523 |
compiled tree by specifying C<-Dx> on the Perl command line. The |
4524 |
output takes several lines per node, and for C<$b+$c> it looks like |
4525 |
this: |
4526 |
|
4527 |
=end original |
4528 |
|
4529 |
perl をデバッグ用にコンパイルした(通常は C<Configure> のコマンドラインで |
4530 |
C<-DDEBUGGING> を使って行います)場合、Perl のコマンドラインで |
4531 |
C<-Dx> を指定することによって解析木を検査することができます。 |
4532 |
その出力はノード毎に数行を取り、C<$b+$c> は以下のようになります。 |
4533 |
|
4534 |
5 TYPE = add ===> 6 |
4535 |
TARG = 1 |
4536 |
FLAGS = (SCALAR,KIDS) |
4537 |
{ |
4538 |
TYPE = null ===> (4) |
4539 |
(was rv2sv) |
4540 |
FLAGS = (SCALAR,KIDS) |
4541 |
{ |
4542 |
3 TYPE = gvsv ===> 4 |
4543 |
FLAGS = (SCALAR) |
4544 |
GV = main::b |
4545 |
} |
4546 |
} |
4547 |
{ |
4548 |
TYPE = null ===> (5) |
4549 |
(was rv2sv) |
4550 |
FLAGS = (SCALAR,KIDS) |
4551 |
{ |
4552 |
4 TYPE = gvsv ===> 5 |
4553 |
FLAGS = (SCALAR) |
4554 |
GV = main::c |
4555 |
} |
4556 |
} |
4557 |
|
4558 |
=begin original |
4559 |
|
4560 |
This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are |
4561 |
not optimized away (one per number in the left column). The immediate |
4562 |
children of the given node correspond to C<{}> pairs on the same level |
4563 |
of indentation, thus this listing corresponds to the tree: |
4564 |
|
4565 |
=end original |
4566 |
|
4567 |
この木には五つのノード(C<TYPE> 毎にひとつ)があって、そのうちの |
4568 |
三つだけが最適化されないものです(左側に数字のあるもの)。 |
4569 |
与えられたノードのすぐ下にある子供は同じレベルのインデントにある C<{}> の |
4570 |
ペアに対応します; したがって、このリストは以下の木に対応します。 |
4571 |
|
4572 |
add |
4573 |
/ \ |
4574 |
null null |
4575 |
| | |
4576 |
gvsv gvsv |
4577 |
|
4578 |
=begin original |
4579 |
|
4580 |
The execution order is indicated by C<===E<gt>> marks, thus it is C<3 |
4581 |
4 5 6> (node C<6> is not included into above listing), i.e., |
4582 |
C<gvsv gvsv add whatever>. |
4583 |
|
4584 |
=end original |
4585 |
|
4586 |
実行順序は C<===E<gt>> マークによって表わされますから、C<3 4 5 6> |
4587 |
(ノード C<6>は、上にあるリストには含まれません)となります; |
4588 |
つまり、C<gvsv gvsv add whatever> ということになります。 |
4589 |
|
4590 |
=begin original |
4591 |
|
4592 |
Each of these nodes represents an op, a fundamental operation inside the |
4593 |
Perl core. The code which implements each operation can be found in the |
4594 |
F<pp*.c> files; the function which implements the op with type C<gvsv> |
4595 |
is C<pp_gvsv>, and so on. As the tree above shows, different ops have |
4596 |
different numbers of children: C<add> is a binary operator, as one would |
4597 |
expect, and so has two children. To accommodate the various different |
4598 |
numbers of children, there are various types of op data structure, and |
4599 |
they link together in different ways. |
4600 |
|
4601 |
=end original |
4602 |
|
4603 |
ノードのそれぞれは op を示し、これは Perl コア内部の基本的な操作です。 |
4604 |
それぞれの操作を実装しているコードは F<pp*.c> ファイルにあります; |
4605 |
C<gvsv> 型の op を実装している関数は C<pp_gvsv>、といった形です。 |
4606 |
上述の木において、異なった op は異なった数の子を持ちます: C<add> は |
4607 |
二項演算子で、推測される通り、二つの子を持ちます。 |
4608 |
様々に異なる数の子に対応するために、op データ構造には様々な種類があり、 |
4609 |
異なった方法で互いにリンクしています。 |
4610 |
|
4611 |
=begin original |
4612 |
|
4613 |
The simplest type of op structure is C<OP>: this has no children. Unary |
4614 |
operators, C<UNOP>s, have one child, and this is pointed to by the |
4615 |
C<op_first> field. Binary operators (C<BINOP>s) have not only an |
4616 |
C<op_first> field but also an C<op_last> field. The most complex type of |
4617 |
op is a C<LISTOP>, which has any number of children. In this case, the |
4618 |
first child is pointed to by C<op_first> and the last child by |
4619 |
C<op_last>. The children in between can be found by iteratively |
4620 |
following the C<op_sibling> pointer from the first child to the last. |
4621 |
|
4622 |
=end original |
4623 |
|
4624 |
op 構造体の最も単純な型は C<OP> です: これは子はありません。 |
4625 |
単項演算子である C<UNOP> は一つの子を持ち、これは C<op_first> |
4626 |
フィールドによって示されています。 |
4627 |
二項演算子 (C<BINOP>) は C<op_first> フィールドだけでなく |
4628 |
C<op_last> フィールドも持ちます。 |
4629 |
最も複雑な op の型は C<LISTOP> で、任意の数の子を持ちます。 |
4630 |
この場合、最初の子は C<op_first> で示され、最後の子は C<op_last> で示されます。 |
4631 |
その間の子は、最初の子から最後の子まで C<op_sibling> ポインタを反復的に |
4632 |
辿ることで見つけられます。 |
4633 |
|
4634 |
=begin original |
4635 |
|
4636 |
There are also two other op types: a C<PMOP> holds a regular expression, |
4637 |
and has no children, and a C<LOOP> may or may not have children. If the |
4638 |
C<op_children> field is non-zero, it behaves like a C<LISTOP>. To |
4639 |
complicate matters, if a C<UNOP> is actually a C<null> op after |
4640 |
optimization (see L</Compile pass 2: context propagation>) it will still |
4641 |
have children in accordance with its former type. |
4642 |
|
4643 |
=end original |
4644 |
|
4645 |
あと二つの op 型があります: C<PMOP> は正規表現を保持し、子はありません; |
4646 |
また C<LOOP> は子があるかもしれませんしないかもしれません。 |
4647 |
C<op_children> フィールドが非ゼロなら、C<LISTOP> のように振る舞います。 |
4648 |
問題を複雑にするために、もし C<UNOP> が最適化の後実際には |
4649 |
C<null> op になった場合 (L</Compile pass 2: context propagation> を |
4650 |
参照してください)、これは以前の形に一致する形で子を持ちます。 |
4651 |
|
4652 |
=begin original |
4653 |
|
4654 |
Another way to examine the tree is to use a compiler back-end module, such |
4655 |
as L<B::Concise>. |
4656 |
|
4657 |
=end original |
4658 |
|
4659 |
木を調べるその他の方法は、L<B::Concise> のようなコンパイラバックエンド |
4660 |
モジュールを使うことです。 |
4661 |
|
4662 |
=head2 Compile pass 1: check routines |
4663 |
|
4664 |
(コンパイルパス1: チェックルーチン) |
4665 |
|
4666 |
=begin original |
4667 |
|
4668 |
The tree is created by the compiler while I<yacc> code feeds it |
4669 |
the constructions it recognizes. Since I<yacc> works bottom-up, so does |
4670 |
the first pass of perl compilation. |
4671 |
|
4672 |
=end original |
4673 |
|
4674 |
この木構造は、I<yacc> が perl プログラムを読み込んでその構造を解析している |
4675 |
間にコンパイラによって生成されます。 |
4676 |
yacc はボトムアップで動作するので、perl によるコンパイルの最初のパスで |
4677 |
行なわれます。 |
4678 |
|
4679 |
=begin original |
4680 |
|
4681 |
What makes this pass interesting for perl developers is that some |
4682 |
optimization may be performed on this pass. This is optimization by |
4683 |
so-called "check routines". The correspondence between node names |
4684 |
and corresponding check routines is described in F<opcode.pl> (do not |
4685 |
forget to run C<make regen_headers> if you modify this file). |
4686 |
|
4687 |
=end original |
4688 |
|
4689 |
perl 開発者にとって興味深いのは、このパスで行なわれるいくつかの |
4690 |
最適化でしょう。 |
4691 |
これは、"check routines" とも呼ばれる最適化です。 |
4692 |
ノード名と対応するチェックルーチンとの間の対応は F<opcode.pl> に |
4693 |
記述されています(このファイルを修正した場合には、C<make regen_headers> を |
4694 |
実行することを忘れないでください)。 |
4695 |
|
4696 |
=begin original |
4697 |
|
4698 |
A check routine is called when the node is fully constructed except |
4699 |
for the execution-order thread. Since at this time there are no |
4700 |
back-links to the currently constructed node, one can do most any |
4701 |
operation to the top-level node, including freeing it and/or creating |
4702 |
new nodes above/below it. |
4703 |
|
4704 |
=end original |
4705 |
|
4706 |
チェックルーチンは、ノードが実行順序スレッドを除いて完全に |
4707 |
構築されたときに呼び出されます。 |
4708 |
この時点では、構築されたノードに対する back-line が存在しないので、 |
4709 |
トップレベルノードに対して、新たなノードを生成したりノードを |
4710 |
解放したりすることを含めて、ほとんどの操作を行うことができます。 |
4711 |
|
4712 |
=begin original |
4713 |
|
4714 |
The check routine returns the node which should be inserted into the |
4715 |
tree (if the top-level node was not modified, check routine returns |
4716 |
its argument). |
4717 |
|
4718 |
=end original |
4719 |
|
4720 |
このチェックルーチンは木に挿入すべきノードを返します(トップレベルの |
4721 |
ノードが変更されていなければ、チェックルーチンはその引数を返します)。 |
4722 |
|
4723 |
=begin original |
4724 |
|
4725 |
By convention, check routines have names C<ck_*>. They are usually |
4726 |
called from C<new*OP> subroutines (or C<convert>) (which in turn are |
4727 |
called from F<perly.y>). |
4728 |
|
4729 |
=end original |
4730 |
|
4731 |
規約により、チェックルーチンは C<ck_*> のような名前を持ちます。 |
4732 |
これらは通常サブルーチン C<new*OP> (もしくは C<convert>) から |
4733 |
呼び出されます(これらのサブルーチンは F<perly.y> から呼び出されます)。 |
4734 |
|
4735 |
=head2 Compile pass 1a: constant folding |
4736 |
|
4737 |
(コンパイルパス1a: 定数の畳み込み) |
4738 |
|
4739 |
=begin original |
4740 |
|
4741 |
Immediately after the check routine is called the returned node is |
4742 |
checked for being compile-time executable. If it is (the value is |
4743 |
judged to be constant) it is immediately executed, and a I<constant> |
4744 |
node with the "return value" of the corresponding subtree is |
4745 |
substituted instead. The subtree is deleted. |
4746 |
|
4747 |
=end original |
4748 |
|
4749 |
チェックルーチンが呼び出された直後に、返されたノードはコンパイル時実行の |
4750 |
ためのチェックが行なわれます。 |
4751 |
もしそうであれば(値が定数であると判定された)、そのノードは即座に実行されて、 |
4752 |
「戻り値」に対応する部分木は B<定数> ノードで置換され、部分木が削除されます。 |
4753 |
|
4754 |
=begin original |
4755 |
|
4756 |
If constant folding was not performed, the execution-order thread is |
4757 |
created. |
4758 |
|
4759 |
=end original |
4760 |
|
4761 |
定数の畳み込み(constant folding)が働かなければ、実行順序スレッドが |
4762 |
生成されます。 |
4763 |
|
4764 |
=head2 Compile pass 2: context propagation |
4765 |
|
4766 |
(コンパイルパス2: コンテキスト伝播) |
4767 |
|
4768 |
=begin original |
4769 |
|
4770 |
When a context for a part of compile tree is known, it is propagated |
4771 |
down through the tree. At this time the context can have 5 values |
4772 |
(instead of 2 for runtime context): void, boolean, scalar, list, and |
4773 |
lvalue. In contrast with the pass 1 this pass is processed from top |
4774 |
to bottom: a node's context determines the context for its children. |
4775 |
|
4776 |
=end original |
4777 |
|
4778 |
解析木の一部分のコンテキストがわかっているとき、それは木の末端へ伝播します。 |
4779 |
このとき、コンテキストは(実行時コンテキストの二種類ではなく) |
4780 |
無効、真偽値、スカラ、リスト、左辺値の五種類の値を持つことができます。 |
4781 |
パス 1 とは対照的に、このパスではトップから末端へと処理が進みます: |
4782 |
あるノードのコンテキストは、その下にある部分のコンテキストを決定します。 |
4783 |
|
4784 |
=begin original |
4785 |
|
4786 |
Additional context-dependent optimizations are performed at this time. |
4787 |
Since at this moment the compile tree contains back-references (via |
4788 |
"thread" pointers), nodes cannot be free()d now. To allow |
4789 |
optimized-away nodes at this stage, such nodes are null()ified instead |
4790 |
of free()ing (i.e. their type is changed to OP_NULL). |
4791 |
|
4792 |
=end original |
4793 |
|
4794 |
コンテキストに依存した最適化はこのときに行なわれます。 |
4795 |
この動作では解析木が("スレッド" ポインタを通じて)後方参照を含んでいるので、 |
4796 |
ノードをこの時に free() することはできません。 |
4797 |
このステージでノードを最適化するのを許すために、対象となるノードは |
4798 |
free() されるかわりに null() されます(つまり、そのノードの型が OP_NULL に |
4799 |
変えられるということ)。 |
4800 |
|
4801 |
=head2 Compile pass 3: peephole optimization |
4802 |
|
4803 |
(コンパイルパス 3: 覗き穴最適化) |
4804 |
|
4805 |
=begin original |
4806 |
|
4807 |
After the compile tree for a subroutine (or for an C<eval> or a file) |
4808 |
is created, an additional pass over the code is performed. This pass |
4809 |
is neither top-down or bottom-up, but in the execution order (with |
4810 |
additional complications for conditionals). Optimizations performed |
4811 |
at this stage are subject to the same restrictions as in the pass 2. |
4812 |
|
4813 |
=end original |
4814 |
|
4815 |
サブルーチン(もしくは C<eval> かファイル)に対する解析木が生成された後で、 |
4816 |
そのコードに対する追加パスが実行されます。 |
4817 |
このパスはトップダウンでもボトムアップでもなく、(条件に対する複雑さを伴った) |
4818 |
実行順序です。 |
4819 |
このステージで行なわれる最適化はパス 2 でのものと同じ制限に従います。 |
4820 |
|
4821 |
=begin original |
4822 |
|
4823 |
Peephole optimizations are done by calling the function pointed to |
4824 |
by the global variable C<PL_peepp>. By default, C<PL_peepp> just |
4825 |
calls the function pointed to by the global variable C<PL_rpeepp>. |
4826 |
By default, that performs some basic op fixups and optimisations along |
4827 |
the execution-order op chain, and recursively calls C<PL_rpeepp> for |
4828 |
each side chain of ops (resulting from conditionals). Extensions may |
4829 |
provide additional optimisations or fixups, hooking into either the |
4830 |
per-subroutine or recursive stage, like this: |
4831 |
|
4832 |
=end original |
4833 |
|
4834 |
大域変数 C<PL_peepp> で示されている関数を呼び出すことによって、覗き穴最適化が |
4835 |
行われます。 |
4836 |
デフォルトでは、C<PL_peepp> は単に大域変数 C<PL_rpeepp> で示されている |
4837 |
関数を呼び出します。 |
4838 |
デフォルトでは、これは実行順 op チェーンに対する基本的な op の修正と最適化を |
4839 |
行い、また(条件文の結果の) op のチェーンの両側に対して再帰的に C<PL_rpeepp> を |
4840 |
呼び出します。 |
4841 |
エクステンションは、以下のように、サブルーチン毎か再帰ステージのどちらかに |
4842 |
フックすることでさらなる最適化や修正を提供できます: |
4843 |
|
4844 |
static peep_t prev_peepp; |
4845 |
static void my_peep(pTHX_ OP *o) |
4846 |
{ |
4847 |
/* custom per-subroutine optimisation goes here */ |
4848 |
prev_peepp(aTHX_ o); |
4849 |
/* custom per-subroutine optimisation may also go here */ |
4850 |
} |
4851 |
BOOT: |
4852 |
prev_peepp = PL_peepp; |
4853 |
PL_peepp = my_peep; |
4854 |
|
4855 |
static peep_t prev_rpeepp; |
4856 |
static void my_rpeep(pTHX_ OP *o) |
4857 |
{ |
4858 |
OP *orig_o = o; |
4859 |
for(; o; o = o->op_next) { |
4860 |
/* custom per-op optimisation goes here */ |
4861 |
} |
4862 |
prev_rpeepp(aTHX_ orig_o); |
4863 |
} |
4864 |
BOOT: |
4865 |
prev_rpeepp = PL_rpeepp; |
4866 |
PL_rpeepp = my_rpeep; |
4867 |
|
4868 |
=head2 Pluggable runops |
4869 |
|
4870 |
(プラガブルな runops) |
4871 |
|
4872 |
=begin original |
4873 |
|
4874 |
The compile tree is executed in a runops function. There are two runops |
4875 |
functions, in F<run.c> and in F<dump.c>. C<Perl_runops_debug> is used |
4876 |
with DEBUGGING and C<Perl_runops_standard> is used otherwise. For fine |
4877 |
control over the execution of the compile tree it is possible to provide |
4878 |
your own runops function. |
4879 |
|
4880 |
=end original |
4881 |
|
4882 |
コンパイル木は runops 関数で実行されます。 |
4883 |
F<run.c> と F<dump.c> に二つの関数があります。 |
4884 |
C<Perl_runops_debug> は DEBUGGING で使われ、C<Perl_runops_standard> は |
4885 |
その他で使われます。 |
4886 |
コンパイル木の実行を細かく制御するために、独自の runops 関数を |
4887 |
設定できます。 |
4888 |
|
4889 |
=begin original |
4890 |
|
4891 |
It's probably best to copy one of the existing runops functions and |
4892 |
change it to suit your needs. Then, in the BOOT section of your XS |
4893 |
file, add the line: |
4894 |
|
4895 |
=end original |
4896 |
|
4897 |
既にある runops 関数の一つをコピーして、必要性に合わせて変更するのが |
4898 |
おそらく最良です。 |
4899 |
それから、XS ファイルの BOOT セクションに、以下の行を追加します: |
4900 |
|
4901 |
PL_runops = my_runops; |
4902 |
|
4903 |
=begin original |
4904 |
|
4905 |
This function should be as efficient as possible to keep your programs |
4906 |
running as fast as possible. |
4907 |
|
4908 |
=end original |
4909 |
|
4910 |
この関数はプログラムを出来るだけ早く実行し続けられるように、出来るだけ |
4911 |
効率的にするべきです。 |
4912 |
|
4913 |
=head2 Compile-time scope hooks |
4914 |
|
4915 |
(コンパイル時スコープフック) |
4916 |
|
4917 |
=begin original |
4918 |
|
4919 |
As of perl 5.14 it is possible to hook into the compile-time lexical |
4920 |
scope mechanism using C<Perl_blockhook_register>. This is used like |
4921 |
this: |
4922 |
|
4923 |
=end original |
4924 |
|
4925 |
perl 5.14 から、C<Perl_blockhook_register> を使って、コンパイル時 |
4926 |
レキシカルスコープ機構にフックすることができるようになりました。 |
4927 |
これは次のようにして使います: |
4928 |
|
4929 |
STATIC void my_start_hook(pTHX_ int full); |
4930 |
STATIC BHK my_hooks; |
4931 |
|
4932 |
BOOT: |
4933 |
BhkENTRY_set(&my_hooks, bhk_start, my_start_hook); |
4934 |
Perl_blockhook_register(aTHX_ &my_hooks); |
4935 |
|
4936 |
=begin original |
4937 |
|
4938 |
This will arrange to have C<my_start_hook> called at the start of |
4939 |
compiling every lexical scope. The available hooks are: |
4940 |
|
4941 |
=end original |
4942 |
|
4943 |
これは、レキシカルスコープのコンパイルを開始する毎に C<my_start_hook> が |
4944 |
呼び出されるように設定します。 |
4945 |
利用可能なフックは: |
4946 |
|
4947 |
=over 4 |
4948 |
|
4949 |
=item C<void bhk_start(pTHX_ int full)> |
4950 |
|
4951 |
=begin original |
4952 |
|
4953 |
This is called just after starting a new lexical scope. Note that Perl |
4954 |
code like |
4955 |
|
4956 |
=end original |
4957 |
|
4958 |
これは新しいレキシカルスコープの開始の直後に呼び出されます。 |
4959 |
次のような Perl コードは |
4960 |
|
4961 |
if ($x) { ... } |
4962 |
|
4963 |
=begin original |
4964 |
|
4965 |
creates two scopes: the first starts at the C<(> and has C<full == 1>, |
4966 |
the second starts at the C<{> and has C<full == 0>. Both end at the |
4967 |
C<}>, so calls to C<start> and C<pre/post_end> will match. Anything |
4968 |
pushed onto the save stack by this hook will be popped just before the |
4969 |
scope ends (between the C<pre_> and C<post_end> hooks, in fact). |
4970 |
|
4971 |
=end original |
4972 |
|
4973 |
二つのスコープを作ることに注意してください: 一つ目は C<(> の場所で |
4974 |
C<full == 1> を持って始まり、二つ目は C<{> の場所で C<full == 0> を持って |
4975 |
始まります。 |
4976 |
両方の末尾は C<}> なので、C<start> と C<pre/post_end> の呼び出しは |
4977 |
一致します。 |
4978 |
このフックで保存スタックにプッシュされたあらゆるものはスコープが終わる直前 |
4979 |
(実際には C<pre_> と C<post_end> のフックの間) にポップされます。 |
4980 |
|
4981 |
=item C<void bhk_pre_end(pTHX_ OP **o)> |
4982 |
|
4983 |
=begin original |
4984 |
|
4985 |
This is called at the end of a lexical scope, just before unwinding the |
4986 |
stack. I<o> is the root of the optree representing the scope; it is a |
4987 |
double pointer so you can replace the OP if you need to. |
4988 |
|
4989 |
=end original |
4990 |
|
4991 |
これはレキシカルスコープの終わり、スタックを巻き戻す直前に呼び出されます。 |
4992 |
I<o> はスコープを表現する op 木のルートです; これはダブルポインタなので |
4993 |
必要なら OP を入れ替えることができます。 |
4994 |
|
4995 |
=item C<void bhk_post_end(pTHX_ OP **o)> |
4996 |
|
4997 |
=begin original |
4998 |
|
4999 |
This is called at the end of a lexical scope, just after unwinding the |
5000 |
stack. I<o> is as above. Note that it is possible for calls to C<pre_> |
5001 |
and C<post_end> to nest, if there is something on the save stack that |
5002 |
calls string eval. |
5003 |
|
5004 |
=end original |
5005 |
|
5006 |
これはレキシカルスコープの終わり、スタックを巻き戻した直後に呼び出されます。 |
5007 |
I<o> は上述の通りです。 |
5008 |
保存スタック上に文字列 eval を呼び出すものがあった場合、C<pre_> と |
5009 |
C<post_end> がネストして呼び出される可能性があることに注意してください。 |
5010 |
|
5011 |
=item C<void bhk_eval(pTHX_ OP *const o)> |
5012 |
|
5013 |
=begin original |
5014 |
|
5015 |
This is called just before starting to compile an C<eval STRING>, C<do |
5016 |
FILE>, C<require> or C<use>, after the eval has been set up. I<o> is the |
5017 |
OP that requested the eval, and will normally be an C<OP_ENTEREVAL>, |
5018 |
C<OP_DOFILE> or C<OP_REQUIRE>. |
5019 |
|
5020 |
=end original |
5021 |
|
5022 |
これは C<eval STRING>, C<do FILE>, C<require>, C<use> のコンパイルを始める |
5023 |
直前、eval が設定された後に呼び出されます。 |
5024 |
I<o> は eval を要求した OP で、通常は C<OP_ENTEREVAL>, C<OP_DOFILE>, |
5025 |
C<OP_REQUIRE> のいずれかです。 |
5026 |
|
5027 |
=back |
5028 |
|
5029 |
=begin original |
5030 |
|
5031 |
Once you have your hook functions, you need a C<BHK> structure to put |
5032 |
them in. It's best to allocate it statically, since there is no way to |
5033 |
free it once it's registered. The function pointers should be inserted |
5034 |
into this structure using the C<BhkENTRY_set> macro, which will also set |
5035 |
flags indicating which entries are valid. If you do need to allocate |
5036 |
your C<BHK> dynamically for some reason, be sure to zero it before you |
5037 |
start. |
5038 |
|
5039 |
=end original |
5040 |
|
5041 |
フック関数を持つと、それを入れる C<BHK> 構造体が必要です。 |
5042 |
これは静的に割り当てるのが最良です; 一度登録すると解放する方法はないからです。 |
5043 |
関数ポインタは C<BhkENTRY_set> マクロを使ってこの構造体に挿入されます; |
5044 |
これはまたどのエントリが有効化を示すフラグを設定します。 |
5045 |
何らかの理由で C<BHK> を動的に割り当てる必要がある場合、開始前にゼロで |
5046 |
埋めておく必要があります。 |
5047 |
|
5048 |
=begin original |
5049 |
|
5050 |
Once registered, there is no mechanism to switch these hooks off, so if |
5051 |
that is necessary you will need to do this yourself. An entry in C<%^H> |
5052 |
is probably the best way, so the effect is lexically scoped; however it |
5053 |
is also possible to use the C<BhkDISABLE> and C<BhkENABLE> macros to |
5054 |
temporarily switch entries on and off. You should also be aware that |
5055 |
generally speaking at least one scope will have opened before your |
5056 |
extension is loaded, so you will see some C<pre/post_end> pairs that |
5057 |
didn't have a matching C<start>. |
5058 |
|
5059 |
=end original |
5060 |
|
5061 |
フックが一旦登録されると、無効にするための機構はないので、それが必要な |
5062 |
場合は自分自身でそうする必要があります。 |
5063 |
C<%^H> のエントリはおそらく最良の方法です; 効果はレキシカルスコープを |
5064 |
持つからです; しかし一時的にエントリを有効または無効にするために |
5065 |
C<BhkDISABLE> と C<BhkENABLE> マクロを使うことも可能です。 |
5066 |
また、一般的に言ってエクステンションが読み込まれる前に最低一つのスコープが |
5067 |
開いているので、対になる C<start> のない C<pre/post_end> の組を見ることにも |
5068 |
注意するべきです。 |
5069 |
|
5070 |
=head1 Examining internal data structures with the C<dump> functions |
5071 |
|
5072 |
(内部データ構造を C<dump> 関数で調べる) |
5073 |
|
5074 |
=begin original |
5075 |
|
5076 |
To aid debugging, the source file F<dump.c> contains a number of |
5077 |
functions which produce formatted output of internal data structures. |
5078 |
|
5079 |
=end original |
5080 |
|
5081 |
デバッグを助けるために、ソースファイル F<dump.c> に内部データ構造の |
5082 |
フォーマットした出力を生成する多くの関数があります。 |
5083 |
|
5084 |
=begin original |
5085 |
|
5086 |
The most commonly used of these functions is C<Perl_sv_dump>; it's used |
5087 |
for dumping SVs, AVs, HVs, and CVs. The C<Devel::Peek> module calls |
5088 |
C<sv_dump> to produce debugging output from Perl-space, so users of that |
5089 |
module should already be familiar with its format. |
5090 |
|
5091 |
=end original |
5092 |
|
5093 |
これらの関数で最もよく使われるものは C<Perl_sv_dump> です; これは |
5094 |
SV, AV, HV, CV をダンプするために使います。 |
5095 |
C<Devel::Peek> モジュールは、Perl 空間からのデバッグ出力を作成するために |
5096 |
C<sv_dump> を呼び出すので、このモジュールのユーザーは既にこのフォーマットに |
5097 |
親しみがあるはずです。 |
5098 |
|
5099 |
=begin original |
5100 |
|
5101 |
C<Perl_op_dump> can be used to dump an C<OP> structure or any of its |
5102 |
derivatives, and produces output similar to C<perl -Dx>; in fact, |
5103 |
C<Perl_dump_eval> will dump the main root of the code being evaluated, |
5104 |
exactly like C<-Dx>. |
5105 |
|
5106 |
=end original |
5107 |
|
5108 |
C<Perl_op_dump> は、C<OP> 構造体やその派生をダンプするために使い、 |
5109 |
C<perl -Dx> と同様の出力を作成します; 実際のところ、C<Perl_dump_eval> は |
5110 |
C<-Dx> と正確に同じように、評価されたコードの main ルートをダンプします。 |
5111 |
|
5112 |
=begin original |
5113 |
|
5114 |
Other useful functions are C<Perl_dump_sub>, which turns a C<GV> into an |
5115 |
op tree, C<Perl_dump_packsubs> which calls C<Perl_dump_sub> on all the |
5116 |
subroutines in a package like so: (Thankfully, these are all xsubs, so |
5117 |
there is no op tree) |
5118 |
|
5119 |
=end original |
5120 |
|
5121 |
その他の有用な関数は、C<GV> を op 木に変換する C<Perl_dump_sub> と、 |
5122 |
パッケージの全てのサブルーチンで C<Perl_dump_sub> を呼び出す |
5123 |
C<Perl_dump_packsubs>: (ありがたいことに、これらは全て xsub なので、 |
5124 |
op 木はありません) |
5125 |
|
5126 |
(gdb) print Perl_dump_packsubs(PL_defstash) |
5127 |
|
5128 |
SUB attributes::bootstrap = (xsub 0x811fedc 0) |
5129 |
|
5130 |
SUB UNIVERSAL::can = (xsub 0x811f50c 0) |
5131 |
|
5132 |
SUB UNIVERSAL::isa = (xsub 0x811f304 0) |
5133 |
|
5134 |
SUB UNIVERSAL::VERSION = (xsub 0x811f7ac 0) |
5135 |
|
5136 |
SUB DynaLoader::boot_DynaLoader = (xsub 0x805b188 0) |
5137 |
|
5138 |
=begin original |
5139 |
|
5140 |
and C<Perl_dump_all>, which dumps all the subroutines in the stash and |
5141 |
the op tree of the main root. |
5142 |
|
5143 |
=end original |
5144 |
|
5145 |
および、stash の全てのサブルーチンと main ルートの op 木をダンプする |
5146 |
C<Perl_dump_all> です。 |
5147 |
|
5148 |
=head1 How multiple interpreters and concurrency are supported |
5149 |
|
5150 |
(複数インタプリタと並列性にどのように対応しているか) |
5151 |
|
5152 |
=head2 Background and PERL_IMPLICIT_CONTEXT |
5153 |
|
5154 |
(背景と PERL_IMPLICIT_CONTEXT) |
5155 |
|
5156 |
=begin original |
5157 |
|
5158 |
The Perl interpreter can be regarded as a closed box: it has an API |
5159 |
for feeding it code or otherwise making it do things, but it also has |
5160 |
functions for its own use. This smells a lot like an object, and |
5161 |
there are ways for you to build Perl so that you can have multiple |
5162 |
interpreters, with one interpreter represented either as a C structure, |
5163 |
or inside a thread-specific structure. These structures contain all |
5164 |
the context, the state of that interpreter. |
5165 |
|
5166 |
=end original |
5167 |
|
5168 |
Perl インタプリタはブラックボックスとして扱われます: コードに与えたり、 |
5169 |
何かをするための API がありますが、自分自身で使うための関数もあります。 |
5170 |
これはオブジェクトのような匂いがして、それぞれを C の構造体や |
5171 |
スレッド固有の構造体の内部として表現する、複数のインタプリタを使えるように |
5172 |
Perl をビルドするための方法があります。 |
5173 |
これらの構造体はそのインタプリタの全てのコンテキストと状態を含みます。 |
5174 |
|
5175 |
=begin original |
5176 |
|
5177 |
One macro controls the major Perl build flavor: MULTIPLICITY. The |
5178 |
MULTIPLICITY build has a C structure that packages all the interpreter |
5179 |
state. With multiplicity-enabled perls, PERL_IMPLICIT_CONTEXT is also |
5180 |
normally defined, and enables the support for passing in a "hidden" first |
5181 |
argument that represents all three data structures. MULTIPLICITY makes |
5182 |
multi-threaded perls possible (with the ithreads threading model, related |
5183 |
to the macro USE_ITHREADS.) |
5184 |
|
5185 |
=end original |
5186 |
|
5187 |
一つのマクロは主な Perl ビルド設定: MULTIPLICITY です。 |
5188 |
MULTIPLICITY ビルドは全てのインタプリタ状態をパッケージした C の構造体を |
5189 |
持ちます。 |
5190 |
MULTIPLICITY を遊行した perl では、PERL_IMPLICIT_CONTEXT も普通設定され、 |
5191 |
三つのデータ構造体全てを表現する「隠された」最初の引数を渡すことへの |
5192 |
対応が有効になります。 |
5193 |
MULTIPLICITY は(マクロ USE_ITHREADS に関連する ithread スレッドモデルで) |
5194 |
マルチスレッド perl を可能にします。 |
5195 |
|
5196 |
=begin original |
5197 |
|
5198 |
Two other "encapsulation" macros are the PERL_GLOBAL_STRUCT and |
5199 |
PERL_GLOBAL_STRUCT_PRIVATE (the latter turns on the former, and the |
5200 |
former turns on MULTIPLICITY.) The PERL_GLOBAL_STRUCT causes all the |
5201 |
internal variables of Perl to be wrapped inside a single global struct, |
5202 |
struct perl_vars, accessible as (globals) &PL_Vars or PL_VarsPtr or |
5203 |
the function Perl_GetVars(). The PERL_GLOBAL_STRUCT_PRIVATE goes |
5204 |
one step further, there is still a single struct (allocated in main() |
5205 |
either from heap or from stack) but there are no global data symbols |
5206 |
pointing to it. In either case the global struct should be initialized |
5207 |
as the very first thing in main() using Perl_init_global_struct() and |
5208 |
correspondingly tear it down after perl_free() using Perl_free_global_struct(), |
5209 |
please see F<miniperlmain.c> for usage details. You may also need |
5210 |
to use C<dVAR> in your coding to "declare the global variables" |
5211 |
when you are using them. dTHX does this for you automatically. |
5212 |
|
5213 |
=end original |
5214 |
|
5215 |
あと二つの「カプセル化」マクロは PERL_GLOBAL_STRUCT と |
5216 |
PERL_GLOBAL_STRUCT_PRIVATE です(後者は前者を有効にして、前者は |
5217 |
MULTIPLICITY を有効にします。) |
5218 |
PERL_GLOBAL_STRUCT は Perl の全ての内部変数を一つグローバル構造体である |
5219 |
struct perl_vars にラップして、(グローバルに) &PL_Vars, PL_VarsPtr, |
5220 |
Perl_GetVars() 関数でアクセスできます。 |
5221 |
PERL_GLOBAL_STRUCT_PRIVATE はもう一歩進めて、やはり(main() でヒープか |
5222 |
スタックに割り当てられた)一つの構造体ですが、これを示すグローバルな |
5223 |
データシンボルはありません。 |
5224 |
どちらの場合でもグローバルな構造体は Perl_init_global_struct() を使って |
5225 |
main() の最初で初期化され、Perl_free_global_struct() を使って perl_free() の |
5226 |
後で解放されます; 詳細な使用法については F<miniperlmain.c> を |
5227 |
参照してください。 |
5228 |
これらを使う時、「グローバル変数を宣言する」ためにコード中で C<dVAR> を |
5229 |
使う必要があるかもしれません。 |
5230 |
dTHX はこれを自動的に行います。 |
5231 |
|
5232 |
=begin original |
5233 |
|
5234 |
To see whether you have non-const data you can use a BSD-compatible C<nm>: |
5235 |
|
5236 |
=end original |
5237 |
|
5238 |
非 const データがあるかどうかを見るには、BSD 互換の C<nm> を使えます: |
5239 |
|
5240 |
nm libperl.a | grep -v ' [TURtr] ' |
5241 |
|
5242 |
=begin original |
5243 |
|
5244 |
If this displays any C<D> or C<d> symbols, you have non-const data. |
5245 |
|
5246 |
=end original |
5247 |
|
5248 |
C<D> または C<d> シンボルが表示されたら、非 const データがあります。 |
5249 |
|
5250 |
=begin original |
5251 |
|
5252 |
For backward compatibility reasons defining just PERL_GLOBAL_STRUCT |
5253 |
doesn't actually hide all symbols inside a big global struct: some |
5254 |
PerlIO_xxx vtables are left visible. The PERL_GLOBAL_STRUCT_PRIVATE |
5255 |
then hides everything (see how the PERLIO_FUNCS_DECL is used). |
5256 |
|
5257 |
=end original |
5258 |
|
5259 |
後方互換性のために、単に PERL_GLOBAL_STRUCT を定義しただけでは |
5260 |
大きなグローバル構造体の全てのシンボルは隠れません: いくつかの |
5261 |
PerlIO_xxx vtables は見えるままです。 |
5262 |
PERL_GLOBAL_STRUCT_PRIVATE は全てを隠します ( PERLIO_FUNCS_DECL の |
5263 |
使い方を参照してください)。 |
5264 |
|
5265 |
=begin original |
5266 |
|
5267 |
All this obviously requires a way for the Perl internal functions to be |
5268 |
either subroutines taking some kind of structure as the first |
5269 |
argument, or subroutines taking nothing as the first argument. To |
5270 |
enable these two very different ways of building the interpreter, |
5271 |
the Perl source (as it does in so many other situations) makes heavy |
5272 |
use of macros and subroutine naming conventions. |
5273 |
|
5274 |
=end original |
5275 |
|
5276 |
これら全ては明らかに、Perl 内部関数を、ある種の構造体を最初の引数として取る |
5277 |
サブルーチンか、最初の引数に何も取らないサブルーチンにする方法が必要です。 |
5278 |
インタプリタのビルドをかなり異なった方法でこれら二つを有効にするために、 |
5279 |
Perl ソースは(その他の多くの状況で行うのと同様) マクロとサブルーチンの |
5280 |
命名規則を激しく使っています。 |
5281 |
|
5282 |
=begin original |
5283 |
|
5284 |
First problem: deciding which functions will be public API functions and |
5285 |
which will be private. All functions whose names begin C<S_> are private |
5286 |
(think "S" for "secret" or "static"). All other functions begin with |
5287 |
"Perl_", but just because a function begins with "Perl_" does not mean it is |
5288 |
part of the API. (See L</Internal |
5289 |
Functions>.) The easiest way to be B<sure> a |
5290 |
function is part of the API is to find its entry in L<perlapi>. |
5291 |
If it exists in L<perlapi>, it's part of the API. If it doesn't, and you |
5292 |
think it should be (i.e., you need it for your extension), send mail via |
5293 |
L<perlbug> explaining why you think it should be. |
5294 |
|
5295 |
=end original |
5296 |
|
5297 |
最初の問題: どの関数が公的な API 関数になる関数で、どの関数が |
5298 |
プライベートかを決定する。 |
5299 |
名前が C<S_> で始まる全ての関数はプライベートです ("S" は "secret" または |
5300 |
"static" と考えてください)。 |
5301 |
その他の全ての関数は "Perl_" で始まりますが、"Perl_" で始まっているからと |
5302 |
いって API の一部とは限りません。 |
5303 |
(L</Internal Functions> を参照してください。) |
5304 |
関数が API の一部であることを B<確認する> 最も簡単な方法は、 |
5305 |
L<perlapi> からエントリを探すことです。 |
5306 |
もし L<perlapi> にあれば、API の一部です。 |
5307 |
もしなくて、あなたが これは API であるべきと考える(つまり、あなたの |
5308 |
エクステンションに必要)なら、どうしてそう考えるかを説明したメールを |
5309 |
L<perlbug> で送ってください。 |
5310 |
|
5311 |
=begin original |
5312 |
|
5313 |
Second problem: there must be a syntax so that the same subroutine |
5314 |
declarations and calls can pass a structure as their first argument, |
5315 |
or pass nothing. To solve this, the subroutines are named and |
5316 |
declared in a particular way. Here's a typical start of a static |
5317 |
function used within the Perl guts: |
5318 |
|
5319 |
=end original |
5320 |
|
5321 |
二番目の問題: 同じサブルーチン定義と呼び出しが最初の引数として構造体を |
5322 |
渡せるようにするか、何も渡さないようにする文法でなければなりません。 |
5323 |
問題を解決するために、サブルーチンは決められた方法で命名して宣言されます。 |
5324 |
以下は、Perl の内部で使われている静的関数の典型的な開始部分です: |
5325 |
|
5326 |
STATIC void |
5327 |
S_incline(pTHX_ char *s) |
5328 |
|
5329 |
=begin original |
5330 |
|
5331 |
STATIC becomes "static" in C, and may be #define'd to nothing in some |
5332 |
configurations in the future. |
5333 |
|
5334 |
=end original |
5335 |
|
5336 |
STATIC は C では "static" になり、将来一部の設定では何もしないように |
5337 |
#define されます。 |
5338 |
|
5339 |
=begin original |
5340 |
|
5341 |
A public function (i.e. part of the internal API, but not necessarily |
5342 |
sanctioned for use in extensions) begins like this: |
5343 |
|
5344 |
=end original |
5345 |
|
5346 |
公的な関数(つまり内部 API の一部ですが、エクステンションで使うのに許可は |
5347 |
不要なもの)は以下のように始まります: |
5348 |
|
5349 |
void |
5350 |
Perl_sv_setiv(pTHX_ SV* dsv, IV num) |
5351 |
|
5352 |
=begin original |
5353 |
|
5354 |
C<pTHX_> is one of a number of macros (in F<perl.h>) that hide the |
5355 |
details of the interpreter's context. THX stands for "thread", "this", |
5356 |
or "thingy", as the case may be. (And no, George Lucas is not involved. :-) |
5357 |
The first character could be 'p' for a B<p>rototype, 'a' for B<a>rgument, |
5358 |
or 'd' for B<d>eclaration, so we have C<pTHX>, C<aTHX> and C<dTHX>, and |
5359 |
their variants. |
5360 |
|
5361 |
=end original |
5362 |
|
5363 |
C<pTHX_> は、インタプリタのコンテキストの詳細を隠すための(F<perl.h> にある) |
5364 |
多くのマクロの一つです。 |
5365 |
THX は "thread", "this", "thingy" などから来ています。 |
5366 |
(そしてジョージルーカスは関係ありません。:-) |
5367 |
最初の文字は 'p' がプロトタイプ(B<p>rototype)、'a' が引数(B<a>rgument)、 |
5368 |
'd' が宣言(B<d>eclaration) を意味するので、C<pTHX>, C<aTHX>, C<dTHX> および |
5369 |
その変形があります。 |
5370 |
|
5371 |
=begin original |
5372 |
|
5373 |
When Perl is built without options that set PERL_IMPLICIT_CONTEXT, there is no |
5374 |
first argument containing the interpreter's context. The trailing underscore |
5375 |
in the pTHX_ macro indicates that the macro expansion needs a comma |
5376 |
after the context argument because other arguments follow it. If |
5377 |
PERL_IMPLICIT_CONTEXT is not defined, pTHX_ will be ignored, and the |
5378 |
subroutine is not prototyped to take the extra argument. The form of the |
5379 |
macro without the trailing underscore is used when there are no additional |
5380 |
explicit arguments. |
5381 |
|
5382 |
=end original |
5383 |
|
5384 |
PERL_IMPLICIT_CONTEXT が設定されたオプションなしで Perl がビルドされると、 |
5385 |
インタプリタのコンテキストに最初の引数は含まれません。 |
5386 |
pTHX_ マクロの末尾の下線は、他の引数が引き続くのでマクロ拡張はコンテキスト |
5387 |
引数の後にカンマが必要であることを示しています。 |
5388 |
PERL_IMPLICIT_CONTEXT が定義されていない場合、pTHX_ は無視され、 |
5389 |
サブルーチンは追加の引数を取るようなプロトタイプを持ちません。 |
5390 |
引き続く下線なしのマクロの形式は、追加の明示的な引数がない場合に使われます。 |
5391 |
|
5392 |
=begin original |
5393 |
|
5394 |
When a core function calls another, it must pass the context. This |
5395 |
is normally hidden via macros. Consider C<sv_setiv>. It expands into |
5396 |
something like this: |
5397 |
|
5398 |
=end original |
5399 |
|
5400 |
コア関数が他の関数を呼び出すとき、コンテキストを渡さなければなりません。 |
5401 |
これは普通マクロ経由で隠されます。 |
5402 |
C<sv_setiv> を考えてみます。 |
5403 |
これは以下のような感じに展開されます: |
5404 |
|
5405 |
#ifdef PERL_IMPLICIT_CONTEXT |
5406 |
#define sv_setiv(a,b) Perl_sv_setiv(aTHX_ a, b) |
5407 |
/* can't do this for vararg functions, see below */ |
5408 |
#else |
5409 |
#define sv_setiv Perl_sv_setiv |
5410 |
#endif |
5411 |
|
5412 |
=begin original |
5413 |
|
5414 |
This works well, and means that XS authors can gleefully write: |
5415 |
|
5416 |
=end original |
5417 |
|
5418 |
これはうまく動きますし、XS 作者は喜んで以下のように書けます: |
5419 |
|
5420 |
sv_setiv(foo, bar); |
5421 |
|
5422 |
=begin original |
5423 |
|
5424 |
and still have it work under all the modes Perl could have been |
5425 |
compiled with. |
5426 |
|
5427 |
=end original |
5428 |
|
5429 |
そしてやはり Perl がコンパイルされる全てのモードで動作します。 |
5430 |
|
5431 |
=begin original |
5432 |
|
5433 |
This doesn't work so cleanly for varargs functions, though, as macros |
5434 |
imply that the number of arguments is known in advance. Instead we |
5435 |
either need to spell them out fully, passing C<aTHX_> as the first |
5436 |
argument (the Perl core tends to do this with functions like |
5437 |
Perl_warner), or use a context-free version. |
5438 |
|
5439 |
=end original |
5440 |
|
5441 |
しかし、可変長引数関数ではそれほどきれいには動作しません; マクロは事前に |
5442 |
引数の数が分かっていることを仮定しているからです。 |
5443 |
どちらかを完全に綴る必要があるようにする代わりに、最初の引数として |
5444 |
C<aTHX_> を渡す(Perl コアは Perl_warner のような関数でこれをする |
5445 |
傾向があります)か、コンテキストの影響を受けないバージョンを使います。 |
5446 |
|
5447 |
=begin original |
5448 |
|
5449 |
The context-free version of Perl_warner is called |
5450 |
Perl_warner_nocontext, and does not take the extra argument. Instead |
5451 |
it does dTHX; to get the context from thread-local storage. We |
5452 |
C<#define warner Perl_warner_nocontext> so that extensions get source |
5453 |
compatibility at the expense of performance. (Passing an arg is |
5454 |
cheaper than grabbing it from thread-local storage.) |
5455 |
|
5456 |
=end original |
5457 |
|
5458 |
Perl_warner のコンテキストの影響を受けないバージョンは |
5459 |
Perl_warner_nocontext と呼ばれ、追加の引数を取りません。 |
5460 |
代わりに、スレッドローカルなストレージからコンテキストを得るために |
5461 |
dTHX; します。 |
5462 |
エクステンションが性能のコストでソース互換性を得るために |
5463 |
C<#define warner Perl_warner_nocontext> とします。 |
5464 |
(一つの引数を渡すのはスレッドローカルなストレージから値を取り出すよりも |
5465 |
安価です。) |
5466 |
|
5467 |
=begin original |
5468 |
|
5469 |
You can ignore [pad]THXx when browsing the Perl headers/sources. |
5470 |
Those are strictly for use within the core. Extensions and embedders |
5471 |
need only be aware of [pad]THX. |
5472 |
|
5473 |
=end original |
5474 |
|
5475 |
Perl ヘッダ/ソースを見るときには [pad]THXx を無視できます。 |
5476 |
これらは純粋にコア内部での使用のためのものです。 |
5477 |
エクステンションと組み込みだけが [pad]THX の存在を汁必要があります。 |
5478 |
|
5479 |
=head2 So what happened to dTHR? |
5480 |
|
5481 |
(それで dTHR に何が起こるの?) |
5482 |
|
5483 |
=begin original |
5484 |
|
5485 |
C<dTHR> was introduced in perl 5.005 to support the older thread model. |
5486 |
The older thread model now uses the C<THX> mechanism to pass context |
5487 |
pointers around, so C<dTHR> is not useful any more. Perl 5.6.0 and |
5488 |
later still have it for backward source compatibility, but it is defined |
5489 |
to be a no-op. |
5490 |
|
5491 |
=end original |
5492 |
|
5493 |
C<dTHR> は、古いスレッドモデルに対応するために perl 5.005 で導入されました。 |
5494 |
古いスレッドモデルは今ではコンテキストのポインタを渡すのに C<THX> 機構を |
5495 |
使うので、C<dTHR> はもはや有用ではありません。 |
5496 |
Perl 5.6.0 以降では、ソースの後方互換性のためにまだ存在していますが、 |
5497 |
何もしないように定義されています。 |
5498 |
|
5499 |
=head2 How do I use all this in extensions? |
5500 |
|
5501 |
(これら全てをエクステンションで使うには?) |
5502 |
|
5503 |
=begin original |
5504 |
|
5505 |
When Perl is built with PERL_IMPLICIT_CONTEXT, extensions that call |
5506 |
any functions in the Perl API will need to pass the initial context |
5507 |
argument somehow. The kicker is that you will need to write it in |
5508 |
such a way that the extension still compiles when Perl hasn't been |
5509 |
built with PERL_IMPLICIT_CONTEXT enabled. |
5510 |
|
5511 |
=end original |
5512 |
|
5513 |
Perl が PERL_IMPLICIT_CONTEXT 付きでビルドされると、Perl API の関数を |
5514 |
呼び出すエクステンションは何か初期コンテキスト引数を渡す必要があります。 |
5515 |
キッカーは、Perl が PERL_IMPLICIT_CONTEXT を有効にせずにビルドされたときにも |
5516 |
エクステンションがコンパイルできるようにそれを書く方法が必要ということです。 |
5517 |
|
5518 |
=begin original |
5519 |
|
5520 |
There are three ways to do this. First, the easy but inefficient way, |
5521 |
which is also the default, in order to maintain source compatibility |
5522 |
with extensions: whenever F<XSUB.h> is #included, it redefines the aTHX |
5523 |
and aTHX_ macros to call a function that will return the context. |
5524 |
Thus, something like: |
5525 |
|
5526 |
=end original |
5527 |
|
5528 |
これをするには三つの方法があります。 |
5529 |
最初に、簡単だけれども効率的ではない方法ですが、エクステンションのソース |
5530 |
互換性を維持するために、これがデフォルトです: F<XSUB.h> が #include されると、 |
5531 |
コンテキストを返す関数を呼び出すように aTHX と aTHX_ のマクロを再定義します。 |
5532 |
従って、以下のようなものが: |
5533 |
|
5534 |
sv_setiv(sv, num); |
5535 |
|
5536 |
=begin original |
5537 |
|
5538 |
in your extension will translate to this when PERL_IMPLICIT_CONTEXT is |
5539 |
in effect: |
5540 |
|
5541 |
=end original |
5542 |
|
5543 |
エクステンションにあると、PERL_IMPLICIT_CONTEXT が有効なら、以下のように |
5544 |
翻訳します: |
5545 |
|
5546 |
Perl_sv_setiv(Perl_get_context(), sv, num); |
5547 |
|
5548 |
=begin original |
5549 |
|
5550 |
or to this otherwise: |
5551 |
|
5552 |
=end original |
5553 |
|
5554 |
さもなければ、こうなります: |
5555 |
|
5556 |
Perl_sv_setiv(sv, num); |
5557 |
|
5558 |
=begin original |
5559 |
|
5560 |
You don't have to do anything new in your extension to get this; since |
5561 |
the Perl library provides Perl_get_context(), it will all just |
5562 |
work. |
5563 |
|
5564 |
=end original |
5565 |
|
5566 |
これをするためにエクステンション何の新しいこともする必要はありません; |
5567 |
Perl ライブラリは Perl_get_context() を提供するので、全てうまく動作します。 |
5568 |
|
5569 |
=begin original |
5570 |
|
5571 |
The second, more efficient way is to use the following template for |
5572 |
your Foo.xs: |
5573 |
|
5574 |
=end original |
5575 |
|
5576 |
次に、より効率的な方法は、Foo.xs に以下のテンプレートを使うことです: |
5577 |
|
5578 |
#define PERL_NO_GET_CONTEXT /* we want efficiency */ |
5579 |
#include "EXTERN.h" |
5580 |
#include "perl.h" |
5581 |
#include "XSUB.h" |
5582 |
|
5583 |
STATIC void my_private_function(int arg1, int arg2); |
5584 |
|
5585 |
STATIC void |
5586 |
my_private_function(int arg1, int arg2) |
5587 |
{ |
5588 |
dTHX; /* fetch context */ |
5589 |
... call many Perl API functions ... |
5590 |
} |
5591 |
|
5592 |
[... etc ...] |
5593 |
|
5594 |
MODULE = Foo PACKAGE = Foo |
5595 |
|
5596 |
/* typical XSUB */ |
5597 |
|
5598 |
void |
5599 |
my_xsub(arg) |
5600 |
int arg |
5601 |
CODE: |
5602 |
my_private_function(arg, 10); |
5603 |
|
5604 |
=begin original |
5605 |
|
5606 |
Note that the only two changes from the normal way of writing an |
5607 |
extension is the addition of a C<#define PERL_NO_GET_CONTEXT> before |
5608 |
including the Perl headers, followed by a C<dTHX;> declaration at |
5609 |
the start of every function that will call the Perl API. (You'll |
5610 |
know which functions need this, because the C compiler will complain |
5611 |
that there's an undeclared identifier in those functions.) No changes |
5612 |
are needed for the XSUBs themselves, because the XS() macro is |
5613 |
correctly defined to pass in the implicit context if needed. |
5614 |
|
5615 |
=end original |
5616 |
|
5617 |
エクステンションを書く通常の方法とただ二つの違いは、Perl ヘッダを |
5618 |
インクルードする前に C<#define PERL_NO_GET_CONTEXT> を追加して、 |
5619 |
Perl API を呼び出す全ての関数の先頭に C<dTHX;> 宣言を書くということに |
5620 |
注意してください。 |
5621 |
(どの関数にこれが必要なのかは分かります; これらの関数に未宣言の識別子があると |
5622 |
C コンパイラがエラーを出すからです。) |
5623 |
XSUB 自身には変更は必要ありません; なぜなら XS() マクロは、もし必要なら |
5624 |
暗黙のコンテキストを渡すように正しく定義されるからです。 |
5625 |
|
5626 |
=begin original |
5627 |
|
5628 |
The third, even more efficient way is to ape how it is done within |
5629 |
the Perl guts: |
5630 |
|
5631 |
=end original |
5632 |
|
5633 |
3 番目に、さらに効率的な方法は、Perl の内部で行われている方法を |
5634 |
真似ることです: |
5635 |
|
5636 |
#define PERL_NO_GET_CONTEXT /* we want efficiency */ |
5637 |
#include "EXTERN.h" |
5638 |
#include "perl.h" |
5639 |
#include "XSUB.h" |
5640 |
|
5641 |
/* pTHX_ only needed for functions that call Perl API */ |
5642 |
STATIC void my_private_function(pTHX_ int arg1, int arg2); |
5643 |
|
5644 |
STATIC void |
5645 |
my_private_function(pTHX_ int arg1, int arg2) |
5646 |
{ |
5647 |
/* dTHX; not needed here, because THX is an argument */ |
5648 |
... call Perl API functions ... |
5649 |
} |
5650 |
|
5651 |
[... etc ...] |
5652 |
|
5653 |
MODULE = Foo PACKAGE = Foo |
5654 |
|
5655 |
/* typical XSUB */ |
5656 |
|
5657 |
void |
5658 |
my_xsub(arg) |
5659 |
int arg |
5660 |
CODE: |
5661 |
my_private_function(aTHX_ arg, 10); |
5662 |
|
5663 |
=begin original |
5664 |
|
5665 |
This implementation never has to fetch the context using a function |
5666 |
call, since it is always passed as an extra argument. Depending on |
5667 |
your needs for simplicity or efficiency, you may mix the previous |
5668 |
two approaches freely. |
5669 |
|
5670 |
=end original |
5671 |
|
5672 |
この実装は、関数呼び出しを使ってコンテキストを取得する必要はありません; |
5673 |
なぜなら常に追加の引数として渡されるからです。 |
5674 |
単純さと効率性のどちらが必要かに応じて、前述の二つの手法と自由に |
5675 |
混ぜてもかまいません。 |
5676 |
|
5677 |
=begin original |
5678 |
|
5679 |
Never add a comma after C<pTHX> yourself--always use the form of the |
5680 |
macro with the underscore for functions that take explicit arguments, |
5681 |
or the form without the argument for functions with no explicit arguments. |
5682 |
|
5683 |
=end original |
5684 |
|
5685 |
C<pTHX> の後ろに自分でカンマを追加しないでください -- 明示的な引数を |
5686 |
取る関数の場合は下線のあるマクロの形式を、明示的な引数のない関数では |
5687 |
引数なしの形式を、常に使ってください。 |
5688 |
|
5689 |
=begin original |
5690 |
|
5691 |
If one is compiling Perl with the C<-DPERL_GLOBAL_STRUCT> the C<dVAR> |
5692 |
definition is needed if the Perl global variables (see F<perlvars.h> |
5693 |
or F<globvar.sym>) are accessed in the function and C<dTHX> is not |
5694 |
used (the C<dTHX> includes the C<dVAR> if necessary). One notices |
5695 |
the need for C<dVAR> only with the said compile-time define, because |
5696 |
otherwise the Perl global variables are visible as-is. |
5697 |
|
5698 |
=end original |
5699 |
|
5700 |
C<-DPERL_GLOBAL_STRUCT> 付きで Perl をコンパイルすると、Perl グローバル変数 |
5701 |
(F<perlvars.h> や F<globvar.sym> を参照)が関数内でアクセスされて、 |
5702 | |