|
The flags parameter in all the call_* functions is a bit mask which can
consist of any combination of the symbols defined below, OR'ed together.
Calls the Perl subroutine in a void context.
This flag has 2 effects:
- 1.
- It indicates to the subroutine being called that it is executing in a void context (if
it executes wantarray the result will be the undefined value).
- 2.
- It ensures that nothing is actually returned from the subroutine.
The value returned by the call_* function indicates how many items have been
returned by the Perl subroutine - in this case it will be 0.
Calls the Perl subroutine in a scalar context. This is the default context flag setting for
all the call_* functions.
This flag has 2 effects:
- 1.
- It indicates to the subroutine being called that it is executing in a scalar context (if
it executes wantarray the result will be false).
- 2.
- It ensures that only a scalar is actually returned from the subroutine. The subroutine
can, of course, ignore the wantarray and return a list anyway. If so, then only the
last element of the list will be returned.
The value returned by the call_* function indicates how many items have been
returned by the Perl subroutine - in this case it will be either 0 or 1.
If 0, then you have specified the G_DISCARD flag.
If 1, then the item actually returned by the Perl subroutine will be stored on the Perl
stack - the section Returning a Scalar shows how to access this value on the stack.
Remember that regardless of how many items the Perl subroutine returns, only the last one will
be accessible from the stack - think of the case where only one value is returned as being a
list with only one element. Any other items that were returned will not exist by the time
control returns from the call_* function. The section Returning a list in a scalar
context shows an example of this behavior.
Calls the Perl subroutine in a list context.
As with G_SCALAR, this flag has 2 effects:
- 1.
- It indicates to the subroutine being called that it is executing in a list context (if
it executes wantarray the result will be true).
- 2.
- It ensures that all items returned from the subroutine will be accessible when control
returns from the call_* function.
The value returned by the call_* function indicates how many items have been
returned by the Perl subroutine.
If 0, then you have specified the G_DISCARD flag.
If not 0, then it will be a count of the number of items returned by the subroutine. These
items will be stored on the Perl stack. The section Returning a list of values gives an
example of using the G_ARRAY flag and the mechanics of accessing the returned items from the
Perl stack.
By default, the call_* functions place the items returned from by the Perl
subroutine on the stack. If you are not interested in these items, then setting this flag will
make Perl get rid of them automatically for you. Note that it is still possible to indicate a
context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
If you do not set this flag then it is very important that you make sure that any
temporaries (i.e., parameters passed to the Perl subroutine and values returned from the
subroutine) are disposed of yourself. The section Returning a Scalar gives details of
how to dispose of these temporaries explicitly and the section Using Perl to dispose of
temporaries discusses the specific circumstances where you can ignore the problem and let
Perl deal with it for you.
Whenever a Perl subroutine is called using one of the call_* functions, it is
assumed by default that parameters are to be passed to the subroutine. If you are not passing
any parameters to the Perl subroutine, you can save a bit of time by setting this flag. It has
the effect of not creating the @_ array for the Perl subroutine.
Although the functionality provided by this flag may seem straightforward, it should be
used only if there is a good reason to do so. The reason for being cautious is that even if
you have specified the G_NOARGS flag, it is still possible for the Perl subroutine that has
been called to think that you have passed it parameters.
In fact, what can happen is that the Perl subroutine you have called can access the @_
array from a previous Perl subroutine. This will occur when the code that is executing the call_*
function has itself been called from another Perl subroutine. The code below illustrates this
sub fred
{ print "@_\n" }
sub joe
{ &fred }
&joe(1,2,3) ;
|
|
This will print
What has happened is that fred accesses the @_ array which
belongs to joe.
It is possible for the Perl subroutine you are calling to terminate abnormally, e.g., by
calling die explicitly or by not actually existing. By default, when either of these
events occurs, the process will terminate immediately. If you want to trap this type of event,
specify the G_EVAL flag. It will put an eval { } around the subroutine call.
Whenever control returns from the call_* function you need to check the $@
variable as you would in a normal Perl script.
The value returned from the call_* function is dependent on what other flags have
been specified and whether an error has occurred. Here are all the different cases that can
occur:
- If the call_* function returns normally, then the value returned is as specified
in the previous sections.
- If G_DISCARD is specified, the return value will always be 0.
- If G_ARRAY is specified and an error has occurred, the return value will always
be 0.
- If G_SCALAR is specified and an error has occurred, the return value will be 1
and the value on the top of the stack will be undef. This means that if you have
already detected the error by checking
$@ and you want the program to
continue, you must remember to pop the undef from the stack.
See Using G_EVAL for details on using G_EVAL.
You may have noticed that using the G_EVAL flag described above will always clear
the $@ variable and set it to a string describing the error iff there was an
error in the called code. This unqualified resetting of $@ can be problematic in
the reliable identification of errors using the eval {} mechanism, because the
possibility exists that perl will call other code (end of block processing code, for example)
between the time the error causes $@ to be set within eval {}, and
the subsequent statement which checks for the value of $@ gets executed in the
user's script.
This scenario will mostly be applicable to code that is meant to be called from within
destructors, asynchronous callbacks, signal handlers, __DIE__ or __WARN__
hooks, and tie functions. In such situations, you will not want to clear $@
at all, but simply to append any new errors to any existing value of $@.
The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in call_*
functions that are used to implement such code. This flag has no effect when G_EVAL is not
used.
When G_KEEPERR is used, any errors in the called code will be prefixed with the string
"\t(in cleanup)", and appended to the current value of $@.
The G_KEEPERR flag was introduced in Perl version 5.002.
See Using G_KEEPERR for an example of a situation that warrants the use of this
flag.
As mentioned above, you can determine the context of the currently executing subroutine in
Perl with wantarray. The equivalent test can be made in C by using the GIMME_V
macro, which returns G_ARRAY if you have been called in a list context, G_SCALAR
if in a scalar context, or G_VOID if in a void context (i.e. the return value
will not be used). An older version of this macro is called GIMME; in a void
context it returns G_SCALAR instead of G_VOID. An example of using
the GIMME_V macro is shown in section Using GIMME_V.
|
