core.ops - Parrot Core Ops
Parrot's core library of ops.
Core operations are primarily flow control and interpreter introspection.
These are the fundamental operations.
Please note: These opcodes must not be moved; they must have exactly these opcode numbers.
Opcodes ending with underscores are for internal use only; don't emit these opcodes.
- end()
- Halts the interpreter.
(Must be op #0,
CORE_OPS_end).
See also exit.
- noop()
- Does nothing other than waste an iota of time and 32 bits of bytecode space.
(Must be op #1,
CORE_OPS_noop)
- cpu_ret()
- Emit a cpu return instruction.
This is used to return from CGP core to JIT code.
Note: Do not use this opcode.
It is for internal use only.
(Must be op #2,
CORE_OPS_cpu_ret)
- check_events()
- Check the event queue and run event handlers if there are unhandled events.
Note: This opcode is mainly for testing.
It should not be necessary to ever use it explicitly.
(Must be op #3,
CORE_OPS_check_events).
- check_events__()
- Check the event queue and run event handlers if there are unhandled events.
Note: Do not use this opcode.
It is for internal use only.
(Must be op #4,
CORE_OPS_check_events__).
- wrapper__()
- Internal opcode to wrap unknown ops from loaded opcode libs.
Don't use.
(Must be op #5,
CORE_OPS_wrapper__).
- prederef__()
- Internal opcode to prederef opcodes on the fly.
Don't use.
(Must be op #6,
CORE_OPS_prederef__ ).
- reserved(inconst INT)
- Reserve 1 more fix entry.
- load_bytecode(in STR)
- Load Parrot bytecode from file $1,
and (TODO) search the library path,
to locate the file.
The control flow opcodes check conditions and manage program flow.
- branch(label INT)
- Branch forward or backward by the amount in $1.
- branch_cs(in STR)
- Intersegment branch to location in fixup table named $1.
- bsr(label INT)
- Branch to the location specified by $1.
Push the current location onto the call stack for later returning.
- ret()
- Pop the location off the top of the call stack and go there.
- jsr(label INT)
- Jump to the location specified by register $1.
Push the current location onto the call stack for later returning.
- jump(label INT)
- Jump to the address held in register $1.
- enternative()
- Internal opcode used to jump from normal bytecode into a JITted version.
These operations perform a conditional relative branch.
If the condition is met,
the branch happens.
Otherwise control falls to the next operation.
- if(invar INT,
labelconst INT)
- if(invar NUM,
labelconst INT)
- if(invar PMC,
labelconst INT)
- if(invar STR,
labelconst INT)
- Check register $1.
If true,
branch by $2.
- unless(invar INT,
labelconst INT)
- unless(invar NUM,
labelconst INT)
- unless(invar PMC,
labelconst INT)
- unless(invar STR,
labelconst INT)
- Check register $1.
If false,
branch by $2.
These operations are used to generate and call subroutines and continuations.
- invokecc(invar PMC)
- Call the subroutine in $1 and generate a new return continuation,
if needed.
For example,
a NCI subroutine which executes code in some C library will not create a continuation,
nor will anything but the first call to a coroutine.
- invoke(invar PMC,
invar PMC)
- Call the subroutine in $1 and use continuation $2.
- yield()
- Yield results from a coroutine.
- tailcall(invar PMC)
- Call the subroutine in $1 and use the current continuation as the subs continuation.
- returncc()
- Return from the sub or method via the current continuation.
- newclosure(out PMC,
invar PMC)
- Create a closure of the given subroutine PMC by cloning the sub's state.
Implementations of function argument and params handling
- set_args(inconst PMC /* ,
...
*/)
- Define arguments for the next function call.
- get_results(inconst PMC /* ,
...
*/)
- Define return values for the next function call.
- get_params(inconst PMC /* ,
...
*/)
- Define function parameters for this subroutine.
- set_returns(inconst PMC /* ,
...
*/)
- Define return results for the subroutine return statement.
- For all of these opcodes the passed invar PMC constant is the string representation of a FixedIntegerArray with one flag word per argument.
The flags are documented currently in include/parrot/enum.h only.
- After this argument a variable amount of arguments must follow according to the elements of the signature array.
- result_info(out PMC)
- Returns the get_results signature PMC of the caller.
This PMC is a FixedIntegerPMCArray.
The number of elements of this PMC is equal to the number of return values that are expected.
The individual bits per entry are specified in docs/pdds/pdd03_calling_conventions.pod.
########################################
- set_addr(out INT,
labelconst INT)
- Sets register $1 to the current address plus the offset $2.
- set_addr(invar PMC,
labelconst INT)
- Sets PMC in register $1 to the current address plus the offset $2.
- set_addr(invar PMC,
labelvar INT)
- Sets PMC in register $1 to the absolute address $2 obtained from get_addr.
- get_addr(out INT,
invar PMC)
- Sets $1 to the absolute address of the Sub PMC $2.
- push_eh(labelconst INT)
- Create an exception handler for the given catch label and push it onto the control stack.
- clear_eh()
- Clear out the most recently placed exception.
- throw(invar PMC)
- Throw the exception in $1.
- rethrow(invar PMC)
- Only valid inside an exception handler.
Rethrow the exception $1.
- die(in INT,
in INT)
- Die with severity $1 and error $2.
If severity is .EXCEPT_DOOMED,
call _exit($2).
The latter isn't catchable.
- exit(in INT)
- Exit the interpreter with exit_status $1.
If you want to communicate an extended exit status,
create an exception with severity EXCEPT_exit and throw it.
- pushmark(in INT)
- Push a mark labeled $1 onto the dynamic environment.
- popmark(in INT)
- Pop all items off the dynamic environment to the given mark.
- pushaction(invar PMC)
- Push the given Sub PMC $1 onto the dynamic environment.
If the dynamic environment is unwound due to a
popmark
,
subroutine return,
or an exception,
the subroutine will be invoked with an integer argument: 0
means a normal return; 1
means an exception has been raised.
These operations inspect or modify the interpreter itself,
possibly affecting its subsequent operation.
- debug(in INT)
- If $1 is zero,
turn off debugging.
Otherwise turn debug flag $1 on.
- bounds(in INT)
- If $1 is zero,
turn off byte code bounds checking.
Otherwise turn it on.
- profile(in INT)
- If $1 is zero,
turn off profiling.
Otherwise turn it on.
- trace(in INT)
- If $1 is zero,
turn off tracing.
Otherwise turn trace flag $1 on.
- gc_debug(in INT)
- If $1 is zero,
turn off GC_DEBUG.
Otherwise turn it on.
- interpinfo
- Fetch some piece of information about the interpreter and put it in $1.
Possible values for $2 are defined in runtime/parrot/include/interpinfo.pasm.
The valid constants for each return value are:
- interpinfo(out INT,
in INT)
- .TOTAL_MEM_ALLOC,
.DOD_RUNS,
.COLLECT_RUNS,
.ACTIVE_PMCS,
.ACTIVE_BUFFERS,
.TOTAL_PMCS,
.TOTAL_BUFFERS,
.HEADER_ALLOCS_SINCE_COLLECT,
.MEM_ALLOCS_SINCE_COLLECT,
.TOTAL_COPIED,
.IMPATIENT_PMCS,
.LAZY_DOD_RUNS,
.EXTENDED_PMCS
- interpinfo(out PMC,
in INT)
- .CURRENT_SUB,
.CURRENT_CONT,
.CURRENT_OBJECT,
.NAMESPACE_ROOT,
.CURRENT_LEXPAD
- interpinfo(out STR,
in INT)
- .CURRENT_METHOD
- warningson(in INT)
- Turns on warnings categories.
Categories already turned on will stay on.
Initial setting is currently all warnings off.
Include warnings.pasm to access the categories.
They are:
- .PARROT_WARNINGS_UNDEF_FLAG
- .PARROT_WARNINGS_IO_FLAG
- .PARROT_WARNINGS_PLATFORM_FLAG
- .PARROT_WARNINGS_ALL_FLAG
- To turn on multiple categories,
OR the category numbers together.
- warningsoff(in INT)
- Turns off warnings categories.
Categories already turned off will stay off.
See the documentation for warningson for category numbers.
- errorson(in INT)
- Turns on error categories.
Categories already turned on will stay on.
To access these from PASM,
include errors.pasm.
The current categories are:
- .PARROT_ERRORS_GLOBALS_FLAG
- Throw an exception if global doesn't exist.
Default: on.
- .PARROT_ERRORS_OVERFLOW_FLAG
- Throw math overflow instead of promoting to BigInt.
Default: off.
- .PARROT_ERRORS_PARAM_COUNT_FLAG
- Throw exception on argument <-> param count mismatch.
Default: off.
- .PARROT_ERRORS_RESULT_COUNT_FLAG
- Throw exception on return <-> result count mismatch.
Default: off.
- .PARROT_ERRORS_ALL_FLAG
- To turn on multiple categories,
OR the category numbers together.
- errorsoff(in INT)
- Turns off errors categories.
Categories already turned off will stay off.
See the documentation for errorson for category numbers.
- runinterp(invar PMC,
label INT)
- Run the code starting at offset $2 within interpreter $1.
- getinterp(out PMC)
- Get the current ParrotInterpreter.
Opcodes that interact with the DOD and GC subsystems.
- sweep(inconst INT)
- Triggers a DOD run,
based on the value of $1,
where:
- collect()
- Trigger a garbage collection.
- sweepoff()
- Disable DOD sweeps.
(Nestable)
- sweepon()
- Re-enable DOD sweeps.
- collectoff()
- Disable GC runs (nestable).
- collecton()
- Re-enable GC.
- needs_destroy(invar PMC)
- Mark the PMC wanting destruction as soon as possible,
for example when unused during the lazy sweep,
triggered by
sweep 0
.
###############################################################################
Opcodes for interfacing with C functions in shared libraries.
- loadlib(out PMC,
in STR)
- Load a dynamic link library named $2 and store it in $1.
- dlfunc(out PMC,
invar PMC,
in STR,
in STR)
- Look up symbol $3 in library $2 with signature $4,
and put the corresponding sub object in $1.
Note that you need the signature so we can build or find an appropriate thunking function.
- dlvar(out PMC,
invar PMC,
in STR)
- Look up symbol $3 in library $2.
We assume that this is actually a variable address rather than a function address,
and build an UnManagedStruct PMC and stick the address into its data pointer.
- compile(out PMC,
invar PMC,
in STR)
- Don't use compile -- just invoke the compiler.
- compreg(out PMC,
in STR)
- Get a compiler for source type $2.
- compreg(in STR,
invar PMC)
- Register the sub $2 as a compiler for source type $1.
$2 is either a NCI PMC with signature
pIt
or a PASM Sub.
- new_callback(out PMC,
invar PMC,
invar PMC,
in STR)
- Create a callback stub $1 for PASM subroutine $2 with userdata $3 and callback function signature $4.
Only 2 argument signatures with signature chars U[1iscpt] or [1iscpt]U are handled currently.
But these cover a lot of callback signatures.
Please note that the userdata PMC U has to be handled transparently by the caller of the callback function.
Copyright (C) 2001-2006,
The Perl Foundation.
This program is free software.
It is subject to the same license as the Parrot interpreter itself.