mingw/html/pod/perlcall.html

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