PageRenderTime 178ms CodeModel.GetById 11ms app.highlight 151ms RepoModel.GetById 2ms app.codeStats 0ms

/IronPython_Main/Runtime/Tests/LinqDlrTests/testenv/perl/lib/pod/perlcall.pod

#
Unknown | 1957 lines | 1402 code | 555 blank | 0 comment | 0 complexity | b7dbc2949c475833a676d46ed7eaeed4 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1=head1 NAME
   2
   3perlcall - Perl calling conventions from C
   4
   5=head1 DESCRIPTION
   6
   7The purpose of this document is to show you how to call Perl subroutines
   8directly from C, i.e., how to write I<callbacks>.
   9
  10Apart from discussing the C interface provided by Perl for writing
  11callbacks the document uses a series of examples to show how the
  12interface actually works in practice.  In addition some techniques for
  13coding callbacks are covered.
  14
  15Examples where callbacks are necessary include
  16
  17=over 5
  18
  19=item * An Error Handler
  20
  21You have created an XSUB interface to an application's C API.
  22
  23A fairly common feature in applications is to allow you to define a C
  24function that will be called whenever something nasty occurs. What we
  25would like is to be able to specify a Perl subroutine that will be
  26called instead.
  27
  28=item * An Event Driven Program
  29
  30The classic example of where callbacks are used is when writing an
  31event driven program like for an X windows application.  In this case
  32you register functions to be called whenever specific events occur,
  33e.g., a mouse button is pressed, the cursor moves into a window or a
  34menu item is selected.
  35
  36=back
  37
  38Although the techniques described here are applicable when embedding
  39Perl in a C program, this is not the primary goal of this document.
  40There are other details that must be considered and are specific to
  41embedding Perl. For details on embedding Perl in C refer to
  42L<perlembed>.
  43
  44Before you launch yourself head first into the rest of this document,
  45it would be a good idea to have read the following two documents -
  46L<perlxs> and L<perlguts>.
  47
  48=head1 THE CALL_ FUNCTIONS
  49
  50Although this stuff is easier to explain using examples, you first need
  51be aware of a few important definitions.
  52
  53Perl has a number of C functions that allow you to call Perl
  54subroutines.  They are
  55
  56    I32 call_sv(SV* sv, I32 flags) ;
  57    I32 call_pv(char *subname, I32 flags) ;
  58    I32 call_method(char *methname, I32 flags) ;
  59    I32 call_argv(char *subname, I32 flags, register char **argv) ;
  60
  61The key function is I<call_sv>.  All the other functions are
  62fairly simple wrappers which make it easier to call Perl subroutines in
  63special cases. At the end of the day they will all call I<call_sv>
  64to invoke the Perl subroutine.
  65
  66All the I<call_*> functions have a C<flags> parameter which is
  67used to pass a bit mask of options to Perl.  This bit mask operates
  68identically for each of the functions.  The settings available in the
  69bit mask are discussed in L<FLAG VALUES>.
  70
  71Each of the functions will now be discussed in turn.
  72
  73=over 5
  74
  75=item call_sv
  76
  77I<call_sv> takes two parameters, the first, C<sv>, is an SV*.
  78This allows you to specify the Perl subroutine to be called either as a
  79C string (which has first been converted to an SV) or a reference to a
  80subroutine. The section, I<Using call_sv>, shows how you can make
  81use of I<call_sv>.
  82
  83=item call_pv
  84
  85The function, I<call_pv>, is similar to I<call_sv> except it
  86expects its first parameter to be a C char* which identifies the Perl
  87subroutine you want to call, e.g., C<call_pv("fred", 0)>.  If the
  88subroutine you want to call is in another package, just include the
  89package name in the string, e.g., C<"pkg::fred">.
  90
  91=item call_method
  92
  93The function I<call_method> is used to call a method from a Perl
  94class.  The parameter C<methname> corresponds to the name of the method
  95to be called.  Note that the class that the method belongs to is passed
  96on the Perl stack rather than in the parameter list. This class can be
  97either the name of the class (for a static method) or a reference to an
  98object (for a virtual method).  See L<perlobj> for more information on
  99static and virtual methods and L<Using call_method> for an example
 100of using I<call_method>.
 101
 102=item call_argv
 103
 104I<call_argv> calls the Perl subroutine specified by the C string
 105stored in the C<subname> parameter. It also takes the usual C<flags>
 106parameter.  The final parameter, C<argv>, consists of a NULL terminated
 107list of C strings to be passed as parameters to the Perl subroutine.
 108See I<Using call_argv>.
 109
 110=back
 111
 112All the functions return an integer. This is a count of the number of
 113items returned by the Perl subroutine. The actual items returned by the
 114subroutine are stored on the Perl stack.
 115
 116As a general rule you should I<always> check the return value from
 117these functions.  Even if you are expecting only a particular number of
 118values to be returned from the Perl subroutine, there is nothing to
 119stop someone from doing something unexpected--don't say you haven't
 120been warned.
 121
 122=head1 FLAG VALUES
 123
 124The C<flags> parameter in all the I<call_*> functions is a bit mask
 125which can consist of any combination of the symbols defined below,
 126OR'ed together.
 127
 128
 129=head2  G_VOID
 130
 131Calls the Perl subroutine in a void context.
 132
 133This flag has 2 effects:
 134
 135=over 5
 136
 137=item 1.
 138
 139It indicates to the subroutine being called that it is executing in
 140a void context (if it executes I<wantarray> the result will be the
 141undefined value).
 142
 143=item 2.
 144
 145It ensures that nothing is actually returned from the subroutine.
 146
 147=back
 148
 149The value returned by the I<call_*> function indicates how many
 150items have been returned by the Perl subroutine - in this case it will
 151be 0.
 152
 153
 154=head2  G_SCALAR
 155
 156Calls the Perl subroutine in a scalar context.  This is the default
 157context flag setting for all the I<call_*> functions.
 158
 159This flag has 2 effects:
 160
 161=over 5
 162
 163=item 1.
 164
 165It indicates to the subroutine being called that it is executing in a
 166scalar context (if it executes I<wantarray> the result will be false).
 167
 168=item 2.
 169
 170It ensures that only a scalar is actually returned from the subroutine.
 171The subroutine can, of course,  ignore the I<wantarray> and return a
 172list anyway. If so, then only the last element of the list will be
 173returned.
 174
 175=back
 176
 177The value returned by the I<call_*> function indicates how many
 178items have been returned by the Perl subroutine - in this case it will
 179be either 0 or 1.
 180
 181If 0, then you have specified the G_DISCARD flag.
 182
 183If 1, then the item actually returned by the Perl subroutine will be
 184stored on the Perl stack - the section I<Returning a Scalar> shows how
 185to access this value on the stack.  Remember that regardless of how
 186many items the Perl subroutine returns, only the last one will be
 187accessible from the stack - think of the case where only one value is
 188returned as being a list with only one element.  Any other items that
 189were returned will not exist by the time control returns from the
 190I<call_*> function.  The section I<Returning a list in a scalar
 191context> shows an example of this behavior.
 192
 193
 194=head2 G_ARRAY
 195
 196Calls the Perl subroutine in a list context.
 197
 198As with G_SCALAR, this flag has 2 effects:
 199
 200=over 5
 201
 202=item 1.
 203
 204It indicates to the subroutine being called that it is executing in a
 205list context (if it executes I<wantarray> the result will be true).
 206
 207
 208=item 2.
 209
 210It ensures that all items returned from the subroutine will be
 211accessible when control returns from the I<call_*> function.
 212
 213=back
 214
 215The value returned by the I<call_*> function indicates how many
 216items have been returned by the Perl subroutine.
 217
 218If 0, then you have specified the G_DISCARD flag.
 219
 220If not 0, then it will be a count of the number of items returned by
 221the subroutine. These items will be stored on the Perl stack.  The
 222section I<Returning a list of values> gives an example of using the
 223G_ARRAY flag and the mechanics of accessing the returned items from the
 224Perl stack.
 225
 226=head2 G_DISCARD
 227
 228By default, the I<call_*> functions place the items returned from
 229by the Perl subroutine on the stack.  If you are not interested in
 230these items, then setting this flag will make Perl get rid of them
 231automatically for you.  Note that it is still possible to indicate a
 232context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
 233
 234If you do not set this flag then it is I<very> important that you make
 235sure that any temporaries (i.e., parameters passed to the Perl
 236subroutine and values returned from the subroutine) are disposed of
 237yourself.  The section I<Returning a Scalar> gives details of how to
 238dispose of these temporaries explicitly and the section I<Using Perl to
 239dispose of temporaries> discusses the specific circumstances where you
 240can ignore the problem and let Perl deal with it for you.
 241
 242=head2 G_NOARGS
 243
 244Whenever a Perl subroutine is called using one of the I<call_*>
 245functions, it is assumed by default that parameters are to be passed to
 246the subroutine.  If you are not passing any parameters to the Perl
 247subroutine, you can save a bit of time by setting this flag.  It has
 248the effect of not creating the C<@_> array for the Perl subroutine.
 249
 250Although the functionality provided by this flag may seem
 251straightforward, it should be used only if there is a good reason to do
 252so.  The reason for being cautious is that even if you have specified
 253the G_NOARGS flag, it is still possible for the Perl subroutine that
 254has been called to think that you have passed it parameters.
 255
 256In fact, what can happen is that the Perl subroutine you have called
 257can access the C<@_> array from a previous Perl subroutine.  This will
 258occur when the code that is executing the I<call_*> function has
 259itself been called from another Perl subroutine. The code below
 260illustrates this
 261
 262    sub fred
 263      { print "@_\n"  }
 264
 265    sub joe
 266      { &fred }
 267
 268    &joe(1,2,3) ;
 269
 270This will print
 271
 272    1 2 3
 273
 274What has happened is that C<fred> accesses the C<@_> array which
 275belongs to C<joe>.
 276
 277
 278=head2 G_EVAL
 279
 280It is possible for the Perl subroutine you are calling to terminate
 281abnormally, e.g., by calling I<die> explicitly or by not actually
 282existing.  By default, when either of these events occurs, the
 283process will terminate immediately.  If you want to trap this
 284type of event, specify the G_EVAL flag.  It will put an I<eval { }>
 285around the subroutine call.
 286
 287Whenever control returns from the I<call_*> function you need to
 288check the C<$@> variable as you would in a normal Perl script.
 289
 290The value returned from the I<call_*> function is dependent on
 291what other flags have been specified and whether an error has
 292occurred.  Here are all the different cases that can occur:
 293
 294=over 5
 295
 296=item *
 297
 298If the I<call_*> function returns normally, then the value
 299returned is as specified in the previous sections.
 300
 301=item *
 302
 303If G_DISCARD is specified, the return value will always be 0.
 304
 305=item *
 306
 307If G_ARRAY is specified I<and> an error has occurred, the return value
 308will always be 0.
 309
 310=item *
 311
 312If G_SCALAR is specified I<and> an error has occurred, the return value
 313will be 1 and the value on the top of the stack will be I<undef>. This
 314means that if you have already detected the error by checking C<$@> and
 315you want the program to continue, you must remember to pop the I<undef>
 316from the stack.
 317
 318=back
 319
 320See I<Using G_EVAL> for details on using G_EVAL.
 321
 322=head2 G_KEEPERR
 323
 324You may have noticed that using the G_EVAL flag described above will
 325B<always> clear the C<$@> variable and set it to a string describing
 326the error iff there was an error in the called code.  This unqualified
 327resetting of C<$@> can be problematic in the reliable identification of
 328errors using the C<eval {}> mechanism, because the possibility exists
 329that perl will call other code (end of block processing code, for
 330example) between the time the error causes C<$@> to be set within
 331C<eval {}>, and the subsequent statement which checks for the value of
 332C<$@> gets executed in the user's script.
 333
 334This scenario will mostly be applicable to code that is meant to be
 335called from within destructors, asynchronous callbacks, signal
 336handlers, C<__DIE__> or C<__WARN__> hooks, and C<tie> functions.  In
 337such situations, you will not want to clear C<$@> at all, but simply to
 338append any new errors to any existing value of C<$@>.
 339
 340The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
 341I<call_*> functions that are used to implement such code.  This flag
 342has no effect when G_EVAL is not used.
 343
 344When G_KEEPERR is used, any errors in the called code will be prefixed
 345with the string "\t(in cleanup)", and appended to the current value
 346of C<$@>.
 347
 348The G_KEEPERR flag was introduced in Perl version 5.002.
 349
 350See I<Using G_KEEPERR> for an example of a situation that warrants the
 351use of this flag.
 352
 353=head2 Determining the Context
 354
 355As mentioned above, you can determine the context of the currently
 356executing subroutine in Perl with I<wantarray>.  The equivalent test
 357can be made in C by using the C<GIMME_V> macro, which returns
 358C<G_ARRAY> if you have been called in a list context, C<G_SCALAR> if
 359in a scalar context, or C<G_VOID> if in a void context (i.e. the
 360return value will not be used).  An older version of this macro is
 361called C<GIMME>; in a void context it returns C<G_SCALAR> instead of
 362C<G_VOID>.  An example of using the C<GIMME_V> macro is shown in
 363section I<Using GIMME_V>.
 364
 365=head1 KNOWN PROBLEMS
 366
 367This section outlines all known problems that exist in the
 368I<call_*> functions.
 369
 370=over 5
 371
 372=item 1.
 373
 374If you are intending to make use of both the G_EVAL and G_SCALAR flags
 375in your code, use a version of Perl greater than 5.000.  There is a bug
 376in version 5.000 of Perl which means that the combination of these two
 377flags will not work as described in the section I<FLAG VALUES>.
 378
 379Specifically, if the two flags are used when calling a subroutine and
 380that subroutine does not call I<die>, the value returned by
 381I<call_*> will be wrong.
 382
 383
 384=item 2.
 385
 386In Perl 5.000 and 5.001 there is a problem with using I<call_*> if
 387the Perl sub you are calling attempts to trap a I<die>.
 388
 389The symptom of this problem is that the called Perl sub will continue
 390to completion, but whenever it attempts to pass control back to the
 391XSUB, the program will immediately terminate.
 392
 393For example, say you want to call this Perl sub
 394
 395    sub fred
 396    {
 397        eval { die "Fatal Error" ; }
 398        print "Trapped error: $@\n"
 399            if $@ ;
 400    }
 401
 402via this XSUB
 403
 404    void
 405    Call_fred()
 406        CODE:
 407        PUSHMARK(SP) ;
 408        call_pv("fred", G_DISCARD|G_NOARGS) ;
 409        fprintf(stderr, "back in Call_fred\n") ;
 410
 411When C<Call_fred> is executed it will print
 412
 413    Trapped error: Fatal Error
 414
 415As control never returns to C<Call_fred>, the C<"back in Call_fred">
 416string will not get printed.
 417
 418To work around this problem, you can either upgrade to Perl 5.002 or
 419higher, or use the G_EVAL flag with I<call_*> as shown below
 420
 421    void
 422    Call_fred()
 423        CODE:
 424        PUSHMARK(SP) ;
 425        call_pv("fred", G_EVAL|G_DISCARD|G_NOARGS) ;
 426        fprintf(stderr, "back in Call_fred\n") ;
 427
 428=back
 429
 430
 431
 432=head1 EXAMPLES
 433
 434Enough of the definition talk, let's have a few examples.
 435
 436Perl provides many macros to assist in accessing the Perl stack.
 437Wherever possible, these macros should always be used when interfacing
 438to Perl internals.  We hope this should make the code less vulnerable
 439to any changes made to Perl in the future.
 440
 441Another point worth noting is that in the first series of examples I
 442have made use of only the I<call_pv> function.  This has been done
 443to keep the code simpler and ease you into the topic.  Wherever
 444possible, if the choice is between using I<call_pv> and
 445I<call_sv>, you should always try to use I<call_sv>.  See
 446I<Using call_sv> for details.
 447
 448=head2 No Parameters, Nothing returned
 449
 450This first trivial example will call a Perl subroutine, I<PrintUID>, to
 451print out the UID of the process.
 452
 453    sub PrintUID
 454    {
 455        print "UID is $<\n" ;
 456    }
 457
 458and here is a C function to call it
 459
 460    static void
 461    call_PrintUID()
 462    {
 463        dSP ;
 464
 465        PUSHMARK(SP) ;
 466        call_pv("PrintUID", G_DISCARD|G_NOARGS) ;
 467    }
 468
 469Simple, eh.
 470
 471A few points to note about this example.
 472
 473=over 5
 474
 475=item 1.
 476
 477Ignore C<dSP> and C<PUSHMARK(SP)> for now. They will be discussed in
 478the next example.
 479
 480=item 2.
 481
 482We aren't passing any parameters to I<PrintUID> so G_NOARGS can be
 483specified.
 484
 485=item 3.
 486
 487We aren't interested in anything returned from I<PrintUID>, so
 488G_DISCARD is specified. Even if I<PrintUID> was changed to
 489return some value(s), having specified G_DISCARD will mean that they
 490will be wiped by the time control returns from I<call_pv>.
 491
 492=item 4.
 493
 494As I<call_pv> is being used, the Perl subroutine is specified as a
 495C string. In this case the subroutine name has been 'hard-wired' into the
 496code.
 497
 498=item 5.
 499
 500Because we specified G_DISCARD, it is not necessary to check the value
 501returned from I<call_pv>. It will always be 0.
 502
 503=back
 504
 505=head2 Passing Parameters
 506
 507Now let's make a slightly more complex example. This time we want to
 508call a Perl subroutine, C<LeftString>, which will take 2 parameters--a
 509string ($s) and an integer ($n).  The subroutine will simply
 510print the first $n characters of the string.
 511
 512So the Perl subroutine would look like this
 513
 514    sub LeftString
 515    {
 516        my($s, $n) = @_ ;
 517        print substr($s, 0, $n), "\n" ;
 518    }
 519
 520The C function required to call I<LeftString> would look like this.
 521
 522    static void
 523    call_LeftString(a, b)
 524    char * a ;
 525    int b ;
 526    {
 527        dSP ;
 528
 529	ENTER ;
 530        SAVETMPS ;
 531
 532        PUSHMARK(SP) ;
 533        XPUSHs(sv_2mortal(newSVpv(a, 0)));
 534        XPUSHs(sv_2mortal(newSViv(b)));
 535        PUTBACK ;
 536
 537        call_pv("LeftString", G_DISCARD);
 538
 539        FREETMPS ;
 540        LEAVE ;
 541    }
 542
 543Here are a few notes on the C function I<call_LeftString>.
 544
 545=over 5
 546
 547=item 1.
 548
 549Parameters are passed to the Perl subroutine using the Perl stack.
 550This is the purpose of the code beginning with the line C<dSP> and
 551ending with the line C<PUTBACK>.  The C<dSP> declares a local copy
 552of the stack pointer.  This local copy should B<always> be accessed
 553as C<SP>.
 554
 555=item 2.
 556
 557If you are going to put something onto the Perl stack, you need to know
 558where to put it. This is the purpose of the macro C<dSP>--it declares
 559and initializes a I<local> copy of the Perl stack pointer.
 560
 561All the other macros which will be used in this example require you to
 562have used this macro.
 563
 564The exception to this rule is if you are calling a Perl subroutine
 565directly from an XSUB function. In this case it is not necessary to
 566use the C<dSP> macro explicitly--it will be declared for you
 567automatically.
 568
 569=item 3.
 570
 571Any parameters to be pushed onto the stack should be bracketed by the
 572C<PUSHMARK> and C<PUTBACK> macros.  The purpose of these two macros, in
 573this context, is to count the number of parameters you are
 574pushing automatically.  Then whenever Perl is creating the C<@_> array for the
 575subroutine, it knows how big to make it.
 576
 577The C<PUSHMARK> macro tells Perl to make a mental note of the current
 578stack pointer. Even if you aren't passing any parameters (like the
 579example shown in the section I<No Parameters, Nothing returned>) you
 580must still call the C<PUSHMARK> macro before you can call any of the
 581I<call_*> functions--Perl still needs to know that there are no
 582parameters.
 583
 584The C<PUTBACK> macro sets the global copy of the stack pointer to be
 585the same as our local copy. If we didn't do this I<call_pv>
 586wouldn't know where the two parameters we pushed were--remember that
 587up to now all the stack pointer manipulation we have done is with our
 588local copy, I<not> the global copy.
 589
 590=item 4.
 591
 592Next, we come to XPUSHs. This is where the parameters actually get
 593pushed onto the stack. In this case we are pushing a string and an
 594integer.
 595
 596See L<perlguts/"XSUBs and the Argument Stack"> for details
 597on how the XPUSH macros work.
 598
 599=item 5.
 600
 601Because we created temporary values (by means of sv_2mortal() calls)
 602we will have to tidy up the Perl stack and dispose of mortal SVs.
 603
 604This is the purpose of
 605
 606    ENTER ;
 607    SAVETMPS ;
 608
 609at the start of the function, and
 610
 611    FREETMPS ;
 612    LEAVE ;
 613
 614at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
 615temporaries we create.  This means that the temporaries we get rid of
 616will be limited to those which were created after these calls.
 617
 618The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
 619the Perl subroutine (see next example), plus it will also dump the
 620mortal SVs we have created.  Having C<ENTER>/C<SAVETMPS> at the
 621beginning of the code makes sure that no other mortals are destroyed.
 622
 623Think of these macros as working a bit like using C<{> and C<}> in Perl
 624to limit the scope of local variables.
 625
 626See the section I<Using Perl to dispose of temporaries> for details of
 627an alternative to using these macros.
 628
 629=item 6.
 630
 631Finally, I<LeftString> can now be called via the I<call_pv> function.
 632The only flag specified this time is G_DISCARD. Because we are passing
 6332 parameters to the Perl subroutine this time, we have not specified
 634G_NOARGS.
 635
 636=back
 637
 638=head2 Returning a Scalar
 639
 640Now for an example of dealing with the items returned from a Perl
 641subroutine.
 642
 643Here is a Perl subroutine, I<Adder>, that takes 2 integer parameters
 644and simply returns their sum.
 645
 646    sub Adder
 647    {
 648        my($a, $b) = @_ ;
 649        $a + $b ;
 650    }
 651
 652Because we are now concerned with the return value from I<Adder>, the C
 653function required to call it is now a bit more complex.
 654
 655    static void
 656    call_Adder(a, b)
 657    int a ;
 658    int b ;
 659    {
 660        dSP ;
 661        int count ;
 662
 663        ENTER ;
 664        SAVETMPS;
 665
 666        PUSHMARK(SP) ;
 667        XPUSHs(sv_2mortal(newSViv(a)));
 668        XPUSHs(sv_2mortal(newSViv(b)));
 669        PUTBACK ;
 670
 671        count = call_pv("Adder", G_SCALAR);
 672
 673        SPAGAIN ;
 674
 675        if (count != 1)
 676            croak("Big trouble\n") ;
 677
 678        printf ("The sum of %d and %d is %d\n", a, b, POPi) ;
 679
 680        PUTBACK ;
 681        FREETMPS ;
 682        LEAVE ;
 683    }
 684
 685Points to note this time are
 686
 687=over 5
 688
 689=item 1.
 690
 691The only flag specified this time was G_SCALAR. That means the C<@_>
 692array will be created and that the value returned by I<Adder> will
 693still exist after the call to I<call_pv>.
 694
 695=item 2.
 696
 697The purpose of the macro C<SPAGAIN> is to refresh the local copy of the
 698stack pointer. This is necessary because it is possible that the memory
 699allocated to the Perl stack has been reallocated whilst in the
 700I<call_pv> call.
 701
 702If you are making use of the Perl stack pointer in your code you must
 703always refresh the local copy using SPAGAIN whenever you make use
 704of the I<call_*> functions or any other Perl internal function.
 705
 706=item 3.
 707
 708Although only a single value was expected to be returned from I<Adder>,
 709it is still good practice to check the return code from I<call_pv>
 710anyway.
 711
 712Expecting a single value is not quite the same as knowing that there
 713will be one. If someone modified I<Adder> to return a list and we
 714didn't check for that possibility and take appropriate action the Perl
 715stack would end up in an inconsistent state. That is something you
 716I<really> don't want to happen ever.
 717
 718=item 4.
 719
 720The C<POPi> macro is used here to pop the return value from the stack.
 721In this case we wanted an integer, so C<POPi> was used.
 722
 723
 724Here is the complete list of POP macros available, along with the types
 725they return.
 726
 727    POPs	SV
 728    POPp	pointer
 729    POPn	double
 730    POPi	integer
 731    POPl	long
 732
 733=item 5.
 734
 735The final C<PUTBACK> is used to leave the Perl stack in a consistent
 736state before exiting the function.  This is necessary because when we
 737popped the return value from the stack with C<POPi> it updated only our
 738local copy of the stack pointer.  Remember, C<PUTBACK> sets the global
 739stack pointer to be the same as our local copy.
 740
 741=back
 742
 743
 744=head2 Returning a list of values
 745
 746Now, let's extend the previous example to return both the sum of the
 747parameters and the difference.
 748
 749Here is the Perl subroutine
 750
 751    sub AddSubtract
 752    {
 753       my($a, $b) = @_ ;
 754       ($a+$b, $a-$b) ;
 755    }
 756
 757and this is the C function
 758
 759    static void
 760    call_AddSubtract(a, b)
 761    int a ;
 762    int b ;
 763    {
 764        dSP ;
 765        int count ;
 766
 767        ENTER ;
 768        SAVETMPS;
 769
 770        PUSHMARK(SP) ;
 771        XPUSHs(sv_2mortal(newSViv(a)));
 772        XPUSHs(sv_2mortal(newSViv(b)));
 773        PUTBACK ;
 774
 775        count = call_pv("AddSubtract", G_ARRAY);
 776
 777        SPAGAIN ;
 778
 779        if (count != 2)
 780            croak("Big trouble\n") ;
 781
 782        printf ("%d - %d = %d\n", a, b, POPi) ;
 783        printf ("%d + %d = %d\n", a, b, POPi) ;
 784
 785        PUTBACK ;
 786        FREETMPS ;
 787        LEAVE ;
 788    }
 789
 790If I<call_AddSubtract> is called like this
 791
 792    call_AddSubtract(7, 4) ;
 793
 794then here is the output
 795
 796    7 - 4 = 3
 797    7 + 4 = 11
 798
 799Notes
 800
 801=over 5
 802
 803=item 1.
 804
 805We wanted list context, so G_ARRAY was used.
 806
 807=item 2.
 808
 809Not surprisingly C<POPi> is used twice this time because we were
 810retrieving 2 values from the stack. The important thing to note is that
 811when using the C<POP*> macros they come off the stack in I<reverse>
 812order.
 813
 814=back
 815
 816=head2 Returning a list in a scalar context
 817
 818Say the Perl subroutine in the previous section was called in a scalar
 819context, like this
 820
 821    static void
 822    call_AddSubScalar(a, b)
 823    int a ;
 824    int b ;
 825    {
 826        dSP ;
 827        int count ;
 828        int i ;
 829
 830        ENTER ;
 831        SAVETMPS;
 832
 833        PUSHMARK(SP) ;
 834        XPUSHs(sv_2mortal(newSViv(a)));
 835        XPUSHs(sv_2mortal(newSViv(b)));
 836        PUTBACK ;
 837
 838        count = call_pv("AddSubtract", G_SCALAR);
 839
 840        SPAGAIN ;
 841
 842        printf ("Items Returned = %d\n", count) ;
 843
 844        for (i = 1 ; i <= count ; ++i)
 845            printf ("Value %d = %d\n", i, POPi) ;
 846
 847        PUTBACK ;
 848        FREETMPS ;
 849        LEAVE ;
 850    }
 851
 852The other modification made is that I<call_AddSubScalar> will print the
 853number of items returned from the Perl subroutine and their value (for
 854simplicity it assumes that they are integer).  So if
 855I<call_AddSubScalar> is called
 856
 857    call_AddSubScalar(7, 4) ;
 858
 859then the output will be
 860
 861    Items Returned = 1
 862    Value 1 = 3
 863
 864In this case the main point to note is that only the last item in the
 865list is returned from the subroutine, I<AddSubtract> actually made it back to
 866I<call_AddSubScalar>.
 867
 868
 869=head2 Returning Data from Perl via the parameter list
 870
 871It is also possible to return values directly via the parameter list -
 872whether it is actually desirable to do it is another matter entirely.
 873
 874The Perl subroutine, I<Inc>, below takes 2 parameters and increments
 875each directly.
 876
 877    sub Inc
 878    {
 879        ++ $_[0] ;
 880        ++ $_[1] ;
 881    }
 882
 883and here is a C function to call it.
 884
 885    static void
 886    call_Inc(a, b)
 887    int a ;
 888    int b ;
 889    {
 890        dSP ;
 891        int count ;
 892        SV * sva ;
 893        SV * svb ;
 894
 895        ENTER ;
 896        SAVETMPS;
 897
 898        sva = sv_2mortal(newSViv(a)) ;
 899        svb = sv_2mortal(newSViv(b)) ;
 900
 901        PUSHMARK(SP) ;
 902        XPUSHs(sva);
 903        XPUSHs(svb);
 904        PUTBACK ;
 905
 906        count = call_pv("Inc", G_DISCARD);
 907
 908        if (count != 0)
 909            croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
 910                   count) ;
 911
 912        printf ("%d + 1 = %d\n", a, SvIV(sva)) ;
 913        printf ("%d + 1 = %d\n", b, SvIV(svb)) ;
 914
 915    	FREETMPS ;
 916        LEAVE ;
 917    }
 918
 919To be able to access the two parameters that were pushed onto the stack
 920after they return from I<call_pv> it is necessary to make a note
 921of their addresses--thus the two variables C<sva> and C<svb>.
 922
 923The reason this is necessary is that the area of the Perl stack which
 924held them will very likely have been overwritten by something else by
 925the time control returns from I<call_pv>.
 926
 927
 928
 929
 930=head2 Using G_EVAL
 931
 932Now an example using G_EVAL. Below is a Perl subroutine which computes
 933the difference of its 2 parameters. If this would result in a negative
 934result, the subroutine calls I<die>.
 935
 936    sub Subtract
 937    {
 938        my ($a, $b) = @_ ;
 939
 940        die "death can be fatal\n" if $a < $b ;
 941
 942        $a - $b ;
 943    }
 944
 945and some C to call it
 946
 947    static void
 948    call_Subtract(a, b)
 949    int a ;
 950    int b ;
 951    {
 952        dSP ;
 953        int count ;
 954
 955        ENTER ;
 956        SAVETMPS;
 957
 958        PUSHMARK(SP) ;
 959        XPUSHs(sv_2mortal(newSViv(a)));
 960        XPUSHs(sv_2mortal(newSViv(b)));
 961        PUTBACK ;
 962
 963        count = call_pv("Subtract", G_EVAL|G_SCALAR);
 964
 965        SPAGAIN ;
 966
 967        /* Check the eval first */
 968        if (SvTRUE(ERRSV))
 969        {
 970	    STRLEN n_a;
 971            printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ;
 972            POPs ;
 973        }
 974        else
 975        {
 976            if (count != 1)
 977               croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
 978                        count) ;
 979
 980            printf ("%d - %d = %d\n", a, b, POPi) ;
 981        }
 982
 983        PUTBACK ;
 984        FREETMPS ;
 985        LEAVE ;
 986    }
 987
 988If I<call_Subtract> is called thus
 989
 990    call_Subtract(4, 5)
 991
 992the following will be printed
 993
 994    Uh oh - death can be fatal
 995
 996Notes
 997
 998=over 5
 999
