This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
PERL_OBJECT build tweaks
[perl5.git] / pod / perlguts.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
954c1994 3perlguts - Introduction to the Perl API
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
954c1994
GS
7This document attempts to describe how to use the Perl API, as well as containing
8some info on the basic workings of the Perl core. It is far from complete
9and probably contains many errors. Please refer any questions or
10comments to the author below.
a0d0e21e 11
0a753a76
PP
12=head1 Variables
13
5f05dabc 14=head2 Datatypes
a0d0e21e
LW
15
16Perl has three typedefs that handle Perl's three main data types:
17
18 SV Scalar Value
19 AV Array Value
20 HV Hash Value
21
d1b91892 22Each typedef has specific routines that manipulate the various data types.
a0d0e21e
LW
23
24=head2 What is an "IV"?
25
954c1994 26Perl uses a special typedef IV which is a simple signed integer type that is
5f05dabc 27guaranteed to be large enough to hold a pointer (as well as an integer).
954c1994 28Additionally, there is the UV, which is simply an unsigned IV.
a0d0e21e 29
d1b91892 30Perl also uses two special typedefs, I32 and I16, which will always be at
954c1994
GS
31least 32-bits and 16-bits long, respectively. (Again, there are U32 and U16,
32as well.)
a0d0e21e 33
54310121 34=head2 Working with SVs
a0d0e21e
LW
35
36An SV can be created and loaded with one command. There are four types of
37values that can be loaded: an integer value (IV), a double (NV), a string,
38(PV), and another scalar (SV).
39
9da1e3b5 40The six routines are:
a0d0e21e
LW
41
42 SV* newSViv(IV);
43 SV* newSVnv(double);
08105a92
GS
44 SV* newSVpv(const char*, int);
45 SV* newSVpvn(const char*, int);
46fc3d4c 46 SV* newSVpvf(const char*, ...);
a0d0e21e
LW
47 SV* newSVsv(SV*);
48
deb3007b 49To change the value of an *already-existing* SV, there are seven routines:
a0d0e21e
LW
50
51 void sv_setiv(SV*, IV);
deb3007b 52 void sv_setuv(SV*, UV);
a0d0e21e 53 void sv_setnv(SV*, double);
08105a92
GS
54 void sv_setpv(SV*, const char*);
55 void sv_setpvn(SV*, const char*, int)
46fc3d4c 56 void sv_setpvf(SV*, const char*, ...);
9abd00ed 57 void sv_setpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
a0d0e21e
LW
58 void sv_setsv(SV*, SV*);
59
60Notice that you can choose to specify the length of the string to be
9da1e3b5
MUN
61assigned by using C<sv_setpvn>, C<newSVpvn>, or C<newSVpv>, or you may
62allow Perl to calculate the length by using C<sv_setpv> or by specifying
630 as the second argument to C<newSVpv>. Be warned, though, that Perl will
64determine the string's length by using C<strlen>, which depends on the
9abd00ed
GS
65string terminating with a NUL character.
66
67The arguments of C<sv_setpvf> are processed like C<sprintf>, and the
68formatted output becomes the value.
69
70C<sv_setpvfn> is an analogue of C<vsprintf>, but it allows you to specify
71either a pointer to a variable argument list or the address and length of
72an array of SVs. The last argument points to a boolean; on return, if that
73boolean is true, then locale-specific information has been used to format
c2611fb3 74the string, and the string's contents are therefore untrustworthy (see
9abd00ed
GS
75L<perlsec>). This pointer may be NULL if that information is not
76important. Note that this function requires you to specify the length of
77the format.
78
9da1e3b5
MUN
79The C<sv_set*()> functions are not generic enough to operate on values
80that have "magic". See L<Magic Virtual Tables> later in this document.
a0d0e21e 81
a3cb178b
GS
82All SVs that contain strings should be terminated with a NUL character.
83If it is not NUL-terminated there is a risk of
5f05dabc
PP
84core dumps and corruptions from code which passes the string to C
85functions or system calls which expect a NUL-terminated string.
86Perl's own functions typically add a trailing NUL for this reason.
87Nevertheless, you should be very careful when you pass a string stored
88in an SV to a C function or system call.
89
a0d0e21e
LW
90To access the actual value that an SV points to, you can use the macros:
91
92 SvIV(SV*)
954c1994 93 SvUV(SV*)
a0d0e21e
LW
94 SvNV(SV*)
95 SvPV(SV*, STRLEN len)
1fa8b10d 96 SvPV_nolen(SV*)
a0d0e21e 97
954c1994 98which will automatically coerce the actual scalar type into an IV, UV, double,
a0d0e21e
LW
99or string.
100
101In the C<SvPV> macro, the length of the string returned is placed into the
1fa8b10d
JD
102variable C<len> (this is a macro, so you do I<not> use C<&len>). If you do
103not care what the length of the data is, use the C<SvPV_nolen> macro.
104Historically the C<SvPV> macro with the global variable C<PL_na> has been
105used in this case. But that can be quite inefficient because C<PL_na> must
106be accessed in thread-local storage in threaded Perl. In any case, remember
107that Perl allows arbitrary strings of data that may both contain NULs and
108might not be terminated by a NUL.
a0d0e21e 109
ce2f5d8f
KA
110Also remember that C doesn't allow you to safely say C<foo(SvPV(s, len),
111len);>. It might work with your compiler, but it won't work for everyone.
112Break this sort of statement up into separate assignments:
113
b2f5ed49 114 SV *s;
ce2f5d8f
KA
115 STRLEN len;
116 char * ptr;
b2f5ed49 117 ptr = SvPV(s, len);
ce2f5d8f
KA
118 foo(ptr, len);
119
07fa94a1 120If you want to know if the scalar value is TRUE, you can use:
a0d0e21e
LW
121
122 SvTRUE(SV*)
123
124Although Perl will automatically grow strings for you, if you need to force
125Perl to allocate more memory for your SV, you can use the macro
126
127 SvGROW(SV*, STRLEN newlen)
128
129which will determine if more memory needs to be allocated. If so, it will
130call the function C<sv_grow>. Note that C<SvGROW> can only increase, not
5f05dabc
PP
131decrease, the allocated memory of an SV and that it does not automatically
132add a byte for the a trailing NUL (perl's own string functions typically do
8ebc5c01 133C<SvGROW(sv, len + 1)>).
a0d0e21e
LW
134
135If you have an SV and want to know what kind of data Perl thinks is stored
136in it, you can use the following macros to check the type of SV you have.
137
138 SvIOK(SV*)
139 SvNOK(SV*)
140 SvPOK(SV*)
141
142You can get and set the current length of the string stored in an SV with
143the following macros:
144
145 SvCUR(SV*)
146 SvCUR_set(SV*, I32 val)
147
cb1a09d0
AD
148You can also get a pointer to the end of the string stored in the SV
149with the macro:
150
151 SvEND(SV*)
152
153But note that these last three macros are valid only if C<SvPOK()> is true.
a0d0e21e 154
d1b91892
AD
155If you want to append something to the end of string stored in an C<SV*>,
156you can use the following functions:
157
08105a92 158 void sv_catpv(SV*, const char*);
e65f3abd 159 void sv_catpvn(SV*, const char*, STRLEN);
46fc3d4c 160 void sv_catpvf(SV*, const char*, ...);
9abd00ed 161 void sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
d1b91892
AD
162 void sv_catsv(SV*, SV*);
163
164The first function calculates the length of the string to be appended by
165using C<strlen>. In the second, you specify the length of the string
46fc3d4c 166yourself. The third function processes its arguments like C<sprintf> and
9abd00ed
GS
167appends the formatted output. The fourth function works like C<vsprintf>.
168You can specify the address and length of an array of SVs instead of the
169va_list argument. The fifth function extends the string stored in the first
170SV with the string stored in the second SV. It also forces the second SV
171to be interpreted as a string.
172
173The C<sv_cat*()> functions are not generic enough to operate on values that
174have "magic". See L<Magic Virtual Tables> later in this document.
d1b91892 175
a0d0e21e
LW
176If you know the name of a scalar variable, you can get a pointer to its SV
177by using the following:
178
4929bf7b 179 SV* get_sv("package::varname", FALSE);
a0d0e21e
LW
180
181This returns NULL if the variable does not exist.
182
d1b91892 183If you want to know if this variable (or any other SV) is actually C<defined>,
a0d0e21e
LW
184you can call:
185
186 SvOK(SV*)
187
9cde0e7f 188The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>. Its
a0d0e21e
LW
189address can be used whenever an C<SV*> is needed.
190
9cde0e7f
GS
191There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain Boolean
192TRUE and FALSE values, respectively. Like C<PL_sv_undef>, their addresses can
a0d0e21e
LW
193be used whenever an C<SV*> is needed.
194
9cde0e7f 195Do not be fooled into thinking that C<(SV *) 0> is the same as C<&PL_sv_undef>.
a0d0e21e
LW
196Take this code:
197
198 SV* sv = (SV*) 0;
199 if (I-am-to-return-a-real-value) {
200 sv = sv_2mortal(newSViv(42));
201 }
202 sv_setsv(ST(0), sv);
203
204This code tries to return a new SV (which contains the value 42) if it should
04343c6d 205return a real value, or undef otherwise. Instead it has returned a NULL
a0d0e21e 206pointer which, somewhere down the line, will cause a segmentation violation,
9cde0e7f 207bus error, or just weird results. Change the zero to C<&PL_sv_undef> in the first
5f05dabc 208line and all will be well.
a0d0e21e
LW
209
210To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
3fe9a6f1 211call is not necessary (see L<Reference Counts and Mortality>).
a0d0e21e 212
d1b91892 213=head2 What's Really Stored in an SV?
a0d0e21e
LW
214
215Recall that the usual method of determining the type of scalar you have is
5f05dabc 216to use C<Sv*OK> macros. Because a scalar can be both a number and a string,
d1b91892 217usually these macros will always return TRUE and calling the C<Sv*V>
a0d0e21e
LW
218macros will do the appropriate conversion of string to integer/double or
219integer/double to string.
220
221If you I<really> need to know if you have an integer, double, or string
222pointer in an SV, you can use the following three macros instead:
223
224 SvIOKp(SV*)
225 SvNOKp(SV*)
226 SvPOKp(SV*)
227
228These will tell you if you truly have an integer, double, or string pointer
d1b91892 229stored in your SV. The "p" stands for private.
a0d0e21e 230
07fa94a1 231In general, though, it's best to use the C<Sv*V> macros.
a0d0e21e 232
54310121 233=head2 Working with AVs
a0d0e21e 234
07fa94a1
JO
235There are two ways to create and load an AV. The first method creates an
236empty AV:
a0d0e21e
LW
237
238 AV* newAV();
239
54310121 240The second method both creates the AV and initially populates it with SVs:
a0d0e21e
LW
241
242 AV* av_make(I32 num, SV **ptr);
243
5f05dabc 244The second argument points to an array containing C<num> C<SV*>'s. Once the
54310121 245AV has been created, the SVs can be destroyed, if so desired.
a0d0e21e 246
54310121 247Once the AV has been created, the following operations are possible on AVs:
a0d0e21e
LW
248
249 void av_push(AV*, SV*);
250 SV* av_pop(AV*);
251 SV* av_shift(AV*);
252 void av_unshift(AV*, I32 num);
253
254These should be familiar operations, with the exception of C<av_unshift>.
255This routine adds C<num> elements at the front of the array with the C<undef>
256value. You must then use C<av_store> (described below) to assign values
257to these new elements.
258
259Here are some other functions:
260
5f05dabc 261 I32 av_len(AV*);
a0d0e21e 262 SV** av_fetch(AV*, I32 key, I32 lval);
a0d0e21e 263 SV** av_store(AV*, I32 key, SV* val);
a0d0e21e 264
5f05dabc
PP
265The C<av_len> function returns the highest index value in array (just
266like $#array in Perl). If the array is empty, -1 is returned. The
267C<av_fetch> function returns the value at index C<key>, but if C<lval>
268is non-zero, then C<av_fetch> will store an undef value at that index.
04343c6d
GS
269The C<av_store> function stores the value C<val> at index C<key>, and does
270not increment the reference count of C<val>. Thus the caller is responsible
271for taking care of that, and if C<av_store> returns NULL, the caller will
272have to decrement the reference count to avoid a memory leak. Note that
273C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s as their
274return value.
d1b91892 275
a0d0e21e 276 void av_clear(AV*);
a0d0e21e 277 void av_undef(AV*);
cb1a09d0 278 void av_extend(AV*, I32 key);
5f05dabc
PP
279
280The C<av_clear> function deletes all the elements in the AV* array, but
281does not actually delete the array itself. The C<av_undef> function will
282delete all the elements in the array plus the array itself. The
adc882cf
GS
283C<av_extend> function extends the array so that it contains at least C<key+1>
284elements. If C<key+1> is less than the currently allocated length of the array,
285then nothing is done.
a0d0e21e
LW
286
287If you know the name of an array variable, you can get a pointer to its AV
288by using the following:
289
4929bf7b 290 AV* get_av("package::varname", FALSE);
a0d0e21e
LW
291
292This returns NULL if the variable does not exist.
293
04343c6d
GS
294See L<Understanding the Magic of Tied Hashes and Arrays> for more
295information on how to use the array access functions on tied arrays.
296
54310121 297=head2 Working with HVs
a0d0e21e
LW
298
299To create an HV, you use the following routine:
300
301 HV* newHV();
302
54310121 303Once the HV has been created, the following operations are possible on HVs:
a0d0e21e 304
08105a92
GS
305 SV** hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash);
306 SV** hv_fetch(HV*, const char* key, U32 klen, I32 lval);
a0d0e21e 307
5f05dabc
PP
308The C<klen> parameter is the length of the key being passed in (Note that
309you cannot pass 0 in as a value of C<klen> to tell Perl to measure the
310length of the key). The C<val> argument contains the SV pointer to the
54310121 311scalar being stored, and C<hash> is the precomputed hash value (zero if
5f05dabc
PP
312you want C<hv_store> to calculate it for you). The C<lval> parameter
313indicates whether this fetch is actually a part of a store operation, in
314which case a new undefined value will be added to the HV with the supplied
315key and C<hv_fetch> will return as if the value had already existed.
a0d0e21e 316
5f05dabc
PP
317Remember that C<hv_store> and C<hv_fetch> return C<SV**>'s and not just
318C<SV*>. To access the scalar value, you must first dereference the return
319value. However, you should check to make sure that the return value is
320not NULL before dereferencing it.
a0d0e21e
LW
321
322These two functions check if a hash table entry exists, and deletes it.
323
08105a92
GS
324 bool hv_exists(HV*, const char* key, U32 klen);
325 SV* hv_delete(HV*, const char* key, U32 klen, I32 flags);
a0d0e21e 326
5f05dabc
PP
327If C<flags> does not include the C<G_DISCARD> flag then C<hv_delete> will
328create and return a mortal copy of the deleted value.
329
a0d0e21e
LW
330And more miscellaneous functions:
331
332 void hv_clear(HV*);
a0d0e21e 333 void hv_undef(HV*);
5f05dabc
PP
334
335Like their AV counterparts, C<hv_clear> deletes all the entries in the hash
336table but does not actually delete the hash table. The C<hv_undef> deletes
337both the entries and the hash table itself.
a0d0e21e 338
d1b91892
AD
339Perl keeps the actual data in linked list of structures with a typedef of HE.
340These contain the actual key and value pointers (plus extra administrative
341overhead). The key is a string pointer; the value is an C<SV*>. However,
342once you have an C<HE*>, to get the actual key and value, use the routines
343specified below.
344
a0d0e21e
LW
345 I32 hv_iterinit(HV*);
346 /* Prepares starting point to traverse hash table */
347 HE* hv_iternext(HV*);
348 /* Get the next entry, and return a pointer to a
349 structure that has both the key and value */
350 char* hv_iterkey(HE* entry, I32* retlen);
351 /* Get the key from an HE structure and also return
352 the length of the key string */
cb1a09d0 353 SV* hv_iterval(HV*, HE* entry);
a0d0e21e
LW
354 /* Return a SV pointer to the value of the HE
355 structure */
cb1a09d0 356 SV* hv_iternextsv(HV*, char** key, I32* retlen);
d1b91892
AD
357 /* This convenience routine combines hv_iternext,
358 hv_iterkey, and hv_iterval. The key and retlen
359 arguments are return values for the key and its
360 length. The value is returned in the SV* argument */
a0d0e21e
LW
361
362If you know the name of a hash variable, you can get a pointer to its HV
363by using the following:
364
4929bf7b 365 HV* get_hv("package::varname", FALSE);
a0d0e21e
LW
366
367This returns NULL if the variable does not exist.
368
8ebc5c01 369The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
a0d0e21e 370
a0d0e21e 371 hash = 0;
ab192400
GS
372 while (klen--)
373 hash = (hash * 33) + *key++;
87275199 374 hash = hash + (hash >> 5); /* after 5.6 */
ab192400 375
87275199 376The last step was added in version 5.6 to improve distribution of
ab192400 377lower bits in the resulting hash value.
a0d0e21e 378
04343c6d
GS
379See L<Understanding the Magic of Tied Hashes and Arrays> for more
380information on how to use the hash access functions on tied hashes.
381
1e422769
PP
382=head2 Hash API Extensions
383
384Beginning with version 5.004, the following functions are also supported:
385
386 HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash);
387 HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash);
c47ff5f1 388
1e422769
PP
389 bool hv_exists_ent (HV* tb, SV* key, U32 hash);
390 SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);
c47ff5f1 391
1e422769
PP
392 SV* hv_iterkeysv (HE* entry);
393
394Note that these functions take C<SV*> keys, which simplifies writing
395of extension code that deals with hash structures. These functions
396also allow passing of C<SV*> keys to C<tie> functions without forcing
397you to stringify the keys (unlike the previous set of functions).
398
399They also return and accept whole hash entries (C<HE*>), making their
400use more efficient (since the hash number for a particular string
4a4eefd0
GS
401doesn't have to be recomputed every time). See L<perlapi> for detailed
402descriptions.
1e422769
PP
403
404The following macros must always be used to access the contents of hash
405entries. Note that the arguments to these macros must be simple
406variables, since they may get evaluated more than once. See
4a4eefd0 407L<perlapi> for detailed descriptions of these macros.
1e422769
PP
408
409 HePV(HE* he, STRLEN len)
410 HeVAL(HE* he)
411 HeHASH(HE* he)
412 HeSVKEY(HE* he)
413 HeSVKEY_force(HE* he)
414 HeSVKEY_set(HE* he, SV* sv)
415
416These two lower level macros are defined, but must only be used when
417dealing with keys that are not C<SV*>s:
418
419 HeKEY(HE* he)
420 HeKLEN(HE* he)
421
04343c6d
GS
422Note that both C<hv_store> and C<hv_store_ent> do not increment the
423reference count of the stored C<val>, which is the caller's responsibility.
424If these functions return a NULL value, the caller will usually have to
425decrement the reference count of C<val> to avoid a memory leak.
1e422769 426
a0d0e21e
LW
427=head2 References
428
d1b91892
AD
429References are a special type of scalar that point to other data types
430(including references).
a0d0e21e 431
07fa94a1 432To create a reference, use either of the following functions:
a0d0e21e 433
5f05dabc
PP
434 SV* newRV_inc((SV*) thing);
435 SV* newRV_noinc((SV*) thing);
a0d0e21e 436
5f05dabc 437The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. The
07fa94a1
JO
438functions are identical except that C<newRV_inc> increments the reference
439count of the C<thing>, while C<newRV_noinc> does not. For historical
440reasons, C<newRV> is a synonym for C<newRV_inc>.
441
442Once you have a reference, you can use the following macro to dereference
443the reference:
a0d0e21e
LW
444
445 SvRV(SV*)
446
447then call the appropriate routines, casting the returned C<SV*> to either an
d1b91892 448C<AV*> or C<HV*>, if required.
a0d0e21e 449
d1b91892 450To determine if an SV is a reference, you can use the following macro:
a0d0e21e
LW
451
452 SvROK(SV*)
453
07fa94a1
JO
454To discover what type of value the reference refers to, use the following
455macro and then check the return value.
d1b91892
AD
456
457 SvTYPE(SvRV(SV*))
458
459The most useful types that will be returned are:
460
461 SVt_IV Scalar
462 SVt_NV Scalar
463 SVt_PV Scalar
5f05dabc 464 SVt_RV Scalar
d1b91892
AD
465 SVt_PVAV Array
466 SVt_PVHV Hash
467 SVt_PVCV Code
5f05dabc
PP
468 SVt_PVGV Glob (possible a file handle)
469 SVt_PVMG Blessed or Magical Scalar
470
471 See the sv.h header file for more details.
d1b91892 472
cb1a09d0
AD
473=head2 Blessed References and Class Objects
474
475References are also used to support object-oriented programming. In the
476OO lexicon, an object is simply a reference that has been blessed into a
477package (or class). Once blessed, the programmer may now use the reference
478to access the various methods in the class.
479
480A reference can be blessed into a package with the following function:
481
482 SV* sv_bless(SV* sv, HV* stash);
483
484The C<sv> argument must be a reference. The C<stash> argument specifies
3fe9a6f1 485which class the reference will belong to. See
2ae324a7 486L<Stashes and Globs> for information on converting class names into stashes.
cb1a09d0
AD
487
488/* Still under construction */
489
490Upgrades rv to reference if not already one. Creates new SV for rv to
8ebc5c01
PP
491point to. If C<classname> is non-null, the SV is blessed into the specified
492class. SV is returned.
cb1a09d0 493
08105a92 494 SV* newSVrv(SV* rv, const char* classname);
cb1a09d0 495
8ebc5c01
PP
496Copies integer or double into an SV whose reference is C<rv>. SV is blessed
497if C<classname> is non-null.
cb1a09d0 498
08105a92
GS
499 SV* sv_setref_iv(SV* rv, const char* classname, IV iv);
500 SV* sv_setref_nv(SV* rv, const char* classname, NV iv);
cb1a09d0 501
5f05dabc 502Copies the pointer value (I<the address, not the string!>) into an SV whose
8ebc5c01 503reference is rv. SV is blessed if C<classname> is non-null.
cb1a09d0 504
08105a92 505 SV* sv_setref_pv(SV* rv, const char* classname, PV iv);
cb1a09d0 506
8ebc5c01
PP
507Copies string into an SV whose reference is C<rv>. Set length to 0 to let
508Perl calculate the string length. SV is blessed if C<classname> is non-null.
cb1a09d0 509
e65f3abd 510 SV* sv_setref_pvn(SV* rv, const char* classname, PV iv, STRLEN length);
cb1a09d0 511
9abd00ed
GS
512Tests whether the SV is blessed into the specified class. It does not
513check inheritance relationships.
514
08105a92 515 int sv_isa(SV* sv, const char* name);
9abd00ed
GS
516
517Tests whether the SV is a reference to a blessed object.
518
519 int sv_isobject(SV* sv);
520
521Tests whether the SV is derived from the specified class. SV can be either
522a reference to a blessed object or a string containing a class name. This
523is the function implementing the C<UNIVERSAL::isa> functionality.
524
08105a92 525 bool sv_derived_from(SV* sv, const char* name);
9abd00ed
GS
526
527To check if you've got an object derived from a specific class you have
528to write:
529
530 if (sv_isobject(sv) && sv_derived_from(sv, class)) { ... }
cb1a09d0 531
5f05dabc 532=head2 Creating New Variables
cb1a09d0 533
5f05dabc
PP
534To create a new Perl variable with an undef value which can be accessed from
535your Perl script, use the following routines, depending on the variable type.
cb1a09d0 536
4929bf7b
GS
537 SV* get_sv("package::varname", TRUE);
538 AV* get_av("package::varname", TRUE);
539 HV* get_hv("package::varname", TRUE);
cb1a09d0
AD
540
541Notice the use of TRUE as the second parameter. The new variable can now
542be set, using the routines appropriate to the data type.
543
5f05dabc
PP
544There are additional macros whose values may be bitwise OR'ed with the
545C<TRUE> argument to enable certain extra features. Those bits are:
cb1a09d0 546
5f05dabc 547 GV_ADDMULTI Marks the variable as multiply defined, thus preventing the
54310121 548 "Name <varname> used only once: possible typo" warning.
07fa94a1
JO
549 GV_ADDWARN Issues the warning "Had to create <varname> unexpectedly" if
550 the variable did not exist before the function was called.
cb1a09d0 551
07fa94a1
JO
552If you do not specify a package name, the variable is created in the current
553package.
cb1a09d0 554
5f05dabc 555=head2 Reference Counts and Mortality
a0d0e21e 556
54310121
PP
557Perl uses an reference count-driven garbage collection mechanism. SVs,
558AVs, or HVs (xV for short in the following) start their life with a
55497cff 559reference count of 1. If the reference count of an xV ever drops to 0,
07fa94a1 560then it will be destroyed and its memory made available for reuse.
55497cff
PP
561
562This normally doesn't happen at the Perl level unless a variable is
5f05dabc
PP
563undef'ed or the last variable holding a reference to it is changed or
564overwritten. At the internal level, however, reference counts can be
55497cff
PP
565manipulated with the following macros:
566
567 int SvREFCNT(SV* sv);
5f05dabc 568 SV* SvREFCNT_inc(SV* sv);
55497cff
PP
569 void SvREFCNT_dec(SV* sv);
570
571However, there is one other function which manipulates the reference
07fa94a1
JO
572count of its argument. The C<newRV_inc> function, you will recall,
573creates a reference to the specified argument. As a side effect,
574it increments the argument's reference count. If this is not what
575you want, use C<newRV_noinc> instead.
576
577For example, imagine you want to return a reference from an XSUB function.
578Inside the XSUB routine, you create an SV which initially has a reference
579count of one. Then you call C<newRV_inc>, passing it the just-created SV.
5f05dabc
PP
580This returns the reference as a new SV, but the reference count of the
581SV you passed to C<newRV_inc> has been incremented to two. Now you
07fa94a1
JO
582return the reference from the XSUB routine and forget about the SV.
583But Perl hasn't! Whenever the returned reference is destroyed, the
584reference count of the original SV is decreased to one and nothing happens.
585The SV will hang around without any way to access it until Perl itself
586terminates. This is a memory leak.
5f05dabc
PP
587
588The correct procedure, then, is to use C<newRV_noinc> instead of
faed5253
JO
589C<newRV_inc>. Then, if and when the last reference is destroyed,
590the reference count of the SV will go to zero and it will be destroyed,
07fa94a1 591stopping any memory leak.
55497cff 592
5f05dabc 593There are some convenience functions available that can help with the
54310121 594destruction of xVs. These functions introduce the concept of "mortality".
07fa94a1
JO
595An xV that is mortal has had its reference count marked to be decremented,
596but not actually decremented, until "a short time later". Generally the
597term "short time later" means a single Perl statement, such as a call to
54310121 598an XSUB function. The actual determinant for when mortal xVs have their
07fa94a1
JO
599reference count decremented depends on two macros, SAVETMPS and FREETMPS.
600See L<perlcall> and L<perlxs> for more details on these macros.
55497cff
PP
601
602"Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
603However, if you mortalize a variable twice, the reference count will
604later be decremented twice.
605
606You should be careful about creating mortal variables. Strange things
607can happen if you make the same value mortal within multiple contexts,
5f05dabc 608or if you make a variable mortal multiple times.
a0d0e21e
LW
609
610To create a mortal variable, use the functions:
611
612 SV* sv_newmortal()
613 SV* sv_2mortal(SV*)
614 SV* sv_mortalcopy(SV*)
615
5f05dabc
PP
616The first call creates a mortal SV, the second converts an existing
617SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the
618third creates a mortal copy of an existing SV.
a0d0e21e 619
54310121 620The mortal routines are not just for SVs -- AVs and HVs can be
faed5253 621made mortal by passing their address (type-casted to C<SV*>) to the
07fa94a1 622C<sv_2mortal> or C<sv_mortalcopy> routines.
a0d0e21e 623
5f05dabc 624=head2 Stashes and Globs
a0d0e21e 625
aa689395
PP
626A "stash" is a hash that contains all of the different objects that
627are contained within a package. Each key of the stash is a symbol
628name (shared by all the different types of objects that have the same
629name), and each value in the hash table is a GV (Glob Value). This GV
630in turn contains references to the various objects of that name,
631including (but not limited to) the following:
cb1a09d0 632
a0d0e21e
LW
633 Scalar Value
634 Array Value
635 Hash Value
a3cb178b 636 I/O Handle
a0d0e21e
LW
637 Format
638 Subroutine
639
9cde0e7f 640There is a single stash called "PL_defstash" that holds the items that exist
5f05dabc
PP
641in the "main" package. To get at the items in other packages, append the
642string "::" to the package name. The items in the "Foo" package are in
9cde0e7f 643the stash "Foo::" in PL_defstash. The items in the "Bar::Baz" package are
5f05dabc 644in the stash "Baz::" in "Bar::"'s stash.
a0d0e21e 645
d1b91892 646To get the stash pointer for a particular package, use the function:
a0d0e21e 647
08105a92 648 HV* gv_stashpv(const char* name, I32 create)
a0d0e21e
LW
649 HV* gv_stashsv(SV*, I32 create)
650
651The first function takes a literal string, the second uses the string stored
d1b91892 652in the SV. Remember that a stash is just a hash table, so you get back an
cb1a09d0 653C<HV*>. The C<create> flag will create a new package if it is set.
a0d0e21e
LW
654
655The name that C<gv_stash*v> wants is the name of the package whose symbol table
656you want. The default package is called C<main>. If you have multiply nested
d1b91892
AD
657packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl
658language itself.
a0d0e21e
LW
659
660Alternately, if you have an SV that is a blessed reference, you can find
661out the stash pointer by using:
662
663 HV* SvSTASH(SvRV(SV*));
664
665then use the following to get the package name itself:
666
667 char* HvNAME(HV* stash);
668
5f05dabc
PP
669If you need to bless or re-bless an object you can use the following
670function:
a0d0e21e
LW
671
672 SV* sv_bless(SV*, HV* stash)
673
674where the first argument, an C<SV*>, must be a reference, and the second
675argument is a stash. The returned C<SV*> can now be used in the same way
676as any other SV.
677
d1b91892
AD
678For more information on references and blessings, consult L<perlref>.
679
54310121 680=head2 Double-Typed SVs
0a753a76
PP
681
682Scalar variables normally contain only one type of value, an integer,
683double, pointer, or reference. Perl will automatically convert the
684actual scalar data from the stored type into the requested type.
685
686Some scalar variables contain more than one type of scalar data. For
687example, the variable C<$!> contains either the numeric value of C<errno>
688or its string equivalent from either C<strerror> or C<sys_errlist[]>.
689
690To force multiple data values into an SV, you must do two things: use the
691C<sv_set*v> routines to add the additional scalar type, then set a flag
692so that Perl will believe it contains more than one type of data. The
693four macros to set the flags are:
694
695 SvIOK_on
696 SvNOK_on
697 SvPOK_on
698 SvROK_on
699
700The particular macro you must use depends on which C<sv_set*v> routine
701you called first. This is because every C<sv_set*v> routine turns on
702only the bit for the particular type of data being set, and turns off
703all the rest.
704
705For example, to create a new Perl variable called "dberror" that contains
706both the numeric and descriptive string error values, you could use the
707following code:
708
709 extern int dberror;
710 extern char *dberror_list;
711
4929bf7b 712 SV* sv = get_sv("dberror", TRUE);
0a753a76
PP
713 sv_setiv(sv, (IV) dberror);
714 sv_setpv(sv, dberror_list[dberror]);
715 SvIOK_on(sv);
716
717If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
718macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
719
720=head2 Magic Variables
a0d0e21e 721
d1b91892
AD
722[This section still under construction. Ignore everything here. Post no
723bills. Everything not permitted is forbidden.]
724
d1b91892
AD
725Any SV may be magical, that is, it has special features that a normal
726SV does not have. These features are stored in the SV structure in a
5f05dabc 727linked list of C<struct magic>'s, typedef'ed to C<MAGIC>.
d1b91892
AD
728
729 struct magic {
730 MAGIC* mg_moremagic;
731 MGVTBL* mg_virtual;
732 U16 mg_private;
733 char mg_type;
734 U8 mg_flags;
735 SV* mg_obj;
736 char* mg_ptr;
737 I32 mg_len;
738 };
739
740Note this is current as of patchlevel 0, and could change at any time.
741
742=head2 Assigning Magic
743
744Perl adds magic to an SV using the sv_magic function:
745
08105a92 746 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);
d1b91892
AD
747
748The C<sv> argument is a pointer to the SV that is to acquire a new magical
749feature.
750
751If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
752set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding
753it to the beginning of the linked list of magical features. Any prior
754entry of the same type of magic is deleted. Note that this can be
5fb8527f 755overridden, and multiple instances of the same type of magic can be
d1b91892
AD
756associated with an SV.
757
54310121
PP
758The C<name> and C<namlen> arguments are used to associate a string with
759the magic, typically the name of a variable. C<namlen> is stored in the
760C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd
d1b91892
AD
761copy of the name is stored in C<mg_ptr> field.
762
763The sv_magic function uses C<how> to determine which, if any, predefined
764"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
cb1a09d0
AD
765See the "Magic Virtual Table" section below. The C<how> argument is also
766stored in the C<mg_type> field.
d1b91892
AD
767
768The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
769structure. If it is not the same as the C<sv> argument, the reference
770count of the C<obj> object is incremented. If it is the same, or if
04343c6d 771the C<how> argument is "#", or if it is a NULL pointer, then C<obj> is
d1b91892
AD
772merely stored, without the reference count being incremented.
773
cb1a09d0
AD
774There is also a function to add magic to an C<HV>:
775
776 void hv_magic(HV *hv, GV *gv, int how);
777
778This simply calls C<sv_magic> and coerces the C<gv> argument into an C<SV>.
779
780To remove the magic from an SV, call the function sv_unmagic:
781
782 void sv_unmagic(SV *sv, int type);
783
784The C<type> argument should be equal to the C<how> value when the C<SV>
785was initially made magical.
786
d1b91892
AD
787=head2 Magic Virtual Tables
788
789The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
790C<MGVTBL>, which is a structure of function pointers and stands for
791"Magic Virtual Table" to handle the various operations that might be
792applied to that variable.
793
794The C<MGVTBL> has five pointers to the following routine types:
795
796 int (*svt_get)(SV* sv, MAGIC* mg);
797 int (*svt_set)(SV* sv, MAGIC* mg);
798 U32 (*svt_len)(SV* sv, MAGIC* mg);
799 int (*svt_clear)(SV* sv, MAGIC* mg);
800 int (*svt_free)(SV* sv, MAGIC* mg);
801
802This MGVTBL structure is set at compile-time in C<perl.h> and there are
803currently 19 types (or 21 with overloading turned on). These different
804structures contain pointers to various routines that perform additional
805actions depending on which function is being called.
806
807 Function pointer Action taken
808 ---------------- ------------
809 svt_get Do something after the value of the SV is retrieved.
810 svt_set Do something after the SV is assigned a value.
811 svt_len Report on the SV's length.
812 svt_clear Clear something the SV represents.
813 svt_free Free any extra storage associated with the SV.
814
815For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
816to an C<mg_type> of '\0') contains:
817
818 { magic_get, magic_set, magic_len, 0, 0 }
819
820Thus, when an SV is determined to be magical and of type '\0', if a get
821operation is being performed, the routine C<magic_get> is called. All
822the various routines for the various magical types begin with C<magic_>.
954c1994
GS
823NOTE: the magic routines are not considered part of the Perl API, and may
824not be exported by the Perl library.
d1b91892
AD
825
826The current kinds of Magic Virtual Tables are:
827
bdbeb323 828 mg_type MGVTBL Type of magic
5f05dabc 829 ------- ------ ----------------------------
bdbeb323
SM
830 \0 vtbl_sv Special scalar variable
831 A vtbl_amagic %OVERLOAD hash
832 a vtbl_amagicelem %OVERLOAD hash element
833 c (none) Holds overload table (AMT) on stash
834 B vtbl_bm Boyer-Moore (fast string search)
c2e66d9e
GS
835 D vtbl_regdata Regex match position data (@+ and @- vars)
836 d vtbl_regdatum Regex match position data element
d1b91892
AD
837 E vtbl_env %ENV hash
838 e vtbl_envelem %ENV hash element
bdbeb323
SM
839 f vtbl_fm Formline ('compiled' format)
840 g vtbl_mglob m//g target / study()ed string
d1b91892
AD
841 I vtbl_isa @ISA array
842 i vtbl_isaelem @ISA array element
bdbeb323
SM
843 k vtbl_nkeys scalar(keys()) lvalue
844 L (none) Debugger %_<filename
845 l vtbl_dbline Debugger %_<filename element
44a8e56a 846 o vtbl_collxfrm Locale transformation
bdbeb323
SM
847 P vtbl_pack Tied array or hash
848 p vtbl_packelem Tied array or hash element
849 q vtbl_packelem Tied scalar or handle
850 S vtbl_sig %SIG hash
851 s vtbl_sigelem %SIG hash element
d1b91892 852 t vtbl_taint Taintedness
bdbeb323
SM
853 U vtbl_uvar Available for use by extensions
854 v vtbl_vec vec() lvalue
855 x vtbl_substr substr() lvalue
856 y vtbl_defelem Shadow "foreach" iterator variable /
857 smart parameter vivification
858 * vtbl_glob GV (typeglob)
859 # vtbl_arylen Array length ($#ary)
860 . vtbl_pos pos() lvalue
861 ~ (none) Available for use by extensions
d1b91892 862
68dc0745
PP
863When an uppercase and lowercase letter both exist in the table, then the
864uppercase letter is used to represent some kind of composite type (a list
865or a hash), and the lowercase letter is used to represent an element of
d1b91892
AD
866that composite type.
867
bdbeb323
SM
868The '~' and 'U' magic types are defined specifically for use by
869extensions and will not be used by perl itself. Extensions can use
870'~' magic to 'attach' private information to variables (typically
871objects). This is especially useful because there is no way for
872normal perl code to corrupt this private information (unlike using
873extra elements of a hash object).
874
875Similarly, 'U' magic can be used much like tie() to call a C function
876any time a scalar's value is used or changed. The C<MAGIC>'s
877C<mg_ptr> field points to a C<ufuncs> structure:
878
879 struct ufuncs {
880 I32 (*uf_val)(IV, SV*);
881 I32 (*uf_set)(IV, SV*);
882 IV uf_index;
883 };
884
885When the SV is read from or written to, the C<uf_val> or C<uf_set>
886function will be called with C<uf_index> as the first arg and a
1526ead6
AB
887pointer to the SV as the second. A simple example of how to add 'U'
888magic is shown below. Note that the ufuncs structure is copied by
889sv_magic, so you can safely allocate it on the stack.
890
891 void
892 Umagic(sv)
893 SV *sv;
894 PREINIT:
895 struct ufuncs uf;
896 CODE:
897 uf.uf_val = &my_get_fn;
898 uf.uf_set = &my_set_fn;
899 uf.uf_index = 0;
900 sv_magic(sv, 0, 'U', (char*)&uf, sizeof(uf));
5f05dabc 901
bdbeb323
SM
902Note that because multiple extensions may be using '~' or 'U' magic,
903it is important for extensions to take extra care to avoid conflict.
904Typically only using the magic on objects blessed into the same class
905as the extension is sufficient. For '~' magic, it may also be
906appropriate to add an I32 'signature' at the top of the private data
907area and check that.
5f05dabc 908
ef50df4b
GS
909Also note that the C<sv_set*()> and C<sv_cat*()> functions described
910earlier do B<not> invoke 'set' magic on their targets. This must
911be done by the user either by calling the C<SvSETMAGIC()> macro after
912calling these functions, or by using one of the C<sv_set*_mg()> or
913C<sv_cat*_mg()> functions. Similarly, generic C code must call the
914C<SvGETMAGIC()> macro to invoke any 'get' magic if they use an SV
915obtained from external sources in functions that don't handle magic.
4a4eefd0 916See L<perlapi> for a description of these functions.
189b2af5
GS
917For example, calls to the C<sv_cat*()> functions typically need to be
918followed by C<SvSETMAGIC()>, but they don't need a prior C<SvGETMAGIC()>
919since their implementation handles 'get' magic.
920
d1b91892
AD
921=head2 Finding Magic
922
923 MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */
924
925This routine returns a pointer to the C<MAGIC> structure stored in the SV.
926If the SV does not have that magical feature, C<NULL> is returned. Also,
54310121 927if the SV is not of type SVt_PVMG, Perl may core dump.
d1b91892 928
08105a92 929 int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen);
d1b91892
AD
930
931This routine checks to see what types of magic C<sv> has. If the mg_type
68dc0745
PP
932field is an uppercase letter, then the mg_obj is copied to C<nsv>, but
933the mg_type field is changed to be the lowercase letter.
a0d0e21e 934
04343c6d
GS
935=head2 Understanding the Magic of Tied Hashes and Arrays
936
937Tied hashes and arrays are magical beasts of the 'P' magic type.
9edb2b46
GS
938
939WARNING: As of the 5.004 release, proper usage of the array and hash
940access functions requires understanding a few caveats. Some
941of these caveats are actually considered bugs in the API, to be fixed
942in later releases, and are bracketed with [MAYCHANGE] below. If
943you find yourself actually applying such information in this section, be
944aware that the behavior may change in the future, umm, without warning.
04343c6d 945
1526ead6
AB
946The perl tie function associates a variable with an object that implements
947the various GET, SET etc methods. To perform the equivalent of the perl
948tie function from an XSUB, you must mimic this behaviour. The code below
949carries out the necessary steps - firstly it creates a new hash, and then
950creates a second hash which it blesses into the class which will implement
951the tie methods. Lastly it ties the two hashes together, and returns a
952reference to the new tied hash. Note that the code below does NOT call the
953TIEHASH method in the MyTie class -
954see L<Calling Perl Routines from within C Programs> for details on how
955to do this.
956
957 SV*
958 mytie()
959 PREINIT:
960 HV *hash;
961 HV *stash;
962 SV *tie;
963 CODE:
964 hash = newHV();
965 tie = newRV_noinc((SV*)newHV());
966 stash = gv_stashpv("MyTie", TRUE);
967 sv_bless(tie, stash);
968 hv_magic(hash, tie, 'P');
969 RETVAL = newRV_noinc(hash);
970 OUTPUT:
971 RETVAL
972
04343c6d
GS
973The C<av_store> function, when given a tied array argument, merely
974copies the magic of the array onto the value to be "stored", using
975C<mg_copy>. It may also return NULL, indicating that the value did not
9edb2b46
GS
976actually need to be stored in the array. [MAYCHANGE] After a call to
977C<av_store> on a tied array, the caller will usually need to call
978C<mg_set(val)> to actually invoke the perl level "STORE" method on the
979TIEARRAY object. If C<av_store> did return NULL, a call to
980C<SvREFCNT_dec(val)> will also be usually necessary to avoid a memory
981leak. [/MAYCHANGE]
04343c6d
GS
982
983The previous paragraph is applicable verbatim to tied hash access using the
984C<hv_store> and C<hv_store_ent> functions as well.
985
986C<av_fetch> and the corresponding hash functions C<hv_fetch> and
987C<hv_fetch_ent> actually return an undefined mortal value whose magic
988has been initialized using C<mg_copy>. Note the value so returned does not
9edb2b46
GS
989need to be deallocated, as it is already mortal. [MAYCHANGE] But you will
990need to call C<mg_get()> on the returned value in order to actually invoke
991the perl level "FETCH" method on the underlying TIE object. Similarly,
04343c6d
GS
992you may also call C<mg_set()> on the return value after possibly assigning
993a suitable value to it using C<sv_setsv>, which will invoke the "STORE"
9edb2b46 994method on the TIE object. [/MAYCHANGE]
04343c6d 995
9edb2b46 996[MAYCHANGE]
04343c6d
GS
997In other words, the array or hash fetch/store functions don't really
998fetch and store actual values in the case of tied arrays and hashes. They
999merely call C<mg_copy> to attach magic to the values that were meant to be
1000"stored" or "fetched". Later calls to C<mg_get> and C<mg_set> actually
1001do the job of invoking the TIE methods on the underlying objects. Thus
9edb2b46 1002the magic mechanism currently implements a kind of lazy access to arrays
04343c6d
GS
1003and hashes.
1004
1005Currently (as of perl version 5.004), use of the hash and array access
1006functions requires the user to be aware of whether they are operating on
9edb2b46
GS
1007"normal" hashes and arrays, or on their tied variants. The API may be
1008changed to provide more transparent access to both tied and normal data
1009types in future versions.
1010[/MAYCHANGE]
04343c6d
GS
1011
1012You would do well to understand that the TIEARRAY and TIEHASH interfaces
1013are mere sugar to invoke some perl method calls while using the uniform hash
1014and array syntax. The use of this sugar imposes some overhead (typically
1015about two to four extra opcodes per FETCH/STORE operation, in addition to
1016the creation of all the mortal variables required to invoke the methods).
1017This overhead will be comparatively small if the TIE methods are themselves
1018substantial, but if they are only a few statements long, the overhead
1019will not be insignificant.
1020
d1c897a1
IZ
1021=head2 Localizing changes
1022
1023Perl has a very handy construction
1024
1025 {
1026 local $var = 2;
1027 ...
1028 }
1029
1030This construction is I<approximately> equivalent to
1031
1032 {
1033 my $oldvar = $var;
1034 $var = 2;
1035 ...
1036 $var = $oldvar;
1037 }
1038
1039The biggest difference is that the first construction would
1040reinstate the initial value of $var, irrespective of how control exits
1041the block: C<goto>, C<return>, C<die>/C<eval> etc. It is a little bit
1042more efficient as well.
1043
1044There is a way to achieve a similar task from C via Perl API: create a
1045I<pseudo-block>, and arrange for some changes to be automatically
1046undone at the end of it, either explicit, or via a non-local exit (via
1047die()). A I<block>-like construct is created by a pair of
b687b08b
TC
1048C<ENTER>/C<LEAVE> macros (see L<perlcall/"Returning a Scalar">).
1049Such a construct may be created specially for some important localized
1050task, or an existing one (like boundaries of enclosing Perl
1051subroutine/block, or an existing pair for freeing TMPs) may be
1052used. (In the second case the overhead of additional localization must
1053be almost negligible.) Note that any XSUB is automatically enclosed in
1054an C<ENTER>/C<LEAVE> pair.
d1c897a1
IZ
1055
1056Inside such a I<pseudo-block> the following service is available:
1057
1058=over
1059
1060=item C<SAVEINT(int i)>
1061
1062=item C<SAVEIV(IV i)>
1063
1064=item C<SAVEI32(I32 i)>
1065
1066=item C<SAVELONG(long i)>
1067
1068These macros arrange things to restore the value of integer variable
1069C<i> at the end of enclosing I<pseudo-block>.
1070
1071=item C<SAVESPTR(s)>
1072
1073=item C<SAVEPPTR(p)>
1074
1075These macros arrange things to restore the value of pointers C<s> and
1076C<p>. C<s> must be a pointer of a type which survives conversion to
1077C<SV*> and back, C<p> should be able to survive conversion to C<char*>
1078and back.
1079
1080=item C<SAVEFREESV(SV *sv)>
1081
1082The refcount of C<sv> would be decremented at the end of
1083I<pseudo-block>. This is similar to C<sv_2mortal>, which should (?) be
1084used instead.
1085
1086=item C<SAVEFREEOP(OP *op)>
1087
1088The C<OP *> is op_free()ed at the end of I<pseudo-block>.
1089
1090=item C<SAVEFREEPV(p)>
1091
1092The chunk of memory which is pointed to by C<p> is Safefree()ed at the
1093end of I<pseudo-block>.
1094
1095=item C<SAVECLEARSV(SV *sv)>
1096
1097Clears a slot in the current scratchpad which corresponds to C<sv> at
1098the end of I<pseudo-block>.
1099
1100=item C<SAVEDELETE(HV *hv, char *key, I32 length)>
1101
1102The key C<key> of C<hv> is deleted at the end of I<pseudo-block>. The
1103string pointed to by C<key> is Safefree()ed. If one has a I<key> in
1104short-lived storage, the corresponding string may be reallocated like
1105this:
1106
9cde0e7f 1107 SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));
d1c897a1 1108
c76ac1ee 1109=item C<SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)>
d1c897a1
IZ
1110
1111At the end of I<pseudo-block> the function C<f> is called with the
c76ac1ee
GS
1112only argument C<p>.
1113
1114=item C<SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)>
1115
1116At the end of I<pseudo-block> the function C<f> is called with the
1117implicit context argument (if any), and C<p>.
d1c897a1
IZ
1118
1119=item C<SAVESTACK_POS()>
1120
1121The current offset on the Perl internal stack (cf. C<SP>) is restored
1122at the end of I<pseudo-block>.
1123
1124=back
1125
1126The following API list contains functions, thus one needs to
1127provide pointers to the modifiable data explicitly (either C pointers,
1128or Perlish C<GV *>s). Where the above macros take C<int>, a similar
1129function takes C<int *>.
1130
1131=over
1132
1133=item C<SV* save_scalar(GV *gv)>
1134
1135Equivalent to Perl code C<local $gv>.
1136
1137=item C<AV* save_ary(GV *gv)>
1138
1139=item C<HV* save_hash(GV *gv)>
1140
1141Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.
1142
1143=item C<void save_item(SV *item)>
1144
1145Duplicates the current value of C<SV>, on the exit from the current
1146C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
1147using the stored value.
1148
1149=item C<void save_list(SV **sarg, I32 maxsarg)>
1150
1151A variant of C<save_item> which takes multiple arguments via an array
1152C<sarg> of C<SV*> of length C<maxsarg>.
1153
1154=item C<SV* save_svref(SV **sptr)>
1155
1156Similar to C<save_scalar>, but will reinstate a C<SV *>.
1157
1158=item C<void save_aptr(AV **aptr)>
1159
1160=item C<void save_hptr(HV **hptr)>
1161
1162Similar to C<save_svref>, but localize C<AV *> and C<HV *>.
1163
1164=back
1165
1166The C<Alias> module implements localization of the basic types within the
1167I<caller's scope>. People who are interested in how to localize things in
1168the containing scope should take a look there too.
1169
0a753a76 1170=head1 Subroutines
a0d0e21e 1171
68dc0745 1172=head2 XSUBs and the Argument Stack
5f05dabc
PP
1173
1174The XSUB mechanism is a simple way for Perl programs to access C subroutines.
1175An XSUB routine will have a stack that contains the arguments from the Perl
1176program, and a way to map from the Perl data structures to a C equivalent.
1177
1178The stack arguments are accessible through the C<ST(n)> macro, which returns
1179the C<n>'th stack argument. Argument 0 is the first argument passed in the
1180Perl subroutine call. These arguments are C<SV*>, and can be used anywhere
1181an C<SV*> is used.
1182
1183Most of the time, output from the C routine can be handled through use of
1184the RETVAL and OUTPUT directives. However, there are some cases where the
1185argument stack is not already long enough to handle all the return values.
1186An example is the POSIX tzname() call, which takes no arguments, but returns
1187two, the local time zone's standard and summer time abbreviations.
1188
1189To handle this situation, the PPCODE directive is used and the stack is
1190extended using the macro:
1191
924508f0 1192 EXTEND(SP, num);
5f05dabc 1193
924508f0
GS
1194where C<SP> is the macro that represents the local copy of the stack pointer,
1195and C<num> is the number of elements the stack should be extended by.
5f05dabc
PP
1196
1197Now that there is room on the stack, values can be pushed on it using the
54310121 1198macros to push IVs, doubles, strings, and SV pointers respectively:
5f05dabc
PP
1199
1200 PUSHi(IV)
1201 PUSHn(double)
1202 PUSHp(char*, I32)
1203 PUSHs(SV*)
1204
1205And now the Perl program calling C<tzname>, the two values will be assigned
1206as in:
1207
1208 ($standard_abbrev, $summer_abbrev) = POSIX::tzname;
1209
1210An alternate (and possibly simpler) method to pushing values on the stack is
1211to use the macros:
1212
1213 XPUSHi(IV)
1214 XPUSHn(double)
1215 XPUSHp(char*, I32)
1216 XPUSHs(SV*)
1217
1218These macros automatically adjust the stack for you, if needed. Thus, you
1219do not need to call C<EXTEND> to extend the stack.
1220
1221For more information, consult L<perlxs> and L<perlxstut>.
1222
1223=head2 Calling Perl Routines from within C Programs
a0d0e21e
LW
1224
1225There are four routines that can be used to call a Perl subroutine from
1226within a C program. These four are:
1227
954c1994
GS
1228 I32 call_sv(SV*, I32);
1229 I32 call_pv(const char*, I32);
1230 I32 call_method(const char*, I32);
1231 I32 call_argv(const char*, I32, register char**);
a0d0e21e 1232
954c1994 1233The routine most often used is C<call_sv>. The C<SV*> argument
d1b91892
AD
1234contains either the name of the Perl subroutine to be called, or a
1235reference to the subroutine. The second argument consists of flags
1236that control the context in which the subroutine is called, whether
1237or not the subroutine is being passed arguments, how errors should be
1238trapped, and how to treat return values.
a0d0e21e
LW
1239
1240All four routines return the number of arguments that the subroutine returned
1241on the Perl stack.
1242
954c1994
GS
1243These routines used to be called C<perl_call_sv> etc., before Perl v5.6.0,
1244but those names are now deprecated; macros of the same name are provided for
1245compatibility.
1246
1247When using any of these routines (except C<call_argv>), the programmer
d1b91892
AD
1248must manipulate the Perl stack. These include the following macros and
1249functions:
a0d0e21e
LW
1250
1251 dSP
924508f0 1252 SP
a0d0e21e
LW
1253 PUSHMARK()
1254 PUTBACK
1255 SPAGAIN
1256 ENTER
1257 SAVETMPS
1258 FREETMPS
1259 LEAVE
1260 XPUSH*()
cb1a09d0 1261 POP*()
a0d0e21e 1262
5f05dabc
PP
1263For a detailed description of calling conventions from C to Perl,
1264consult L<perlcall>.
a0d0e21e 1265
5f05dabc 1266=head2 Memory Allocation
a0d0e21e 1267
86058a2d
GS
1268All memory meant to be used with the Perl API functions should be manipulated
1269using the macros described in this section. The macros provide the necessary
1270transparency between differences in the actual malloc implementation that is
1271used within perl.
1272
1273It is suggested that you enable the version of malloc that is distributed
5f05dabc 1274with Perl. It keeps pools of various sizes of unallocated memory in
07fa94a1
JO
1275order to satisfy allocation requests more quickly. However, on some
1276platforms, it may cause spurious malloc or free errors.
d1b91892
AD
1277
1278 New(x, pointer, number, type);
1279 Newc(x, pointer, number, type, cast);
1280 Newz(x, pointer, number, type);
1281
07fa94a1 1282These three macros are used to initially allocate memory.
5f05dabc
PP
1283
1284The first argument C<x> was a "magic cookie" that was used to keep track
1285of who called the macro, to help when debugging memory problems. However,
07fa94a1
JO
1286the current code makes no use of this feature (most Perl developers now
1287use run-time memory checkers), so this argument can be any number.
5f05dabc
PP
1288
1289The second argument C<pointer> should be the name of a variable that will
1290point to the newly allocated memory.
d1b91892 1291
d1b91892
AD
1292The third and fourth arguments C<number> and C<type> specify how many of
1293the specified type of data structure should be allocated. The argument
1294C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>,
1295should be used if the C<pointer> argument is different from the C<type>
1296argument.
1297
1298Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
1299to zero out all the newly allocated memory.
1300
1301 Renew(pointer, number, type);
1302 Renewc(pointer, number, type, cast);
1303 Safefree(pointer)
1304
1305These three macros are used to change a memory buffer size or to free a
1306piece of memory no longer needed. The arguments to C<Renew> and C<Renewc>
1307match those of C<New> and C<Newc> with the exception of not needing the
1308"magic cookie" argument.
1309
1310 Move(source, dest, number, type);
1311 Copy(source, dest, number, type);
1312 Zero(dest, number, type);
1313
1314These three macros are used to move, copy, or zero out previously allocated
1315memory. The C<source> and C<dest> arguments point to the source and
1316destination starting points. Perl will move, copy, or zero out C<number>
1317instances of the size of the C<type> data structure (using the C<sizeof>
1318function).
a0d0e21e 1319
5f05dabc 1320=head2 PerlIO
ce3d39e2 1321
5f05dabc
PP
1322The most recent development releases of Perl has been experimenting with
1323removing Perl's dependency on the "normal" standard I/O suite and allowing
1324other stdio implementations to be used. This involves creating a new
1325abstraction layer that then calls whichever implementation of stdio Perl
68dc0745 1326was compiled with. All XSUBs should now use the functions in the PerlIO
5f05dabc
PP
1327abstraction layer and not make any assumptions about what kind of stdio
1328is being used.
1329
1330For a complete description of the PerlIO abstraction, consult L<perlapio>.
1331
8ebc5c01 1332=head2 Putting a C value on Perl stack
ce3d39e2
IZ
1333
1334A lot of opcodes (this is an elementary operation in the internal perl
1335stack machine) put an SV* on the stack. However, as an optimization
1336the corresponding SV is (usually) not recreated each time. The opcodes
1337reuse specially assigned SVs (I<target>s) which are (as a corollary)
1338not constantly freed/created.
1339
0a753a76 1340Each of the targets is created only once (but see
ce3d39e2
IZ
1341L<Scratchpads and recursion> below), and when an opcode needs to put
1342an integer, a double, or a string on stack, it just sets the
1343corresponding parts of its I<target> and puts the I<target> on stack.
1344
1345The macro to put this target on stack is C<PUSHTARG>, and it is
1346directly used in some opcodes, as well as indirectly in zillions of
1347others, which use it via C<(X)PUSH[pni]>.
1348
8ebc5c01 1349=head2 Scratchpads
ce3d39e2 1350
54310121 1351The question remains on when the SVs which are I<target>s for opcodes
5f05dabc
PP
1352are created. The answer is that they are created when the current unit --
1353a subroutine or a file (for opcodes for statements outside of
1354subroutines) -- is compiled. During this time a special anonymous Perl
ce3d39e2
IZ
1355array is created, which is called a scratchpad for the current
1356unit.
1357
54310121 1358A scratchpad keeps SVs which are lexicals for the current unit and are
ce3d39e2
IZ
1359targets for opcodes. One can deduce that an SV lives on a scratchpad
1360by looking on its flags: lexicals have C<SVs_PADMY> set, and
1361I<target>s have C<SVs_PADTMP> set.
1362
54310121
PP
1363The correspondence between OPs and I<target>s is not 1-to-1. Different
1364OPs in the compile tree of the unit can use the same target, if this
ce3d39e2
IZ
1365would not conflict with the expected life of the temporary.
1366
2ae324a7 1367=head2 Scratchpads and recursion
ce3d39e2
IZ
1368
1369In fact it is not 100% true that a compiled unit contains a pointer to
1370the scratchpad AV. In fact it contains a pointer to an AV of
1371(initially) one element, and this element is the scratchpad AV. Why do
1372we need an extra level of indirection?
1373
1374The answer is B<recursion>, and maybe (sometime soon) B<threads>. Both
1375these can create several execution pointers going into the same
1376subroutine. For the subroutine-child not write over the temporaries
1377for the subroutine-parent (lifespan of which covers the call to the
1378child), the parent and the child should have different
1379scratchpads. (I<And> the lexicals should be separate anyway!)
1380
5f05dabc
PP
1381So each subroutine is born with an array of scratchpads (of length 1).
1382On each entry to the subroutine it is checked that the current
ce3d39e2
IZ
1383depth of the recursion is not more than the length of this array, and
1384if it is, new scratchpad is created and pushed into the array.
1385
1386The I<target>s on this scratchpad are C<undef>s, but they are already
1387marked with correct flags.
1388
0a753a76
PP
1389=head1 Compiled code
1390
1391=head2 Code tree
1392
1393Here we describe the internal form your code is converted to by
1394Perl. Start with a simple example:
1395
1396 $a = $b + $c;
1397
1398This is converted to a tree similar to this one:
1399
1400 assign-to
1401 / \
1402 + $a
1403 / \
1404 $b $c
1405
7b8d334a 1406(but slightly more complicated). This tree reflects the way Perl
0a753a76
PP
1407parsed your code, but has nothing to do with the execution order.
1408There is an additional "thread" going through the nodes of the tree
1409which shows the order of execution of the nodes. In our simplified
1410example above it looks like:
1411
1412 $b ---> $c ---> + ---> $a ---> assign-to
1413
1414But with the actual compile tree for C<$a = $b + $c> it is different:
1415some nodes I<optimized away>. As a corollary, though the actual tree
1416contains more nodes than our simplified example, the execution order
1417is the same as in our example.
1418
1419=head2 Examining the tree
1420
1421If you have your perl compiled for debugging (usually done with C<-D
1422optimize=-g> on C<Configure> command line), you may examine the
1423compiled tree by specifying C<-Dx> on the Perl command line. The
1424output takes several lines per node, and for C<$b+$c> it looks like
1425this:
1426
1427 5 TYPE = add ===> 6
1428 TARG = 1
1429 FLAGS = (SCALAR,KIDS)
1430 {
1431 TYPE = null ===> (4)
1432 (was rv2sv)
1433 FLAGS = (SCALAR,KIDS)
1434 {
1435 3 TYPE = gvsv ===> 4
1436 FLAGS = (SCALAR)
1437 GV = main::b
1438 }
1439 }
1440 {
1441 TYPE = null ===> (5)
1442 (was rv2sv)
1443 FLAGS = (SCALAR,KIDS)
1444 {
1445 4 TYPE = gvsv ===> 5
1446 FLAGS = (SCALAR)
1447 GV = main::c
1448 }
1449 }
1450
1451This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are
1452not optimized away (one per number in the left column). The immediate
1453children of the given node correspond to C<{}> pairs on the same level
1454of indentation, thus this listing corresponds to the tree:
1455
1456 add
1457 / \
1458 null null
1459 | |
1460 gvsv gvsv
1461
1462The execution order is indicated by C<===E<gt>> marks, thus it is C<3
14634 5 6> (node C<6> is not included into above listing), i.e.,
1464C<gvsv gvsv add whatever>.
1465
1466=head2 Compile pass 1: check routines
1467
8870b5c7
GS
1468The tree is created by the compiler while I<yacc> code feeds it
1469the constructions it recognizes. Since I<yacc> works bottom-up, so does
0a753a76
PP
1470the first pass of perl compilation.
1471
1472What makes this pass interesting for perl developers is that some
1473optimization may be performed on this pass. This is optimization by
8870b5c7 1474so-called "check routines". The correspondence between node names
0a753a76
PP
1475and corresponding check routines is described in F<opcode.pl> (do not
1476forget to run C<make regen_headers> if you modify this file).
1477
1478A check routine is called when the node is fully constructed except
7b8d334a 1479for the execution-order thread. Since at this time there are no
0a753a76
PP
1480back-links to the currently constructed node, one can do most any
1481operation to the top-level node, including freeing it and/or creating
1482new nodes above/below it.
1483
1484The check routine returns the node which should be inserted into the
1485tree (if the top-level node was not modified, check routine returns
1486its argument).
1487
1488By convention, check routines have names C<ck_*>. They are usually
1489called from C<new*OP> subroutines (or C<convert>) (which in turn are
1490called from F<perly.y>).
1491
1492=head2 Compile pass 1a: constant folding
1493
1494Immediately after the check routine is called the returned node is
1495checked for being compile-time executable. If it is (the value is
1496judged to be constant) it is immediately executed, and a I<constant>
1497node with the "return value" of the corresponding subtree is
1498substituted instead. The subtree is deleted.
1499
1500If constant folding was not performed, the execution-order thread is
1501created.
1502
1503=head2 Compile pass 2: context propagation
1504
1505When a context for a part of compile tree is known, it is propagated
a3cb178b 1506down through the tree. At this time the context can have 5 values
0a753a76
PP
1507(instead of 2 for runtime context): void, boolean, scalar, list, and
1508lvalue. In contrast with the pass 1 this pass is processed from top
1509to bottom: a node's context determines the context for its children.
1510
1511Additional context-dependent optimizations are performed at this time.
1512Since at this moment the compile tree contains back-references (via
1513"thread" pointers), nodes cannot be free()d now. To allow
1514optimized-away nodes at this stage, such nodes are null()ified instead
1515of free()ing (i.e. their type is changed to OP_NULL).
1516
1517=head2 Compile pass 3: peephole optimization
1518
1519After the compile tree for a subroutine (or for an C<eval> or a file)
1520is created, an additional pass over the code is performed. This pass
1521is neither top-down or bottom-up, but in the execution order (with
7b8d334a 1522additional complications for conditionals). These optimizations are
0a753a76
PP
1523done in the subroutine peep(). Optimizations performed at this stage
1524are subject to the same restrictions as in the pass 2.
1525
954c1994 1526=head1 How multiple interpreters and concurrency are supported
ee072b34 1527
ee072b34
GS
1528=head2 Background and PERL_IMPLICIT_CONTEXT
1529
1530The Perl interpreter can be regarded as a closed box: it has an API
1531for feeding it code or otherwise making it do things, but it also has
1532functions for its own use. This smells a lot like an object, and
1533there are ways for you to build Perl so that you can have multiple
1534interpreters, with one interpreter represented either as a C++ object,
1535a C structure, or inside a thread. The thread, the C structure, or
1536the C++ object will contain all the context, the state of that
1537interpreter.
1538
54aff467
GS
1539Three macros control the major Perl build flavors: MULTIPLICITY,
1540USE_THREADS and PERL_OBJECT. The MULTIPLICITY build has a C structure
1541that packages all the interpreter state, there is a similar thread-specific
1542data structure under USE_THREADS, and the PERL_OBJECT build has a C++
1543class to maintain interpreter state. In all three cases,
1544PERL_IMPLICIT_CONTEXT is also normally defined, and enables the
1545support for passing in a "hidden" first argument that represents all three
651a3225 1546data structures.
54aff467
GS
1547
1548All this obviously requires a way for the Perl internal functions to be
ee072b34
GS
1549C++ methods, subroutines taking some kind of structure as the first
1550argument, or subroutines taking nothing as the first argument. To
1551enable these three very different ways of building the interpreter,
1552the Perl source (as it does in so many other situations) makes heavy
1553use of macros and subroutine naming conventions.
1554
54aff467 1555First problem: deciding which functions will be public API functions and
954c1994
GS
1556which will be private. All functions whose names begin C<S_> are private
1557(think "S" for "secret" or "static"). All other functions begin with
1558"Perl_", but just because a function begins with "Perl_" does not mean it is
1559part of the API. The easiest way to be B<sure> a function is part of the API
1560is to find its entry in L<perlapi>. If it exists in L<perlapi>, it's part
4375e838
GS
1561of the API. If it doesn't, and you think it should be (i.e., you need it for
1562your extension), send mail via L<perlbug> explaining why you think it
954c1994
GS
1563should be.
1564
1565(L<perlapi> itself is generated by embed.pl, a Perl script that generates
1566significant portions of the Perl source code. It has a list of almost
1567all the functions defined by the Perl interpreter along with their calling
1568characteristics and some flags. Functions that are part of the public API
1569are marked with an 'A' in its flags.)
ee072b34
GS
1570
1571Second problem: there must be a syntax so that the same subroutine
1572declarations and calls can pass a structure as their first argument,
1573or pass nothing. To solve this, the subroutines are named and
1574declared in a particular way. Here's a typical start of a static
1575function used within the Perl guts:
1576
1577 STATIC void
1578 S_incline(pTHX_ char *s)
1579
1580STATIC becomes "static" in C, and is #define'd to nothing in C++.
1581
651a3225
GS
1582A public function (i.e. part of the internal API, but not necessarily
1583sanctioned for use in extensions) begins like this:
ee072b34
GS
1584
1585 void
1586 Perl_sv_setsv(pTHX_ SV* dsv, SV* ssv)
1587
1588C<pTHX_> is one of a number of macros (in perl.h) that hide the
1589details of the interpreter's context. THX stands for "thread", "this",
1590or "thingy", as the case may be. (And no, George Lucas is not involved. :-)
1591The first character could be 'p' for a B<p>rototype, 'a' for B<a>rgument,
1592or 'd' for B<d>eclaration.
1593
1594When Perl is built without PERL_IMPLICIT_CONTEXT, there is no first
1595argument containing the interpreter's context. The trailing underscore
1596in the pTHX_ macro indicates that the macro expansion needs a comma
1597after the context argument because other arguments follow it. If
1598PERL_IMPLICIT_CONTEXT is not defined, pTHX_ will be ignored, and the
54aff467
GS
1599subroutine is not prototyped to take the extra argument. The form of the
1600macro without the trailing underscore is used when there are no additional
ee072b34
GS
1601explicit arguments.
1602
54aff467 1603When a core function calls another, it must pass the context. This
ee072b34
GS
1604is normally hidden via macros. Consider C<sv_setsv>. It expands
1605something like this:
1606
1607 ifdef PERL_IMPLICIT_CONTEXT
1608 define sv_setsv(a,b) Perl_sv_setsv(aTHX_ a, b)
1609 /* can't do this for vararg functions, see below */
1610 else
1611 define sv_setsv Perl_sv_setsv
1612 endif
1613
1614This works well, and means that XS authors can gleefully write:
1615
1616 sv_setsv(foo, bar);
1617
1618and still have it work under all the modes Perl could have been
1619compiled with.
1620
1621Under PERL_OBJECT in the core, that will translate to either:
1622
1623 CPerlObj::Perl_sv_setsv(foo,bar); # in CPerlObj functions,
1624 # C++ takes care of 'this'
1625 or
1626
1627 pPerl->Perl_sv_setsv(foo,bar); # in truly static functions,
1628 # see objXSUB.h
1629
1630Under PERL_OBJECT in extensions (aka PERL_CAPI), or under
1631MULTIPLICITY/USE_THREADS w/ PERL_IMPLICIT_CONTEXT in both core
1632and extensions, it will be:
1633
1634 Perl_sv_setsv(aTHX_ foo, bar); # the canonical Perl "API"
1635 # for all build flavors
1636
1637This doesn't work so cleanly for varargs functions, though, as macros
1638imply that the number of arguments is known in advance. Instead we
1639either need to spell them out fully, passing C<aTHX_> as the first
1640argument (the Perl core tends to do this with functions like
1641Perl_warner), or use a context-free version.
1642
1643The context-free version of Perl_warner is called
1644Perl_warner_nocontext, and does not take the extra argument. Instead
1645it does dTHX; to get the context from thread-local storage. We
1646C<#define warner Perl_warner_nocontext> so that extensions get source
1647compatibility at the expense of performance. (Passing an arg is
1648cheaper than grabbing it from thread-local storage.)
1649
1650You can ignore [pad]THX[xo] when browsing the Perl headers/sources.
1651Those are strictly for use within the core. Extensions and embedders
1652need only be aware of [pad]THX.
1653
1654=head2 How do I use all this in extensions?
1655
1656When Perl is built with PERL_IMPLICIT_CONTEXT, extensions that call
1657any functions in the Perl API will need to pass the initial context
1658argument somehow. The kicker is that you will need to write it in
1659such a way that the extension still compiles when Perl hasn't been
1660built with PERL_IMPLICIT_CONTEXT enabled.
1661
1662There are three ways to do this. First, the easy but inefficient way,
1663which is also the default, in order to maintain source compatibility
1664with extensions: whenever XSUB.h is #included, it redefines the aTHX
1665and aTHX_ macros to call a function that will return the context.
1666Thus, something like:
1667
1668 sv_setsv(asv, bsv);
1669
4375e838 1670in your extension will translate to this when PERL_IMPLICIT_CONTEXT is
54aff467 1671in effect:
ee072b34 1672
2fa86c13 1673 Perl_sv_setsv(Perl_get_context(), asv, bsv);
ee072b34 1674
54aff467 1675or to this otherwise:
ee072b34
GS
1676
1677 Perl_sv_setsv(asv, bsv);
1678
1679You have to do nothing new in your extension to get this; since
2fa86c13 1680the Perl library provides Perl_get_context(), it will all just
ee072b34
GS
1681work.
1682
1683The second, more efficient way is to use the following template for
1684your Foo.xs:
1685
1686 #define PERL_NO_GET_CONTEXT /* we want efficiency */
1687 #include "EXTERN.h"
1688 #include "perl.h"
1689 #include "XSUB.h"
1690
1691 static my_private_function(int arg1, int arg2);
1692
1693 static SV *
54aff467 1694 my_private_function(int arg1, int arg2)
ee072b34
GS
1695 {
1696 dTHX; /* fetch context */
1697 ... call many Perl API functions ...
1698 }
1699
1700 [... etc ...]
1701
1702 MODULE = Foo PACKAGE = Foo
1703
1704 /* typical XSUB */
1705
1706 void
1707 my_xsub(arg)
1708 int arg
1709 CODE:
1710 my_private_function(arg, 10);
1711
1712Note that the only two changes from the normal way of writing an
1713extension is the addition of a C<#define PERL_NO_GET_CONTEXT> before
1714including the Perl headers, followed by a C<dTHX;> declaration at
1715the start of every function that will call the Perl API. (You'll
1716know which functions need this, because the C compiler will complain
1717that there's an undeclared identifier in those functions.) No changes
1718are needed for the XSUBs themselves, because the XS() macro is
1719correctly defined to pass in the implicit context if needed.
1720
1721The third, even more efficient way is to ape how it is done within
1722the Perl guts:
1723
1724
1725 #define PERL_NO_GET_CONTEXT /* we want efficiency */
1726 #include "EXTERN.h"
1727 #include "perl.h"
1728 #include "XSUB.h"
1729
1730 /* pTHX_ only needed for functions that call Perl API */
1731 static my_private_function(pTHX_ int arg1, int arg2);
1732
1733 static SV *
1734 my_private_function(pTHX_ int arg1, int arg2)
1735 {
1736 /* dTHX; not needed here, because THX is an argument */
1737 ... call Perl API functions ...
1738 }
1739
1740 [... etc ...]
1741
1742 MODULE = Foo PACKAGE = Foo
1743
1744 /* typical XSUB */
1745
1746 void
1747 my_xsub(arg)
1748 int arg
1749 CODE:
1750 my_private_function(aTHX_ arg, 10);
1751
1752This implementation never has to fetch the context using a function
1753call, since it is always passed as an extra argument. Depending on
1754your needs for simplicity or efficiency, you may mix the previous
1755two approaches freely.
1756
651a3225
GS
1757Never add a comma after C<pTHX> yourself--always use the form of the
1758macro with the underscore for functions that take explicit arguments,
1759or the form without the argument for functions with no explicit arguments.
ee072b34
GS
1760
1761=head2 Future Plans and PERL_IMPLICIT_SYS
1762
1763Just as PERL_IMPLICIT_CONTEXT provides a way to bundle up everything
1764that the interpreter knows about itself and pass it around, so too are
1765there plans to allow the interpreter to bundle up everything it knows
1766about the environment it's running on. This is enabled with the
1767PERL_IMPLICIT_SYS macro. Currently it only works with PERL_OBJECT,
1768but is mostly there for MULTIPLICITY and USE_THREADS (see inside
1769iperlsys.h).
1770
1771This allows the ability to provide an extra pointer (called the "host"
1772environment) for all the system calls. This makes it possible for
1773all the system stuff to maintain their own state, broken down into
1774seven C structures. These are thin wrappers around the usual system
1775calls (see win32/perllib.c) for the default perl executable, but for a
1776more ambitious host (like the one that would do fork() emulation) all
1777the extra work needed to pretend that different interpreters are
1778actually different "processes", would be done here.
1779
1780The Perl engine/interpreter and the host are orthogonal entities.
1781There could be one or more interpreters in a process, and one or
1782more "hosts", with free association between them.
1783
954c1994 1784=head1 AUTHORS
e89caa19 1785
954c1994
GS
1786Until May 1997, this document was maintained by Jeff Okamoto
1787<okamoto@corp.hp.com>. It is now maintained as part of Perl itself
1788by the Perl 5 Porters <perl5-porters@perl.org>.
cb1a09d0 1789
954c1994
GS
1790With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
1791Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
1792Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
1793Stephen McCamant, and Gurusamy Sarathy.
cb1a09d0 1794
954c1994 1795API Listing originally by Dean Roehrich <roehrich@cray.com>.
cb1a09d0 1796
954c1994
GS
1797Modifications to autogenerate the API listing (L<perlapi>) by Benjamin
1798Stuhl.
cb1a09d0 1799
954c1994 1800=head1 SEE ALSO
cb1a09d0 1801
954c1994 1802perlapi(1), perlintern(1), perlxs(1), perlembed(1)