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