1000=item 1.
1001
1002We want to be able to catch the I<die> so we have used the G_EVAL
1003flag.  Not specifying this flag would mean that the program would
1004terminate immediately at the I<die> statement in the subroutine
1005I<Subtract>.
1006
1007=item 2.
1008
1009The code
1010
1011    if (SvTRUE(ERRSV))
1012    {
1013	STRLEN n_a;
1014        printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ;
1015        POPs ;
1016    }
1017
1018is the direct equivalent of this bit of Perl
1019
1020    print "Uh oh - $@\n" if $@ ;
1021
1022C<PL_errgv> is a perl global of type C<GV *> that points to the
1023symbol table entry containing the error.  C<ERRSV> therefore
1024refers to the C equivalent of C<$@>.
1025
1026=item 3.
1027
1028Note that the stack is popped using C<POPs> in the block where
1029C<SvTRUE(ERRSV)> is true.  This is necessary because whenever a
1030I<call_*> function invoked with G_EVAL|G_SCALAR returns an error,
1031the top of the stack holds the value I<undef>. Because we want the
1032program to continue after detecting this error, it is essential that
1033the stack is tidied up by removing the I<undef>.
1034
1035=back
1036
1037
1038=head2 Using G_KEEPERR
1039
1040Consider this rather facetious example, where we have used an XS
1041version of the call_Subtract example above inside a destructor:
1042
1043    package Foo;
1044    sub new { bless {}, $_[0] }
1045    sub Subtract {
1046        my($a,$b) = @_;
1047        die "death can be fatal" if $a < $b ;
1048        $a - $b;
1049    }
1050    sub DESTROY { call_Subtract(5, 4); }
1051    sub foo { die "foo dies"; }
1052
1053    package main;
1054    eval { Foo->new->foo };
1055    print "Saw: $@" if $@;             # should be, but isn't
1056
1057This example will fail to recognize that an error occurred inside the
1058C<eval {}>.  Here's why: the call_Subtract code got executed while perl
1059was cleaning up temporaries when exiting the eval block, and because
1060call_Subtract is implemented with I<call_pv> using the G_EVAL
1061flag, it promptly reset C<$@>.  This results in the failure of the
1062outermost test for C<$@>, and thereby the failure of the error trap.
1063
1064Appending the G_KEEPERR flag, so that the I<call_pv> call in
1065call_Subtract reads:
1066
1067        count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
1068
1069will preserve the error and restore reliable error handling.
1070
1071=head2 Using call_sv
1072
1073In all the previous examples I have 'hard-wired' the name of the Perl
1074subroutine to be called from C.  Most of the time though, it is more
1075convenient to be able to specify the name of the Perl subroutine from
1076within the Perl script.
1077
1078Consider the Perl code below
1079
1080    sub fred
1081    {
1082        print "Hello there\n" ;
1083    }
1084
1085    CallSubPV("fred") ;
1086
1087Here is a snippet of XSUB which defines I<CallSubPV>.
1088
1089    void
1090    CallSubPV(name)
1091    	char *	name
1092    	CODE:
1093    	PUSHMARK(SP) ;
1094    	call_pv(name, G_DISCARD|G_NOARGS) ;
1095
1096That is fine as far as it goes. The thing is, the Perl subroutine
1097can be specified as only a string.  For Perl 4 this was adequate,
1098but Perl 5 allows references to subroutines and anonymous subroutines.
1099This is where I<call_sv> is useful.
1100
1101The code below for I<CallSubSV> is identical to I<CallSubPV> except
1102that the C<name> parameter is now defined as an SV* and we use
1103I<call_sv> instead of I<call_pv>.
1104
1105    void
1106    CallSubSV(name)
1107    	SV *	name
1108    	CODE:
1109    	PUSHMARK(SP) ;
1110    	call_sv(name, G_DISCARD|G_NOARGS) ;
1111
1112Because we are using an SV to call I<fred> the following can all be used
1113
1114    CallSubSV("fred") ;
1115    CallSubSV(\&fred) ;
1116    $ref = \&fred ;
1117    CallSubSV($ref) ;
1118    CallSubSV( sub { print "Hello there\n" } ) ;
1119
1120As you can see, I<call_sv> gives you much greater flexibility in
1121how you can specify the Perl subroutine.
1122
1123You should note that if it is necessary to store the SV (C<name> in the
1124example above) which corresponds to the Perl subroutine so that it can
1125be used later in the program, it not enough just to store a copy of the
1126pointer to the SV. Say the code above had been like this
1127
1128    static SV * rememberSub ;
1129
1130    void
1131    SaveSub1(name)
1132    	SV *	name
1133    	CODE:
1134    	rememberSub = name ;
1135
1136    void
1137    CallSavedSub1()
1138    	CODE:
1139    	PUSHMARK(SP) ;
1140    	call_sv(rememberSub, G_DISCARD|G_NOARGS) ;
1141
1142The reason this is wrong is that by the time you come to use the
1143pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer
1144to the Perl subroutine that was recorded in C<SaveSub1>.  This is
1145particularly true for these cases
1146
1147    SaveSub1(\&fred) ;
1148    CallSavedSub1() ;
1149
1150    SaveSub1( sub { print "Hello there\n" } ) ;
1151    CallSavedSub1() ;
1152
1153By the time each of the C<SaveSub1> statements above have been executed,
1154the SV*s which corresponded to the parameters will no longer exist.
1155Expect an error message from Perl of the form
1156
1157    Can't use an undefined value as a subroutine reference at ...
1158
1159for each of the C<CallSavedSub1> lines.
1160
1161Similarly, with this code
1162
1163    $ref = \&fred ;
1164    SaveSub1($ref) ;
1165    $ref = 47 ;
1166    CallSavedSub1() ;
1167
1168you can expect one of these messages (which you actually get is dependent on
1169the version of Perl you are using)
1170
1171    Not a CODE reference at ...
1172    Undefined subroutine &main::47 called ...
1173
1174The variable $ref may have referred to the subroutine C<fred>
1175whenever the call to C<SaveSub1> was made but by the time
1176C<CallSavedSub1> gets called it now holds the number C<47>. Because we
1177saved only a pointer to the original SV in C<SaveSub1>, any changes to
1178$ref will be tracked by the pointer C<rememberSub>. This means that
1179whenever C<CallSavedSub1> gets called, it will attempt to execute the
1180code which is referenced by the SV* C<rememberSub>.  In this case
1181though, it now refers to the integer C<47>, so expect Perl to complain
1182loudly.
1183
1184A similar but more subtle problem is illustrated with this code
1185
1186    $ref = \&fred ;
1187    SaveSub1($ref) ;
1188    $ref = \&joe ;
1189    CallSavedSub1() ;
1190
1191This time whenever C<CallSavedSub1> get called it will execute the Perl
1192subroutine C<joe> (assuming it exists) rather than C<fred> as was
1193originally requested in the call to C<SaveSub1>.
1194
1195To get around these problems it is necessary to take a full copy of the
1196SV.  The code below shows C<SaveSub2> modified to do that
1197
1198    static SV * keepSub = (SV*)NULL ;
1199
1200    void
1201    SaveSub2(name)
1202        SV *	name
1203    	CODE:
1204     	/* Take a copy of the callback */
1205    	if (keepSub == (SV*)NULL)
1206    	    /* First time, so create a new SV */
1207    	    keepSub = newSVsv(name) ;
1208    	else
1209    	    /* Been here before, so overwrite */
1210    	    SvSetSV(keepSub, name) ;
1211
1212    void
1213    CallSavedSub2()
1214    	CODE:
1215    	PUSHMARK(SP) ;
1216    	call_sv(keepSub, G_DISCARD|G_NOARGS) ;
1217
1218To avoid creating a new SV every time C<SaveSub2> is called,
1219the function first checks to see if it has been called before.  If not,
1220then space for a new SV is allocated and the reference to the Perl
1221subroutine, C<name> is copied to the variable C<keepSub> in one
1222operation using C<newSVsv>.  Thereafter, whenever C<SaveSub2> is called
1223the existing SV, C<keepSub>, is overwritten with the new value using
1224C<SvSetSV>.
1225
1226=head2 Using call_argv
1227
1228Here is a Perl subroutine which prints whatever parameters are passed
1229to it.
1230
1231    sub PrintList
1232    {
1233        my(@list) = @_ ;
1234
1235        foreach (@list) { print "$_\n" }
1236    }
1237
1238and here is an example of I<call_argv> which will call
1239I<PrintList>.
1240
1241    static char * words[] = {"alpha", "beta", "gamma", "delta", NULL} ;
1242
1243    static void
1244    call_PrintList()
1245    {
1246        dSP ;
1247
1248        call_argv("PrintList", G_DISCARD, words) ;
1249    }
1250
1251Note that it is not necessary to call C<PUSHMARK> in this instance.
1252This is because I<call_argv> will do it for you.
1253
1254=head2 Using call_method
1255
1256Consider the following Perl code
1257
1258    {
1259        package Mine ;
1260
1261        sub new
1262        {
1263            my($type) = shift ;
1264            bless [@_]
1265        }
1266
1267        sub Display
1268        {
1269            my ($self, $index) = @_ ;
1270            print "$index: $$self[$index]\n" ;
1271        }
1272
1273        sub PrintID
1274        {
1275            my($class) = @_ ;
1276            print "This is Class $class version 1.0\n" ;
1277        }
1278    }
1279
1280It implements just a very simple class to manage an array.  Apart from
1281the constructor, C<new>, it declares methods, one static and one
1282virtual. The static method, C<PrintID>, prints out simply the class
1283name and a version number. The virtual method, C<Display>, prints out a
1284single element of the array.  Here is an all Perl example of using it.
1285
1286    $a = new Mine ('red', 'green', 'blue') ;
1287    $a->Display(1) ;
1288    PrintID Mine;
1289
1290will print
1291
1292    1: green
1293    This is Class Mine version 1.0
1294
1295Calling a Perl method from C is fairly straightforward. The following
1296things are required
1297
1298=over 5
1299
1300=item *
1301
1302a reference to the object for a virtual method or the name of the class
1303for a static method.
1304
1305=item *
1306
1307the name of the method.
1308
1309=item *
1310
1311any other parameters specific to the method.
1312
1313=back
1314
1315Here is a simple XSUB which illustrates the mechanics of calling both
1316the C<PrintID> and C<Display> methods from C.
1317
1318    void
1319    call_Method(ref, method, index)
1320        SV *	ref
1321        char *	method
1322        int		index
1323        CODE:
1324        PUSHMARK(SP);
1325        XPUSHs(ref);
1326        XPUSHs(sv_2mortal(newSViv(index))) ;
1327        PUTBACK;
1328
1329        call_method(method, G_DISCARD) ;
1330
1331    void
1332    call_PrintID(class, method)
1333        char *	class
1334        char *	method
1335        CODE:
1336        PUSHMARK(SP);
1337        XPUSHs(sv_2mortal(newSVpv(class, 0))) ;
1338        PUTBACK;
1339
1340        call_method(method, G_DISCARD) ;
1341
1342
1343So the methods C<PrintID> and C<Display> can be invoked like this
1344
1345    $a = new Mine ('red', 'green', 'blue') ;
1346    call_Method($a, 'Display', 1) ;
1347    call_PrintID('Mine', 'PrintID') ;
1348
1349The only thing to note is that in both the static and virtual methods,
1350the method name is not passed via the stack--it is used as the first
1351parameter to I<call_method>.
1352
1353=head2 Using GIMME_V
1354
1355Here is a trivial XSUB which prints the context in which it is
1356currently executing.
1357
1358    void
1359    PrintContext()
1360        CODE:
1361        I32 gimme = GIMME_V;
1362        if (gimme == G_VOID)
1363            printf ("Context is Void\n") ;
1364        else if (gimme == G_SCALAR)
1365            printf ("Context is Scalar\n") ;
1366        else
1367            printf ("Context is Array\n") ;
1368
1369and here is some Perl to test it
1370
1371    PrintContext ;
1372    $a = PrintContext ;
1373    @a = PrintContext ;
1374
1375The output from that will be
1376
1377    Context is Void
1378    Context is Scalar
1379    Context is Array
1380
1381=head2 Using Perl to dispose of temporaries
1382
1383In the examples given to date, any temporaries created in the callback
1384(i.e., parameters passed on the stack to the I<call_*> function or
1385values returned via the stack) have been freed by one of these methods
1386
1387=over 5
1388
1389=item *
1390
1391specifying the G_DISCARD flag with I<call_*>.
1392
1393=item *
1394
1395explicitly disposed of using the C<ENTER>/C<SAVETMPS> -
1396C<FREETMPS>/C<LEAVE> pairing.
1397
1398=back
1399
1400There is another method which can be used, namely letting Perl do it
1401for you automatically whenever it regains control after the callback
1402has terminated.  This is done by simply not using the
1403
1404    ENTER ;
1405    SAVETMPS ;
1406    ...
1407    FREETMPS ;
1408    LEAVE ;
1409
1410sequence in the callback (and not, of course, specifying the G_DISCARD
1411flag).
1412
1413If you are going to use this method you have to be aware of a possible
1414memory leak which can arise under very specific circumstances.  To
1415explain these circumstances you need to know a bit about the flow of
1416control between Perl and the callback routine.
1417
1418The examples given at the start of the document (an error handler and
1419an event driven program) are typical of the two main sorts of flow
1420control that you are likely to encounter with callbacks.  There is a
1421very important distinction between them, so pay attention.
1422
1423In the first example, an error handler, the flow of control could be as
1424follows.  You have created an interface to an external library.
1425Control can reach the external library like this
1426
1427    perl --> XSUB --> external library
1428
1429Whilst control is in the library, an error condition occurs. You have
1430previously set up a Perl callback to handle this situation, so it will
1431get executed. Once the callback has finished, control will drop back to
1432Perl again.  Here is what the flow of control will be like in that
1433situation
1434
1435    perl --> XSUB --> external library
1436                      ...
1437                      error occurs
1438                      ...
1439                      external library --> call_* --> perl
1440                                                          |
1441    perl <-- XSUB <-- external library <-- call_* <----+
1442
1443After processing of the error using I<call_*> is completed,
1444control reverts back to Perl more or less immediately.
1445
1446In the diagram, the further right you go the more deeply nested the
1447scope is.  It is only when control is back with perl on the extreme
1448left of the diagram that you will have dropped back to the enclosing
1449scope and any temporaries you have left hanging around will be freed.
1450
1451In the second example, an event driven program, the flow of control
1452will be more like this
1453
1454    perl --> XSUB --> event handler
1455                      ...
1456                      event handler --> call_* --> perl
1457                                                       |
1458                      event handler <-- call_* <----+
1459                      ...
1460                      event handler --> call_* --> perl
1461                                                       |
1462                      event handler <-- call_* <----+
1463                      ...
1464                      event handler --> call_* --> perl
1465                                                       |
1466                      event handler <-- call_* <----+
1467
1468In this case the flow of control can consist of only the repeated
1469sequence
1470
1471    event handler --> call_* --> perl
1472
1473for practically the complete duration of the program.  This means that
1474control may I<never> drop back to the surrounding scope in Perl at the
1475extreme left.
1476
1477So what is the big problem? Well, if you are expecting Perl to tidy up
1478those temporaries for you, you might be in for a long wait.  For Perl
1479to dispose of your temporaries, control must drop back to the
1480enclosing scope at some stage.  In the event driven scenario that may
1481never happen.  This means that as time goes on, your program will
1482create more and more temporaries, none of which will ever be freed. As
1483each of these temporaries consumes some memory your program will
1484eventually consume all the available memory in your system--kapow!
1485
1486So here is the bottom line--if you are sure that control will revert
1487back to the enclosing Perl scope fairly quickly after the end of your
1488callback, then it isn't absolutely necessary to dispose explicitly of
1489any temporaries you may have created. Mind you, if you are at all
1490uncertain about what to do, it doesn't do any harm to tidy up anyway.
1491
1492
1493=head2 Strategies for storing Callback Context Information
1494
1495
1496Potentially one of the trickiest problems to overcome when designing a
1497callback interface can be figuring out how to store the mapping between
1498the C callback function and the Perl equivalent.
1499
1500To help understand why this can be a real problem first consider how a
1501callback is set up in an all C environment.  Typically a C API will
1502provide a function to register a callback.  This will expect a pointer
1503to a function as one of its parameters.  Below is a call to a
1504hypothetical function C<register_fatal> which registers the C function
1505to get called when a fatal error occurs.
1506
1507    register_fatal(cb1) ;
1508
1509The single parameter C<cb1> is a pointer to a function, so you must
1510have defined C<cb1> in your code, say something like this
1511
1512    static void
1513    cb1()
1514    {
1515        printf ("Fatal Error\n") ;
1516        exit(1) ;
1517    }
1518
1519Now change that to call a Perl subroutine instead
1520
1521    static SV * callback = (SV*)NULL;
1522
1523    static void
1524    cb1()
1525    {
1526        dSP ;
1527
1528        PUSHMARK(SP) ;
1529
1530        /* Call the Perl sub to process the callback */
1531        call_sv(callback, G_DISCARD) ;
1532    }
1533
1534
1535    void
1536    register_fatal(fn)
1537        SV *	fn
1538        CODE:
1539        /* Remember the Perl sub */
1540        if (callback == (SV*)NULL)
1541            callback = newSVsv(fn) ;
1542        else
1543            SvSetSV(callback, fn) ;
1544
1545        /* register the callback with the external library */
1546        register_fatal(cb1) ;
1547
1548where the Perl equivalent of C<register_fatal> and the callback it
1549registers, C<pcb1>, might look like this
1550
1551    # Register the sub pcb1
1552    register_fatal(\&pcb1) ;
1553
1554    sub pcb1
1555    {
1556        die "I'm dying...\n" ;
1557    }
1558
1559The mapping between the C callback and the Perl equivalent is stored in
1560the global variable C<callback>.
1561
1562This will be adequate if you ever need to have only one callback
1563registered at any time. An example could be an error handler like the
1564code sketched out above. Remember though, repeated calls to
1565C<register_fatal> will replace the previously registered callback
1566function with the new one.
1567
1568Say for example you want to interface to a library which allows asynchronous
1569file i/o.  In this case you may be able to register a callback whenever
1570a read operation has completed. To be of any use we want to be able to
1571call separate Perl subroutines for each file that is opened.  As it
1572stands, the error handler example above would not be adequate as it
1573allows only a single callback to be defined at any time. What we
1574require is a means of storing the mapping between the opened file and
1575the Perl subroutine we want to be called for that file.
1576
1577Say the i/o library has a function C<asynch_read> which associates a C
1578function C<ProcessRead> with a file handle C<fh>--this assumes that it
1579has also provided some routine to open the file and so obtain the file
1580handle.
1581
1582    asynch_read(fh, ProcessRead)
1583
1584This may expect the C I<ProcessRead> function of this form
1585
1586    void
1587    ProcessRead(fh, buffer)
1588    int	fh ;
1589    char *	buffer ;
1590    {
1591         ...
1592    }
1593
1594To provide a Perl interface to this library we need to be able to map
1595between the C<fh> parameter and the Perl subroutine we want called.  A
1596hash is a convenient mechanism for storing this mapping.  The code
1597below shows a possible implementation
1598
1599    static HV * Mapping = (HV*)NULL ;
1600
1601    void
1602    asynch_read(fh, callback)
1603        int	fh
1604        SV *	callback
1605        CODE:
1606        /* If the hash doesn't already exist, create it */
1607        if (Mapping == (HV*)NULL)
1608            Mapping = newHV() ;
1609
1610        /* Save the fh -> callback mapping */
1611        hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0) ;
1612
1613        /* Register with the C Library */
1614        asynch_read(fh, asynch_read_if) ;
1615
1616and C<asynch_read_if> could look like this
1617
1618    static void
1619    asynch_read_if(fh, buffer)
1620    int	fh ;
1621    char *	buffer ;
1622    {
1623        dSP ;
1624        SV ** sv ;
1625
1626        /* Get the callback associated with fh */
1627        sv =  hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE) ;
1628        if (sv == (SV**)NULL)
1629            croak("Internal error...\n") ;
1630
1631        PUSHMARK(SP) ;
1632        XPUSHs(sv_2mortal(newSViv(fh))) ;
1633        XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
1634        PUTBACK ;
1635
1636        /* Call the Perl sub */
1637        call_sv(*sv, G_DISCARD) ;
1638    }
1639
1640For completeness, here is C<asynch_close>.  This shows how to remove
1641the entry from the hash C<Mapping>.
1642
1643    void
1644    asynch_close(fh)
1645        int	fh
1646        CODE:
1647        /* Remove the entry from the hash */
1648        (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD) ;
1649
1650        /* Now call the real asynch_close */
1651        asynch_close(fh) ;
1652
1653So the Perl interface would look like this
1654
1655    sub callback1
1656    {
1657        my($handle, $buffer) = @_ ;
1658    }
1659
1660    # Register the Perl callback
1661    asynch_read($fh, \&callback1) ;
1662
1663    asynch_close($fh) ;
1664
1665The mapping between the C callback and Perl is stored in the global
1666hash C<Mapping> this time. Using a hash has the distinct advantage that
1667it allows an unlimited number of callbacks to be registered.
1668
1669What if the interface provided by the C callback doesn't contain a
1670parameter which allows the file handle to Perl subroutine mapping?  Say
1671in the asynchronous i/o package, the callback function gets passed only
1672the C<buffer> parameter like this
1673
1674    void
1675    ProcessRead(buffer)
1676    char *	buffer ;
1677    {
1678        ...
1679    }
1680
1681Without the file handle there is no straightforward way to map from the
1682C callback

Large files files are truncated, but you can click here to view the full file