++ed by:
ABRAXXA ADAMJS ALEXBIO ANDREFS ARJONES

117 PAUSE user(s)
93 non-PAUSE user(s).

Ricardo SIGNES

Available only under threaded builds, this function allocates an entry in PL_stashpad for the stash passed to it.

Applies a syntactic context to an op tree representing an expression. o is the op tree, and context must be G_SCALAR, G_ARRAY, or G_VOID to specify the context to apply. The modified op tree is returned.

Optree Manipulation Functions

This function finalizes the optree. Should be called directly after the complete optree is built. It does some additional checking which can't be done in the normal ck_xxx functions and makes the tree thread-safe.

Propagate lvalue ("modifiable") context to an op and its children. type represents the context type, roughly based on the type of op that would do the modifying, although local() is represented by OP_NULL, because it has no op type of its own (it is signalled by a flag on the lvalue op).

This function detects things that can't be modified, such as $x+1, and generates errors for them. For example, $x+1 = 2 would cause it to be called with an op of type OP_ADD and a type argument of OP_SASSIGN.

It also flags things that need to behave specially in an lvalue context, such as $$x = 5 which might have to vivify a reference in $x.

Attempts to apply a list of attributes specified by the attrstr and len arguments to the subroutine identified by the cv argument which is expected to be associated with the package identified by the stashpv argument (see attributes). It gets this wrong, though, in that it does not correctly identify the boundaries of the individual attribute specifications within attrstr. This is not really intended for the public API, but has to be listed here for systems such as AIX which need an explicit export list for symbols. (It's called from XS code in support of the ATTRS: keyword from xsubpp.) Patches to fix it to respect attribute syntax properly would be welcome.

Wraps up an op tree with some additional ops so that at runtime a dynamic scope will be created. The original ops run in the new dynamic scope, and then, provided that they exit normally, the scope will be unwound. The additional ops used to create and unwind the dynamic scope will normally be an enter/leave pair, but a scope op may be used instead if the ops are simple enough to not need the full dynamic scope structure.

Compile-time scope hooks

Register a set of hooks to be called when the Perl lexical scope changes at compile time. See "Compile-time scope hooks" in perlguts.

Optree Manipulation Functions */

/* List constructors */

/* =for apidoc Am|OP *|op_append_elem|I32 optype|OP *first|OP *last

Append an item to the list of ops contained directly within a list-type op, returning the lengthened list. first is the list-type op, and last is the op to append to the list. optype specifies the intended opcode for the list. If first is not already a list of the right type, it will be upgraded into one. If either first or last is null, the other is returned unchanged.

Concatenate the lists of ops contained directly within two list-type ops, returning the combined list. first and last are the list-type ops to concatenate. optype specifies the intended opcode for the list. If either first or last is not already a list of the right type, it will be upgraded into one. If either first or last is null, the other is returned unchanged.

Prepend an item to the list of ops contained directly within a list-type op, returning the lengthened list. first is the op to prepend to the list, and last is the list-type op. optype specifies the intended opcode for the list. If last is not already a list of the right type, it will be upgraded into one. If either first or last is null, the other is returned unchanged.

Optree construction

Constructs, checks, and returns a new stub op, which represents an empty list expression.

Constructs, checks, and returns an op of any list type. type is the opcode. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically if required. first and last supply up to two ops to be direct children of the list op; they are consumed by this function and become part of the constructed op tree.

Constructs, checks, and returns an op of any base type (any type that has no extra fields). type is the opcode. flags gives the eight bits of op_flags, and, shifted up eight bits, the eight bits of op_private.

Constructs, checks, and returns an op of any unary type. type is the opcode. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically if required, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 is automatically set. first supplies an optional op to be the direct child of the unary op; it is consumed by this function and become part of the constructed op tree.

Constructs, checks, and returns an op of any binary type. type is the opcode. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 or 2 is automatically set as required. first and last supply up to two ops to be the direct children of the binary op; they are consumed by this function and become part of the constructed op tree.

Constructs, checks, and returns an op of any pattern matching type. type is the opcode. flags gives the eight bits of op_flags and, shifted up eight bits, the eight bits of op_private.

Constructs, checks, and returns an op of any type that involves an embedded SV. type is the opcode. flags gives the eight bits of op_flags. sv gives the SV to embed in the op; this function takes ownership of one reference to it.

Constructs, checks, and returns an op of any type that involves a reference to a pad element. type is the opcode. flags gives the eight bits of op_flags. A pad slot is automatically allocated, and is populated with sv; this function takes ownership of one reference to it.

This function only exists if Perl has been compiled to use ithreads.

Constructs, checks, and returns an op of any type that involves an embedded reference to a GV. type is the opcode. flags gives the eight bits of op_flags. gv identifies the GV that the op should reference; calling this function does not transfer ownership of any reference to it.

Constructs, checks, and returns an op of any type that involves an embedded C-level pointer (PV). type is the opcode. flags gives the eight bits of op_flags. pv supplies the C-level pointer, which must have been allocated using "PerlMemShared_malloc"; the memory will be freed when the op is destroyed.

Embedding Functions

Loads the module whose name is pointed to by the string part of name. Note that the actual module name, not its filename, should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS (or 0 for no flags). ver, if specified and not NULL, provides version semantics similar to use Foo::Bar VERSION. The optional trailing SV* arguments can be used to specify arguments to the module's import() method, similar to use Foo::Bar VERSION LIST. They must be terminated with a final NULL pointer. Note that this list can only be omitted when the PERL_LOADMOD_NOIMPORT flag has been used. Otherwise at least a single NULL pointer to designate the default import list is required.

The reference count for each specified SV* parameter is decremented.

Optree construction

Constructs, checks, and returns an lslice (list slice) op. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 or 2 is automatically set as required. listval and subscript supply the parameters of the slice; they are consumed by this function and become part of the constructed op tree.

Constructs, checks, and returns an assignment op. left and right supply the parameters of the assignment; they are consumed by this function and become part of the constructed op tree.

If optype is OP_ANDASSIGN, OP_ORASSIGN, or OP_DORASSIGN, then a suitable conditional optree is constructed. If optype is the opcode of a binary operator, such as OP_BIT_OR, then an op is constructed that performs the binary operation and assigns the result to the left argument. Either way, if optype is non-zero then flags has no effect.

If optype is zero, then a plain scalar or list assignment is constructed. Which type of assignment it is is automatically determined. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 or 2 is automatically set as required.

Constructs a state op (COP). The state op is normally a nextstate op, but will be a dbstate op if debugging is enabled for currently-compiled code. The state op is populated from "PL_curcop" (or "PL_compiling"). If label is non-null, it supplies the name of a label to attach to the state op; this function takes ownership of the memory pointed at by label, and will free it. flags gives the eight bits of op_flags for the state op.

If o is null, the state op is returned. Otherwise the state op is combined with o into a lineseq list op, which is returned. o is consumed by this function and becomes part of the returned op tree.

Constructs, checks, and returns a logical (flow control) op. type is the opcode. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 is automatically set. first supplies the expression controlling the flow, and other supplies the side (alternate) chain of ops; they are consumed by this function and become part of the constructed op tree.

Constructs, checks, and returns a conditional-expression (cond_expr) op. flags gives the eight bits of op_flags, except that OPf_KIDS will be set automatically, and, shifted up eight bits, the eight bits of op_private, except that the bit with value 1 is automatically set. first supplies the expression selecting between the two branches, and trueop and falseop supply the branches; they are consumed by this function and become part of the constructed op tree.

Constructs and returns a range op, with subordinate flip and flop ops. flags gives the eight bits of op_flags for the flip op and, shifted up eight bits, the eight bits of op_private for both the flip and range ops, except that the bit with value 1 is automatically set. left and right supply the expressions controlling the endpoints of the range; they are consumed by this function and become part of the constructed op tree.

Constructs, checks, and returns an op tree expressing a loop. This is only a loop in the control flow through the op tree; it does not have the heavyweight loop structure that allows exiting the loop by last and suchlike. flags gives the eight bits of op_flags for the top-level op, except that some bits will be set automatically as required. expr supplies the expression controlling loop iteration, and block supplies the body of the loop; they are consumed by this function and become part of the constructed op tree. debuggable is currently unused and should always be 1.

Constructs, checks, and returns an op tree expressing a while loop. This is a heavyweight loop, with structure that allows exiting the loop by last and suchlike.

loop is an optional preconstructed enterloop op to use in the loop; if it is null then a suitable op will be constructed automatically. expr supplies the loop's controlling expression. block supplies the main body of the loop, and cont optionally supplies a continue block that operates as a second half of the body. All of these optree inputs are consumed by this function and become part of the constructed op tree.

flags gives the eight bits of op_flags for the leaveloop op and, shifted up eight bits, the eight bits of op_private for the leaveloop op, except that (in both cases) some bits will be set automatically. debuggable is currently unused and should always be 1. has_my can be supplied as true to force the loop body to be enclosed in its own scope.

Constructs, checks, and returns an op tree expressing a foreach loop (iteration through a list of values). This is a heavyweight loop, with structure that allows exiting the loop by last and suchlike.

sv optionally supplies the variable that will be aliased to each item in turn; if null, it defaults to $_ (either lexical or global). expr supplies the list of values to iterate over. block supplies the main body of the loop, and cont optionally supplies a continue block that operates as a second half of the body. All of these optree inputs are consumed by this function and become part of the constructed op tree.

flags gives the eight bits of op_flags for the leaveloop op and, shifted up eight bits, the eight bits of op_private for the leaveloop op, except that (in both cases) some bits will be set automatically.

Constructs, checks, and returns a loop-exiting op (such as goto or last). type is the opcode. label supplies the parameter determining the target of the op; it is consumed by this function and becomes part of the constructed op tree.

Constructs, checks, and returns an op tree expressing a given block. cond supplies the expression that will be locally assigned to a lexical variable, and block supplies the body of the given construct; they are consumed by this function and become part of the constructed op tree. defsv_off is the pad offset of the scalar lexical variable that will be affected. If it is 0, the global $_ will be used.

Constructs, checks, and returns an op tree expressing a when block. cond supplies the test expression, and block supplies the block that will be executed if the test evaluates to true; they are consumed by this function and become part of the constructed op tree. cond will be interpreted DWIMically, often as a comparison against $_, and may be null to generate a default block.

Optree Manipulation Functions

If cv is a constant sub eligible for inlining. returns the constant value returned by the sub. Otherwise, returns NULL.

Constant subs can be created with newCONSTSUB or as described in "Constant Functions" in perlsub.

See "newCONSTSUB_flags".

Creates a constant sub equivalent to Perl sub FOO () { 123 } which is eligible for inlining at compile-time.

Currently, the only useful value for flags is SVf_UTF8.

The newly created subroutine takes ownership of a reference to the passed in SV.

Passing NULL for SV creates a constant sub equivalent to sub BAR () {}, which won't be called if used as a destructor, but will suppress the overhead of a call to AUTOLOAD. (This form, however, isn't eligible for inlining at compile time.)

Used by xsubpp to hook up XSUBs as Perl subs. filename needs to be static storage, as it is used directly as CvFILE(), without a copy being made.

Examines an op, which is expected to identify a subroutine at runtime, and attempts to determine at compile time which subroutine it identifies. This is normally used during Perl compilation to determine whether a prototype can be applied to a function call. cvop is the op being considered, normally an rv2cv op. A pointer to the identified subroutine is returned, if it could be determined statically, and a null pointer is returned if it was not possible to determine statically.

Currently, the subroutine can be identified statically if the RV that the rv2cv is to operate on is provided by a suitable gv or const op. A gv op is suitable if the GV's CV slot is populated. A const op is suitable if the constant value must be an RV pointing to a CV. Details of this process may change in future versions of Perl. If the rv2cv op has the OPpENTERSUB_AMPER flag set then no attempt is made to identify the subroutine statically: this flag is used to suppress compile-time magic on a subroutine call, forcing it to use default runtime behaviour.

If flags has the bit RV2CVOPCV_MARK_EARLY set, then the handling of a GV reference is modified. If a GV was examined and its CV slot was found to be empty, then the gv op has the OPpEARLY_CV flag set. If the op is not optimised away, and the CV slot is later populated with a subroutine having a prototype, that flag eventually triggers the warning "called too early to check prototype".

If flags has the bit RV2CVOPCV_RETURN_NAME_GV set, then instead of returning a pointer to the subroutine it returns a pointer to the GV giving the most appropriate name for the subroutine in this context. Normally this is just the CvGV of the subroutine, but for an anonymous (CvANON) subroutine that is referenced through a GV it will be the referencing GV. The resulting GV* is cast to CV* to be returned. A null pointer is returned as usual if there is no statically-determinable subroutine.

Performs the default fixup of the arguments part of an entersub op tree. This consists of applying list context to each of the argument ops. This is the standard treatment used on a call marked with &, or a method call, or a call through a subroutine reference, or any other call where the callee can't be identified at compile time, or a call where the callee has no prototype.

Performs the fixup of the arguments part of an entersub op tree based on a subroutine prototype. This makes various modifications to the argument ops, from applying context up to inserting refgen ops, and checking the number and syntactic types of arguments, as directed by the prototype. This is the standard treatment used on a subroutine call, not marked with &, where the callee can be identified at compile time and has a prototype.

protosv supplies the subroutine prototype to be applied to the call. It may be a normal defined scalar, of which the string value will be used. Alternatively, for convenience, it may be a subroutine object (a CV* that has been cast to SV*) which has a prototype. The prototype supplied, in whichever form, does not need to match the actual callee referenced by the op tree.

If the argument ops disagree with the prototype, for example by having an unacceptable number of arguments, a valid op tree is returned anyway. The error is reflected in the parser state, normally resulting in a single exception at the top level of parsing which covers all the compilation errors that occurred. In the error message, the callee is referred to by the name defined by the namegv parameter.

Performs the fixup of the arguments part of an entersub op tree either based on a subroutine prototype or using default list-context processing. This is the standard treatment used on a subroutine call, not marked with &, where the callee can be identified at compile time.

protosv supplies the subroutine prototype to be applied to the call, or indicates that there is no prototype. It may be a normal scalar, in which case if it is defined then the string value will be used as a prototype, and if it is undefined then there is no prototype. Alternatively, for convenience, it may be a subroutine object (a CV* that has been cast to SV*), of which the prototype will be used if it has one. The prototype (or lack thereof) supplied, in whichever form, does not need to match the actual callee referenced by the op tree.

If the argument ops disagree with the prototype, for example by having an unacceptable number of arguments, a valid op tree is returned anyway. The error is reflected in the parser state, normally resulting in a single exception at the top level of parsing which covers all the compilation errors that occurred. In the error message, the callee is referred to by the name defined by the namegv parameter.

Retrieves the function that will be used to fix up a call to cv. Specifically, the function is applied to an entersub op tree for a subroutine call, not marked with &, where the callee can be identified at compile time as cv.

The C-level function pointer is returned in *ckfun_p, and an SV argument for it is returned in *ckobj_p. The function is intended to be called in this manner:

    entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));

In this call, entersubop is a pointer to the entersub op, which may be replaced by the check function, and namegv is a GV supplying the name that should be used by the check function to refer to the callee of the entersub op if it needs to emit any diagnostics. It is permitted to apply the check function in non-standard situations, such as to a call to a different subroutine or to a method call.

By default, the function is Perl_ck_entersub_args_proto_or_list, and the SV parameter is cv itself. This implements standard prototype processing. It can be changed, for a particular subroutine, by "cv_set_call_checker".

Sets the function that will be used to fix up a call to cv. Specifically, the function is applied to an entersub op tree for a subroutine call, not marked with &, where the callee can be identified at compile time as cv.

The C-level function pointer is supplied in ckfun, and an SV argument for it is supplied in ckobj. The function is intended to be called in this manner:

    entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);

In this call, entersubop is a pointer to the entersub op, which may be replaced by the check function, and namegv is a GV supplying the name that should be used by the check function to refer to the callee of the entersub op if it needs to emit any diagnostics. It is permitted to apply the check function in non-standard situations, such as to a call to a different subroutine or to a method call.

The current setting for a particular CV can be retrieved by "cv_get_call_checker".

Custom Operators

Functions in file op.c

Hook manipulation

These functions provide convenient and thread-safe means of manipulating hook variables.

Puts a C function into the chain of check functions for a specified op type. This is the preferred way to manipulate the "PL_check" array. opcode specifies which type of op is to be affected. new_checker is a pointer to the C function that is to be added to that opcode's check chain, and old_checker_p points to the storage location where a pointer to the next function in the chain will be stored. The value of new_pointer is written into the "PL_check" array, while the value previously stored there is written to *old_checker_p.

"PL_check" is global to an entire process, and a module wishing to hook op checking may find itself invoked more than once per process, typically in different threads. To handle that situation, this function is idempotent. The location *old_checker_p must initially (once per process) contain a null pointer. A C variable of static duration (declared at file scope, typically also marked static to give it internal linkage) will be implicitly initialised appropriately, if it does not have an explicit initialiser. This function will only actually modify the check chain if it finds *old_checker_p to be null. This function is also thread safe on the small scale. It uses appropriate locking to avoid race conditions in accessing "PL_check".

When this function is called, the function referenced by new_checker must be ready to be called, except for *old_checker_p being unfilled. In a threading situation, new_checker may be called immediately, even before this function has returned. *old_checker_p will always be appropriately set before new_checker is called. If new_checker decides not to do anything special with an op that it is given (which is the usual case for most uses of op check hooking), it must chain the check function referenced by *old_checker_p.

If you want to influence compilation of calls to a specific subroutine, then use "cv_set_call_checker" rather than hooking checking of all entersub ops.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 2543:

Unknown directive: =notfor




Hosting generously
sponsored by Bytemark