[Summary view] [Print] [Text view]

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