Introduction

This document is for core NQP opcodes.

For generating an abstract tree that includes opcodes, see docs/qast.markdown.

There is not a 1:1 mapping of MoarVM opcodes to the MoarVM-based NQP. Some opcodes are defined in NQP, some MoarVM opcodes are not exposed.

For Raku opcodes added by the rakudo compiler see docs/ops.markdown in the Rakudo repository. They are of the form nqp::p6* (following the historical naming of Perl 6).

NQP Opcodes

Opcodes (ops) are used both directly when writing NQP, and during code generation in QAST nodes.

When invoking them directly, you'll need to prefix them with nqp::, e.g.

nqp::mul_i(6,9);

The ops are listed below by type. Each entry shows the name of the op, its variants, and their arguments and types, and may provide a short description. Some opcodes differ only by argument types - in that case, they are listed under their common name (e.g. mul), with each of their variants (e.g. mul_i, mul_n) together with a single description.

Opcode variants may contain a type suffix, which usually indicates:

_i argument is a native int
_u argument is an unsigned int
_n argument is a native float
_s argument is a native string
_o argument is an object
_b argument is a code block
_I argument is a Big Integer

They may also have a numeric suffix, which typically indicates the number of arguments required. (Note that some opcodes contain an underscore not being used to indicate a type suffix.)

In opcode signatures below, we use the following types, which may not correspond directly to NQP types.

int - native int
num - native float
str - native string
Int - BigInt
Mu - any NQP or VM object
Mu:T - a type object, e.g. Int
Exception - an Exception object
Handle - an I/O Handle object
Iterable - something iterable
Context - a Context object
LexPad - a Context object
@ - this sigil indicates an array parameter
% - this sigil indicates a hash parameter
... - indicates variable args are accepted

VM-specific opcodes are denoted with a jvm, e.g. on the same line as the header. No annotation indicates this opcode should be supported on all nqp backends.

Some individual opcodes may be marked with Internal or Deprecated. Both of these indicate the opcodes are not intended to be used. Deprecated opcodes will eventually be removed from NQP. Internal opcodes are typically used at compile time to replace opcodes that take a variable number of arguments.

The opcodes are grouped into the following categories:

Arithmetic

abs | add | div | gcd | lcm | mod | mul | neg | sub

Array

Asynchronous

Atomic

Binary Data

Bit

Captures

Coercion

Conditional

if | ifnull | unless | with | without

Context Introspection

Loop/Control

Dispatch

delegate | dispatch | guard register | syscall track

Exception Handling

Processes

execname | exit | getpid | getppid

File / Directory / Network

Hash

HLL-Specific

Input/Output

Relational / Logic

NativeCall

Numeric

Objects

Parametric Extensions

parameterizetype | setparameterizer | typeparameterat | typeparameterized | typeparameters

Profiling

force_gc | mvmendprofile | mvmstartprofile

Serialization context

Stream Decoding

String

System Introspection

Threads

Timish

decodelocaltime | sleep | time

Trigonometric

Type / Conversion

Unicode Properties

Miscellaneous

Arithmetic

abs

abs_i(int $i --> int)
abs_n(num $n --> num)
abs_I(Int $i, Mu:T $type --> Int)

Return the absolute value of a number. _I variant returns an object of the given type.

add

add_i(int $l, int $r --> int)
add_n(num $l, num $r --> num)
add_I(Int $l, Int $r, Mu:T $type --> Int)
add_i64(Int $l, Int $r, Mu:T $type --> Int) js

Add two numbers together, returning the result. Typed variants return an object of the given type.

div

div_i(int $l, int $r --> int)
div_n(num $l, num $r --> num)
div_I(Int $l, Int $r, Mu:T $type --> Int)
div_In(Int $l, Int $r --> num)

Divide $l by $r, returning the result. _I variant returns an object of the given type. The _In variant returns a native num, using a scale of 309, and a rounding mode equivalent to Java's ROUND_HALF_UP.

gcd

gcd_i(int $l, int $r --> int)
gcd_I(Int $l, Int $r, Mu:T $type --> Int)

Return the greatest common multiple of two numbers. _I variant returns an object of the given type.

lcm

lcm_i(int $l, int $r --> int)
lcm_I(Int $l, Int $r, Mu:T $type --> Int)

Return the lowest common multiple of two numbers. _I variant returns an object of the given type.

mod

mod_i(int $l, int $r --> int)
mod_n(num $l, num $r --> num)
mod_I(Int $l, Int $r, Mu:T $type --> Int)

Return the modulus of $l by $r. _I variant returns an object of the given type.

mul

mul_i(int $l, int $r --> int)
mul_n(num $l, num $r --> num)
mul_I(Int $l, Int $r, Mu:T $type --> Int)

Multiply two numbers, returning the result. _I variant returns an object of the given type.

neg

neg_i(int $i --> int)
neg_n(num $n --> num)
neg_I(Int $i, Mu:T $type --> Int)

Return the negative of a number. _I variant returns an object of the given type.

sub

sub_i(int $l, int $r --> int)
sub_n(num $l, num $r --> num)
sub_I(Int $l, Int $r, Mu:T $type --> Int)
sub_i64(Int $l, Int $r, Mu:T $type --> Int) js

Subtract $r from $l, returning the result. Typed variants return an object of the given type.

Array

atpos

atpos(@arr, int $i --> Mu)
atpos_i(@arr, int $i --> int)
atpos_n(@arr, int $i --> num)
atpos_s(@arr, int $i --> str)

Return whatever is bound to @arr at position $i.

atpos2d

atpos2d(@arr, int $i, int $j --> Mu)
atpos2d_i(@arr, int $i, int $j --> int)
atpos2d_n(@arr, int $i, int $j --> num)
atpos2d_s(@arr, int $i, int $j --> str)

Return whatever is bound to the 2-dimensional array @arr at position $i, $j.

atpos3d

atpos3d(@arr, int $i, int $j, int $k --> Mu)
atpos3d_i(@arr, int $i, int $j, int $k --> int)
atpos3d_n(@arr, int $i, int $j, int $k --> num)
atpos3d_s(@arr, int $i, int $j, int $k --> str)

Return whatever is bound to the 3-dimensional array @arr at position $i, $j, $k.

atposnd

atposnd(@arr, @indices --> Mu)
atposnd_i(@arr, @indices --> int)
atposnd_n(@arr, @indices --> num)
atposnd_s(@arr, @indices --> str)

Return whatever is bound to the n-dimensional array @arr at @indices, where @indices is a 1-dimensional integer array of index values.

atposref

atposref(@arr, int $idx --> Mu) js
atposref_i(@arr, int $idx --> int)
atposref_n(@arr, int $idx --> num)
atposref_s(@arr, int $idx --> str)

Returns a container (of type IntPosRef, NumPosRef, or StrPosRef) that you can assign to or read from which will directly access @arr at index $idx.

bindpos

bindpos(@arr, int $i, Mu $v --> Mu)
bindpos_i(@arr, int $i, int $v --> int)
bindpos_n(@arr, int $i, num $v --> num)
bindpos_s(@arr, int $i, str $v --> str)

Bind $v to @arr at position $i and return $v.

bindpos2d

bindpos2d(@arr, int $i, int $j, Mu $v --> Mu)
bindpos2d_i(@arr, int $i, int $j, int $v --> int)
bindpos2d_n(@arr, int $i, int $j, num $v --> num)
bindpos2d_s(@arr, int $i, int $j, str $v --> str)

Bind $v to the 2-dimensional arrray @arr at position $i, $j and return $v.

bindpos3d

bindpos3d(@arr, int $i, int $j, int $k, Mu $v --> Mu)
bindpos3d_i(@arr, int $i, int $j, int $k, int $v --> int)
bindpos3d_n(@arr, int $i, int $j, int $k, num $v --> num)
bindpos3d_s(@arr, int $i, int $j, int $k, str $v --> str)

Bind $v to the 3-dimensional arrray @arr at position $i, $j, $k and return $v.

bindposnd

bindposnd(@arr, @indices, Mu $v --> Mu)
bindposnd_i(@arr, @indices, int $v --> int)
bindposnd_n(@arr, @indices, num $v --> num)
bindposnd_s(@arr, @indices, str $v --> str)

Bind $v to @arr at the position specified by @indices and return $v. @indices is a 1-dimensional integer array of index values.

elems

elems(@arr --> int)
elems(%hash --> int)

Return the number of elements in @arr, or the number of keys in %hash.

existspos

existspos(@arr, int $i --> int)

Return 1 if anything is bound to @arr at position $i, 0 otherwise.

list

list(... --> Mu)
list_i(... --> Mu)
list_n(... --> Mu)
list_s(... --> Mu)
list_b(... --> Mu) moar

Create a list of the given parameters. If no arguments are passed, an empty list is created. If a typed variant is used, the parameters are coerced to the appropriate type.

pop

pop(@arr --> Mu)
pop_i(@arr --> int)
pop_n(@arr --> num)
pop_s(@arr --> str)

"Pop the last value off the end of @arr." Return the value of @arr at its last bound position, and unbind @arr at that position.

push

push(@arr, Mu $v --> Mu)
push_i(Array int @arr, int $v --> int)
push_n(Array num @arr, num $v --> num)
push_s(Array str @arr, str $v --> str)
push_o($obj, str $v --> str) moar

"Push $v onto the end of @arr." Bind $v to @arr at the position at the end of @arr, i.e., the position that is just after the last position of @arr that has been bound to.

Return value is not currently defined.

setelems

setelems(@arr, int $i --> @arr)

Set the size of @arr to $i elements. If less than the current size, any elements after the new last position are unbound. If greater, the empty elements at the end are bound with potentially VM specific null entries.

shift

shift(@arr --> Mu)
shift_i(@arr --> int)
shift_n(@arr --> num)
shift_s(@arr --> str)
shift_o(@arr --> obj) moar

"Shift the first value from the beginning of @arr." Return the value of @arr at index 0, unbind @arr at index 0, and move all other bindings of @arr to the index one below what they were previously bound to.

slice

slice(@arr, int $start_pos, int $end_pos --> @copy)

Copy the elements in @arr starting at $start_pos and ending at $end_pos and return the resulting list. If $start_pos or $end_pos is -n it will translate into the nth position relative to the end of the list.

my @a := 'a', 'b', 'c';
print($_ ~ ', ') for nqp::slice(@a, 0, -2);

# OUTPUT: «a, b»

Will throw an exception if either $start_pos or $end_pos is out-of-bounds (after translation).

splice

splice(@arr, @from, int $offset, int $count --> @arr)

Remove the elements in @arr starting at $offset, for $count positions. Replace them with all the elements from @from.

unshift

unshift(@arr, Mu $v --> $v)
unshift_i(@arr, int $v --> $v)
unshift_n(@arr, num $v --> $v)
unshift_s(@arr, str $v --> $v)

"Shift $v into the beginning of @arr." Bind $v to @arr at index 0, move all other bindings of @arr to the index one above what they were previously bound to. Return the $v on JVM.

Asynchronous

asyncconnect

asyncconnect($queue, $schedulee, str $host, int $port, $handle_type)

Creates an asynchronous client socket and commences a connection operation. Upon connection, the queue will be passed an array consisting of the schedulee, a handle if the connection was successful (a type object if not) and an error string (some type object if no error). Returns an AsyncTask representing the connection attempt.

asynclisten

asynclisten($queue, $schedulee, str $host, int $port, $handle_type)

Creates an asynchronous server socket listening on the specified host and port. Each time a connection arrives, the queue will be passed an array consisting of the schedulee and the newly created asynchronous socket, for communicating with the connecting client. Returns an AsyncTask that can be cancelled to stop listening, or throws an exception if there is an error starting to listen.

asyncreadbytes `moar` `jvm`

asyncreadbytes($handle, $queue, $schedulee, $buf_type, $handle_type)

Starts reading bytes from the handle. When a packet is received, a $buf_type will be constructed and point to the received memory. An array will be pushed to the queue containing the schedulee, a sequence number that starts at 0, the buffer or just its type object on error, and an error string (type object if no error). If EOF is reached, a sequence number of -1 is sent. Cancel to stop reading.

asyncwritebytes

asyncwritebytes($handle, $queue, $schedulee, $to_write, $handle_type)

Writes a byte array to some handle capable of asynchronous operations. Once the write is complete, the queue will be passed an array consisting of the schedulee, an integer containing the number of bytes written or a type object if there was an error, and a string containing an error or some type object if none.

cancel `moar` `jvm`

cancel(AsyncTask $handle)

Takes something with the AsyncTask REPR and tries to cancel it, if it is possible to do so. If it is somehow not possible (for example, the operation already completed anyway), then nothing will happen. This is to avoid race conditions.

killprocasync

killprocasync($handle, $signal)

permit

permit(AsyncTask $handle, int $channel, int $permits)

Takes something with the AsyncTask REPR (the $handle parameter) and permits it to emit up to $permits more notifications. This is used as a back-pressure mechanism for asynchronous tasks that produce a stream of events, such as representing data arriving over a socket. Some kinds of tasks may emit on multiple channels, for example an asynchronous process may emit events for STDOUT (channel 1) and STDERR (channel 2) if both are of interest. The $channel argument is used to specify which channel is to get the permits if needed (use a separate permit stament for each channel of interest).

If $permits is less than zero (e.g., permit($task, $channel, -1), then it means there is no limit to the emits.

If $permits is set to any value greater than or equal to zero, then:

In the case unlimited emits were permitted previously, the permits will be set to the new value. If the new value is zero, then the reader will be stopped.
Otherwise the number of permits will be incremented by the specified value. If the resulting number of permits allowed is greater than zero and the reader is not running, it will be started.

signal `moar` `jvm`

signal($queue, $schedulee, int [nqp::cosnt::SIG_], $handle_type)

Sets up a signal handler for the given signal. Whenever it occurs, an array is pushed to the queue containing the schedulee and the signal number. Cancel to stop handling it.

spawnprocasync

spawnprocasync($queue, $prog, @args, $cwd, %env, $callbacks)

Replaced shell and spawn. See t/nqp/111-spawnprocasync.t for an example of use.

timer `moar` `jvm`

timer($queue, $schedulee, int $timeout, int $repeat, $handle_type)

Starts a timer. If timeout is zero, the $schedulee is immediately pushed to the queue. Otherwise, it is pushed after the timeout period. If repeat is non-zero, after the initial timeout period it will then be pushed again at the repeat interval. Returns an object of type $handle_type, which has a AsyncTask REPR. Cancellation stops the timer ever repeating again.

watchfile `moar` `jvm`

watchfile($queue, $schedulee, str $filename, $handle_type)

Watches an individual file for changes. Pushes an array to the queue when a change is detected, consisting of the schedulee, the filename that changed if provided by the underlying watcher mechanism, a 0 if the file changed, and a 1 if it was renamed. Cancel to stop watching.

Atomic

atomicadd_i `moar`

atomicadd_i(NativeIntRef $i, int $value --> int)

Takes an object with the NativeRef representation, which must point to an integer of the machine's atomic operation size. Performs an atomic addition of the provided value, which will be cast to the machine's atomic operation size before the operation is performed. Returns the value at the memory location before the addition was performed.

atomicbindattr `moar`

atomicbindattr(Mu $obj, Mu:T $type, str $attributename, Mu $new_value)

Atomically binds $new_value to the attribute of name $attributename of object $obj, where the attribute was declared in type $type. The notes in the getattr documentation also apply to atomicbindattr.

atomicdec_i `moar`

atomicdec_i(NativeIntRef $i --> int)

Takes an object with the NativeRef representation, which must point to an integer of the machine's atomic operation size. Performs an atomic decrement of the referenced integer. Returns the value before it was decremented.

atomicinc_i `moar`

atomicinc_i(NativeIntRef $i --> int)

Takes an object with the NativeRef representation, which must point to an integer of the machine's atomic operation size. Performs an atomic increment of the referenced integer. Returns the value before it was incremented.

atomicload `moar`

atomicload(ObjectContainer $c)

Takes an object which has a container spec set on it that knows how to do an atomic load (that is, with appropriate barriering to ensure the latest value is read). Performs the atomic load, and returns the loaded object.

atomicload_i `moar`

atomicload_i(NativeIntRef $i --> int)

Takes an object with the NativeRef representation, which must point to an integer of the machine's atomic operation size. Performs an atomic load (that is, with appropriate barriering to ensure the latest value is read).

atomicstore `moar`

atomicstore(ObjectContainer $c, Mu $value)

Takes an object which has a container spec set on it that knows how to do an atomic load. Performs the atomic store, which may fail if the value being stored does not, for example, meet type constraints. Evaluates to the stored value. The store performs appropriate barriering to ensure the changed value is "published".

atomicstore_i `moar`

atomicstore_i(NativeIntRef $i, int64 $value)

Takes an object with the NativeRef representation, which must point to an integer of the machine's atomic operation size. Performs an atomic store (that is, with appropriate barriering to ensure the changed value is "published").

barrierfull `moar`

barrierfull()

Performs a full memory barrier.

cas `moar`

cas(ObjectContainer $cont, Mu $expected, Mu $new --> Mu)

Takes an object which has a container spec set on it that knows how to do an atomic compare and swap, and performs an atomic compare and swap operation. The operation atomically compares the $expected object with what is currently held in the container. If they are the same object, then it replaces it with $new. If not, no change takes place. The original object stored in the container is returned, which can be used with eqaddr to check if it is the same as the $expected object. The container may perform type checks on the $new object before it attempts the operation.

cas_i `moar`

cas_i(NativeIntRef $i, int64 $expected, int64 $new --> int)

Takes an object with the NativeRef representation, which must point to an integer of the machine's atomic operation size. Casts the expected and new parameters to the machine's atomic operation size, and then uses them to perform an atomic compare and swap operation on the referenced integer. The operation atomically compares the $expected value with the value currently at the referenced location. If they are equal, it replaces the value with $new. If they are not equal, nothing happens. The operation evaluates to the value originally at the location (which can be compared with $expected to see if the operation was a success).

Binary Data

readint `moar` `js`

readint(buffer $source, int $offset, int $flags --> int)

Reads a signed integer at offset $offset from $source with size and endianness specified by $flags. Returns that value, widened to a 64-bit int.

readnum `moar` `js`

readnum(buffer $source, int $offset, int $flags --> num)

Reads a floating point number at offset $offset from $source with the size specified by $flags. Returns that value, widened to a 64-bit num.

readuint `moar` `js`

readuint(buffer $source, int $offset, int $flags --> uint)

Reads an unsigned integer at offset $offset from $source with size and endianness specified by $flags. Returns that value, widened to a 64-bit uint.

writeint `moar` `js`

writeint(buffer $target, int $offset, int $value, int $flags)

Writes the signed integer $value at $offset into the buffer $target, with the size and endianness specified by $flags.

writenum `moar` `js`

writenum(buffer $target, int $offset, num $value, int $flags)

Writes the floating point $value at $offset into the buffer $target. Only 32-bit and 64-bit sizes are supported.

writeuint `moar` `js`

writeuint(buffer $target, int $offset, uint $value, int $flags)

Writes the unsigned integer $value at $offset into the buffer $target, with the size and endianness specified by $flags.

Bit

bitand

bitand_i(int $l, int $r)
bitand_s(str $l, str $r --> str)
bitand_I(Int $l, Int $r, Mu:T $type --> Int)

AND the bits in $l and $r. _I variant returns an object of the given type.

bitneg

bitneg_i(int $bits --> int)
bitneg_I(Int $bits, Mu:T $type --> Int)

Negate the bits in $bits. _I variant returns an object of the given type.

bitor

bitor_i(int $l, int $r)
bitor_s(str $l, str $r --> str)
bitor_I(Int $l, Int $r, Mu:T $type --> Int)

OR the bits in $l and $r. _I variant returns an object of the given type.

bitshiftl

bitshiftl_i(int $bits, int $count --> int)
bitshiftl_I(Int $bits, int $count, Mu:T $type --> Int)

Signed left shift of $bits by $count. _I variant returns an object of the given type.

bitshiftr

bitshiftr_i(int $bits, int $count --> int)
bitshiftr_I(Int $bits, int $count, Mu:T $type --> Int)

Signed right shift of $bits by $count. _I variant returns an object of the given type.

bitxor

bitxor_i(int $l, int $r --> int)
bitxor_s(str $l, str $r --> str)
bitxor_I(Int $l, Int $r, Mu:T $type --> Int)

XOR the bits in $l and $r. _I variant returns an object of the given type.

Captures

captureexistsnamed($capture, "c")

captureexistsnamed($capture, str $name --> int)

Returns 1 if the capture (saved with savecapture) has a named argument with the given name. Returns 0 if not.

capturehasnameds

`capturehasnameds($capture --> int)

Returns 1 if the capture (saved with savecapture) has named arguments. Returns 0 if not.

capturenamedshash

`captureamedshash($capture --> hash)

Returns a hash of the named arguments in the given capture.

captureposelems

captureposelems($capture --> int)

Returns the number of positional elements in a capture that was saved with savecapture.

captureposarg

captureposarg($capture, int $index --> obj)
captureposarg_i($capture, int $index --> int)
captureposarg_n($capture, int $index --> num)
captureposarg_s($capture, int $index --> str)
captureposarg_u($capture, int $index --> uint)

Returns the positional argument at the given index from a capture that was saved with savecapture.

captureposprimspec

captureposprimspec($capture, int $index --> int)

Given a capture and an index, return the primitive type of the positional argument at that index.

The primitive types are 1 for int, 2 for num, 3 for str and 10 for uint. 0 is any object.

savecapture

savecapture()

Gets hold of the argument capture passed to the current block. Commits to doing enough copying that the list is valid any amount of time. See usecapture for a version of the op that doesn't promise that. Used by the multi-dispatcher.

usecapture

usecapture()

Gets hold of the argument capture passed to the current block. (a future usecapture may invalidate it) It's valid to implement this exactly the same way as savecapture if there's no performance benefit to be had in a split. Used by the multi-dispatcher.

Coercion

coerce_in `moar`

coerce_in(int --> num)

Coerce from int to num.

coerce_is

coerce_is(int --> str)

Coerce from int to str.

coerce_iu `moar`

coerce_iu(int --> uint)

Coerce from int to uint.

coerce_ni `moar`

coerce_ni(num --> int)

Coerce from num to int.

coerce_ns `moar` `jvm`

coerce_ns(num --> str)

Coerce from num to str.

coerce_si

coerce_si(str --> int)

Coerce from str to int.

coerce_sn `moar`

coerce_sn(str --> num)

Coerce from str to num.

coerce_ui `moar`

coerce_ui(uint --> int)

Coerce from uint to int.

coerce_us `moar` `jvm`

coerce_us(uint --> str)

Coerce from uint to str.

intify `moar`

intify($o --> int)

Coerce an object to int.

numify `moar`

numify($o --> num)

Coerce an object to num.

stringify

stringify($o --> str)

Coerce an object to str.

Conditional

if

if(Block $condition, Block $then)
if(Block $condition, Block $then, Block $else)

If the $condition evaluates to a non-zero value, run the $then block. If not, and an $else block is present, run that instead, if it's absent, return result of $condition.

ifnull

ifnull(Block $cond, Block $body)

If the $cond evaluates to null, evaluate the $body, otherwise return the result of $cond.

unless

unless(Block $condition, Block $then)
unless(Block $condition, Block $then, Block $else)

If the $condition evaluates to 0, run the $then block. If not, and an $else block is present, run that instead, if it's absent, return result of $condition.

with

with(Block $condition, Block $then)
with(Block $condition, Block $then, Block $else)

If the $condition evaluates to a defined value, run the $then block. If not, and an $else block is present, run that instead, if it's absent, return result of $condition.

without

without(Block $condition, Block $then)
without(Block $condition, Block $then, Block $else)

If the $condition evaluates to an undefined value, run the $then block. If not, and an $else block is present, run that instead, if it's absent, return result of $condition.

Context Introspection

bindlex `moar` `jvm`

bindlex(str $name, Mu $value)
bindlex_i(str $name, int $value)
bindlex_n(str $name, num $value)
bindlex_s(str $name, str $value)

Binds $value to the lexical specified by name and type. Searching in the outer frames, starting at the current. An error is thrown if it does not exist or if the type is incorrect.

bindlexdyn

bindlexdyn(str $name, Mu $value)

Binds $value to the contextual with the specified name, searching for it in the call-chain, starting at the calling frame.

ctx

ctx(--> Context)

Return the object representing the current context.

ctxcaller

ctxcaller(Context $ctx)

Given a context, return the caller context, or null.

ctxlexpad

ctxlexpad(Context $ctx)

Given a context, return its lexpad

ctxouter

ctxouter(Context $ctx)

Given a context, return the outer context, or null.

curlexpad

curlexpad()

Return the current lexpad.

getlex `moar` `jvm`

getlex(str $name)
getlex_i(str $name)
getlex_n(str $name)
getlex_s(str $name)

Looks up the lexical with the specified name and the specified type. Searching in the outer frames, starting at the current. An error is thrown if it does not exist or if the type is incorrect.

getlexcaller

getlexcaller(str $name)

Looks up the lexical with the specified name, starting at the calling frame. It checks all outer frames of the caller chain.

getlexdyn

getlexdyn(str $name)

Looks up the contextual with the specified name in the caller chain, starting at the calling frame.

getlexouter

getlexouter(str $name)

Looks up the lexical with the specified name and the specified type. Searching in the outer frames, starting at outer.

getlexref `moar` `jvm`

getlexref_i(str $name)
getlexref_n(str $name)
getlexref_s(str $name)

Looks up the native type lexical with the specified name and the specified type. Searching in the outer frames, starting at the current. An error is thrown if it does not exist or if the type is incorrect.

Lexicalref is a mechanism that allows us to treat a native value stored in a lexpad as if it were a read-writable container we can pass around. the lexicalref that gets created holds a reference to the frame in question and any access to it acts like getlex from the frame it originated in

getlexrel

getlexrel(Mu $context, str $name)

Looks up the lexical with the specified name and the specified type. Searching in the outer frames, starting at the given $context.

getlexrelcaller

getlexrelcaller(Mu $context, str $name)

Looks up the lexical with the specified name, starting at the given $context. It checks all outer frames of the caller chain.

getlexreldyn

getlexreldyn(Mu $context, str $name)

Looks up the contextual with the specified name in the caller chain, starting at the given $context.

lexprimspec

lexprimspec(LexPad $pad, str $name --> int)

Given a lexpad and a name, return the name's primitive type.

The primitive types are 1 for int, 2 for num, 3 for str and 10 for uint. 0 is any object.

Loop/Control

control

QAST::Op.new(:op<control>, :name<next>);
QAST::Op.new(:op<control>, :name<last>);
QAST::Op.new(:op<control>, :name<redo>);

Not callable directly from NQP, but used in languages via QAST to perform loop control. The specific kind of loop control desired is specified via the :name attribute; either next, last, or redo.

defor

defor(Block $cond, Block $body)

If the $cond evaluates to defined value, return it, otherwise, evaluate the $body.

for

for(Iterable $iter, Block $body)

Invoke the $body for every item available in $iter.

repeat_until

repeat_until(Block $condition, Block $body)
repeat_until(Block $condition, Block $body, Block $post)

First run the $body. Then, enter a loop, running the $body only if the condition returns 0.

If a $post block is present, run that at the end, regardless of $condition.

repeat_while

repeat_while(Block $condition, Block $body)
repeat_while(Block $condition, Block $body, Block $post)

First run the $body. Then, enter a loop, running the $body only if the condition returns a non-0 value.

If a $post block is present, run that at the end, regardless of $condition.

stmts

stmts(...)

Executes the given statements sequentially. For example:

nqp::stmts((my $a := nqp::chars("foo")), say($a), say("bar"));
# 3
# bar

Note that := statements must be surrounded by parentheses.

until

until(Block $condition, Block $body)
until(Block $condition, Block $body, Block $post)

Enter a loop, running the $body only if the condition returns 0.

If a $post block is present, run that at the end, regardless of $condition.

while

while(Block $condition, Block $body)
while(Block $condition, Block $body, Block $post)

Enter a loop, running the $body only if the condition returns a non-0 value.

If a $post block is present, run that at the end, regardless of $condition.

Dispatch `moar`

delegate `moar`

nqp::delegate(…) is short for nqp::dispatch('boot-syscall', 'dispatcher-delegate', …)

dispatch `moar`

perform dispatch function as determined by its arguments.

See Jonathan Worthington's blog posts about the subject for now, while the specific arguments and their meaning are being properly documented.

Towards a new general dispatch mechanism in MoarVM
Raku multiple dispatch with the new MoarVM dispatcher
The new MoarVM dispatch mechanism is here!

guard `moar`

nqp::guard('foo', …) is short for nqp::dispatch('boot-syscall', 'dispatcher-guard-foo', …)

register `moar`

nqp::register(…) is short for nqp::dispatch('boot-syscall', 'dispatcher-register', …)

syscall `moar`

nqp::syscall(…) is short for nqp::dispatch('boot-syscall', …)

track `moar`

nqp::track('foo', …) is short for nqp::dispatch('boot-syscall', 'dispatcher-track-foo', …)

Exception Handling

backtrace

backtrace(Exception $ex)

Return an array of hashes, describing the backtrace of the given exception.

backtracestrings

backtracestrings(Exception $ex)

Return an array of strings, describing the backtrace of the given exception.

die

die(str $message)
die_s(str $message)

Create and throw an exception using the given message.

exception

exception()

Return the current exception object.

getextype

getextype(Exception $ex)

Gets the exception category (nqp::const::CONTROL_*)

getmessage

getmessage(Exception $ex)

Gets the exception message.

getpayload

getpayload(Exception $ex)

Gets the exception payload.

newexception

newexception()

Return a new exception object.

resume

resume(Exception $ex)

Resume the exception, if possible.

rethrow

rethrow(Exception $ex)

Re-throw the exception.

setextype

setextype(Exception $ex, int $type)

Sets the exception category (nqp::const::CONTROL_*)

setmessage

setmessage(Exception $ex, str $message)

Sets the exception message.

setpayload

setpayload(Exception $ex, Mu $obj)

Sets the exception payload.

throw

throw(Exception $ex)

Throw the exception.

Processes

execname

execname(--> str)

It's used to implement $*EXECUTABLE in Raku, and is the name of the current "executable". So if you run ./raku-m .... then it'll be the ./raku-m. It's actually set at present by passing a --execname= argument to MoarVM, since raku is actually a shell script. But when we do get to providing a fake executable for raku instead, then it'd just initialize it to argv[0].

exit

exit(int $status)

Exit nqp, using the given status as the compiler's exit value.

getpid

getpid(--> int)

Return the current process id, an int.

getppid `moar`

getppid(--> int)

Return the process id of the parent process, an int.

File / Directory / Network

chdir

chdir(str $path --> str)

Change the working directory to the given path.

chmod

chmod(str $path, int $mode --> int)

Change the permissions of $path to the posix style permissions of $mode. Returns 0 on success, throws an exception on failure.

chown

chown(str $path, uint $uid, uint $gid --> int)

Change the owner or group of the path. Throws an exception on failure.

closedir

closedir(Handle $)

Close the given directory handle.

copy

copy(str $from, str $to --> int)

Copy file $from to file $to. Return 0 on success, throw an exception on failure.

cwd

cwd(--> str)

Return a string containing the current working directory.

fileexecutable

fileexecutable(str $str --> int)

If the specified filename refers to an executable file, returns 1. If not, returns 0. If an error occurs, return -1.

fileislink

fileislink(str $str --> int)

If the specified filename refers to a symbolic link, returns 1. If not, returns 0. If an error occurs, return -1.

filereadable

filereadable(str $str --> int)

If the specified filename refers to a readable file, returns 1. If not, returns 0. If an error occurs, return -1.

filewritable

filewritable(str $str --> int)

If the specified filename refers to a writeable file, returns 1. If not, returns 0. If an error occurs, return -1.

gethostname

gethostname(str $str --> str)

Returns the hostname of the system where it is run.

getport `moar` `jvm`

getport($obj --> int)

If the specified object is an IO::Handle, return the integer port number the object is listening on. If an error occurs, return -1.

link

link(str $before, str $after --> int)

Create a link from $after to $before

lstat

lstat(str $path, int $code --> int)

Same as stat, but internally uses the OS's lstat() function, which does not follow symlinks.

lstat_time

lstat_time(str $path, int $code --> num)

Same as stat_time, but internally uses the OS's lstat() function, which does not follow symlinks.

mkdir

mkdir(str $name, int $mode --> int)

Create a directory of the given name. Use posix-style mode on non-windows platforms. Returns 0, or throws an exception.

nextfiledir

nextfiledir(handle $iterator)

Given the result of an opendir, return the next path from that directory. When no more items are available, return a null string. (check with null_s)

opendir

opendir(str $path --> Mu)

Return a directory handle on the given directory path. Throw an exception if $path is not a directory.

readlink

readlink(str $path -> str)

Given a path that is a link, return the target path. Throw an exception if the argument does not resolve to a link.

rename

rename(str $from, str $to --> int)

Rename file $from to file $to. Return 0 on success, throw an exception on failure.

rmdir

rmdir(str $path --> int)

Delete the given directory $path. Returns 0 on success, -2 if the directory didn't exist. May throw an exception.

stat

stat(str $path, int $code --> int)

Given a path and a code, return an int describing that path using the OS's stat() function. Any of these variants may throw an exception if the platform does not support them. (JVM does not support STAT_PLATFORM_BLOCKSIZE or STAT_PLATFORM_BLOCKS).

* `nqp::const::STAT_EXISTS`

Returns 1 if the path exists, 0 otherwise.

* `nqp::const::STAT_FILESIZE`

Returns the size of the file in bytes.

* `nqp::const::STAT_ISDIR`

Returns 1 if the path is a directory, 0 otherwise, -1 if an exception occurred processing the request.

* `nqp::const::STAT_ISREG`

Returns 1 if the path is a regular file, 0 otherwise, -1 if an exception occurred processing the request.

* `nqp::const::STAT_ISDEV`

Returns 1 if the path is a special file, 0 otherwise, -1 if an exception occurred processing the request.

* `nqp::const::STAT_ISLNK`

Returns 1 if the path is a symbol link, 0 otherwise, -1 if an exception occurred processing the request.

* `nqp::const::STAT_CREATETIME`
* `nqp::const::STAT_ACCESSTIME`
* `nqp::const::STAT_MODIFYTIME`
* `nqp::const::STAT_CHANGETIME`

Returns respective time attribute in seconds since epoch, or -1 if an exception occurred.

* `nqp::const::STAT_BACKUPTIME`

Returns -1.

* `nqp::const::STAT_GID`
* `nqp::const::STAT_UID`

Returns the user id and group id of the path, respectively. Returns -1 if an exception occurred.

* `nqp::const::STAT_PLATFORM_DEV`

Returns the device number of filesystem associated with the path. Returns -1 if an exception occurred.

* `nqp::const::STAT_PLATFORM_INODE`

Returns the inode. Returns -1 if an exception occurred.

* `nqp::const::STAT_PLATFORM_MODE`

Returns unix style mode. Returns -1 if an exception occurred.

* `nqp::const::STAT_PLATFORM_NLINKS`

Returns number of hard links to the path. Returns -1 if an exception occurred.

* `nqp::const::STAT_PLATFORM_DEV`

Returns the device identifier. Returns -1 if an exception occurred.

* `nqp::const::STAT_PLATFORM_BLOCKSIZE`

Returns preferred I/O size in bytes for interacting with the file.

* `nqp::const::STAT_PLATFORM_BLOCKS`

Returns number of system-specific blocks allocated on disk.

stat_time

stat_time(str $path, int $code --> num)

Given a path and one of the STAT_*TIME codes, return that time attribute as a num, using the OS's stat() function.

symlink

symlink(str $before, str $after)

Create a symbolic link from $after to $before

unlink

unlink(str $path --> int)

Delete the given file $path. Returns 0 on success, -2 if the file didn't exist. May throw an exception.

Hash

atkey

atkey(%hash, str $key --> Mu)
atkey_i(%hash, str $key --> int)
atkey_n(%hash, str $key --> num)
atkey_s(%hash, str $key --> str)
atkey_u(%hash, str $key --> uint) moar

Return the value of %hash at key $key.

Note, there's no bindkey_u yet since at the moment atkey_u is only used for getting values from the lexpad

bindkey

bindkey(%hash, str $key, Mu $v --> $v)
bindkey_i(%hash, str $key, int $v --> $v)
bindkey_n(%hash, str $key, num $v --> $v)
bindkey_s(%hash, str $key, str $v --> $v)
bindkey_o(%hash, str $key, obj $v --> $v) moar

Bind key $key of %hash to $v and return $v.

deletekey

deletekey(%hash, str $key --> %hash)

Delete the given key from %hash.

existskey

existskey(%hash, str $key --> int)

Return 1 if %hash has key $key bound to something, otherwise 0.

hash

hash(... --> Mu)

Return a hash. The first argument is a key, the second its value, and so on. Be sure to pass an even number of arguments, a VM specific error may occur otherwise.

iterator

iterator(hash)

Returns an iterator object to iterate over a hash's items. For example:

my $iter := nqp::iterator(%hash);
while $iter {
    my $pair := nqp::shift($iter);
    say(nqp::iterkey_s($pair), ' => ', nqp::iterval($pair));
}

You can also use nqp::iterator() to iterate over a list, which is functionally equivalent to cloning the list and not having to know which form of shift to have to use.

my $list := nqp::list('a', 'b', 'c');
my $iter := nqp::iterator($list);

while $iter {
    say(nqp::shift($iter));
}

Using iterator this way proved to be not very well optimizable, so this form will probably be deprecated in the future. Depending on circumstances one could use clone instead, or use an index variable:

my $list := nqp::list('a', 'b', 'c');
my int $i = -1;

while ++$i < nqp::elems($list) {
    say(nqp::atpos($list,$i));
}

iterkey

iterkey_s($pair --> str)

Returns the key associated with the given key-value pair. For example:

for %hash {
    say(nqp::iterkey_s($_), ' => ', nqp::iterval($_));
}

Or alternately:

my $iter := nqp::iterator(%hash);
while $iter {
    my $pair := nqp::shift($iter);
    say(nqp::iterkey_s($pair), ' => ', nqp::iterval($pair));
}

iterval

iterval($pair --> Mu)

Returns the value associated with the given key-value pair.

HLL-Specific

See MoarVM testfile for MoarVM specific examples

bindcurhllsym

bindcurhllsym(str $symname, $value)

Store a value in the current HLL's symbol hash at a given key.

bindhllsym

bindhllsym(str $hllname, str $symname, $value)

Store a value in a specified HLL's symbol hash at a given key.

getcurhllsym

getcurhllsym(str $symname --> Mu)

Retrieve a value from the current HLL's symbol hash at a given key.

gethllsym

gethllsym(str $hllname, str $symname --> Mu)

Retrieve a value from a specified HLL's symbol hash at a given key.

hllbool

hllbool(int -> obj)

If passed 0, return a HLL specific Boolean false value, otherwise, a true one. For Raku, this maps to Bool::False and Bool::True, respectively.

hllboxtype

hllboxtype_i(Mu)
hllboxtype_n(Mu)
hllboxtype_s(Mu)

Ignores any args passed and returns the HLL specific type objects for each basic type. For Raku, this maps to Int, Num, and Str.

hllhash `moar` `jvm`

hllhash(Mu)

Returns HLL specific type object for a hash. Ignores optional argument.

hlllist `moar` `jvm`

hlllist(Mu)

Returns HLL specific type object for a list. Ignores optional argument.

sethllconfig `moar`

sethllconfig(string, Hash)

usecompileehll

usecompileehllconfig

Decreases the "compilee depth" value.

usecompilerhll

usecompilerhllconfig

Increases the "compilee depth" value. When the compilee depth is greater than one, every hll access will hit the "compilee's HLL config", otherwise every access will hit the "compiler's HLL config".

This serves, for example, to seperate a running NQP compiler from an NQP compiler it's compiling, when compile-time evaluation happens.

Input/Output

closefh

closefh(Handle $fh)

Close the filehandle.

eoffh

eoffh(Handle $fh --> int)

Return 1 if this filehandle is at the end of the file, otherwise 0.

filenofh

filenofh(Handle $fh --> int) Returns the filehandle number. Not usable on the JVM (always returns -1).

flushfh

flushfh(Handle $fh)

Flushes the filehandle, forcing it to write any buffered output.

getstderr

getstderr()

Return the filehandle for standard error.

getstdin

getstdin()

Return the filehandle for standard input.

getstdout

getstdout()

Return the filehandle for standard output.

open

open(str $filename, str $mode)

Open the specified file in the given mode. Valid modes include r for read, w for write, and wa for write with append. Returns a filehandle.

print

print(str $str)

Output the given string to stdout.

readfh

readfh(Handle $fh, @arr, long $count)

Given a readable $fh, and an array of Buf[int8] or a Buf[uint8], read in the next $count bytes from the filehandle and store them in the array.

say

say(str $str)

Output the given string to stdout, followed by a newline.

seekfh

seekfh(Handle $fh, int $offset, int $whence)

Seek in the filehandle to the location specified by the offset and whence.

* `0` - from beginning of file
* `1` - from current position
* `2` - from end of file

tellfh

tellfh(Handle $fh --> int)

Return current access position for an open filehandle.

writefh

writefh(Handle $fh, Mu $str --> int)

Output the given object to the filehandle. Returns the number of bytes written.

Relational / Logic

cmp

cmp_i(int $l, int $r --> int)
cmp_n(num $l, num $r --> int)
cmp_s(str $l, str $r --> int)
cmp_I(Int $l, Int $r --> int)
cmp_u(uint $l, uint $r --> int)

Compare two values, returns -1 if $l is greater than $r, 0 if they are equal, and 1 if $r is greater than $l.

eqat

eqat(str $haystack, str $needle, int $pos --> int)

Return 1 if the string $haystack has the string $needle at position $pos, otherwise return 0.

eqatic

eqatic(str haystack, str $needle, int $pos --> int) Case-insensitive eqat

eqaticim `moar` `js`

eqaticim(str haystack, str $needle, int $pos --> int) Case-insensitive and ignore-mark eqat

eqatim `moar` `js`

eqatim(str haystack, str $needle, int $pos --> int) Ignore-mark eqat, NFD decomposes and matches the base codepoint

Example: eqat("á", "a", 0) → 1

falsey

falsey($a --> int)

Return 0 if the parameter has a truthy value, 1 otherwise.

iseq

iseq_i(int $l, int $r --> int)
iseq_n(num $l, num $r --> int)
iseq_s(str $l, str $r --> int)
iseq_I(Int $l, Int $r --> int)
iseq_u(uint $l, uint $r --> int) moar jvm
iseq_snfg(str $l, str $r --> int) js

Return 1 if the two parameters are equal, 0 otherwise.

iseq_snfg is a JS specific opcode that first normalizes string arguments to NFC.

isge

isge_i(int $l, int $r --> int)
isge_n(num $l, num $r --> int)
isge_s(str $l, str $r --> int)
isge_I(Int $l, Int $r --> int)
isge_u(uint $l, uint $r --> int) moar jvm

Return 1 if $l is greater than or equal to $r, otherwise 0.

isgt

isgt_i(int $l, int $r --> int)
isgt_n(num $l, num $r --> int)
isgt_s(str $l, str $r --> int)
isgt_I(Int $l, Int $r --> int)
isgt_u(uint $l, uint $r --> int) moar jvm

Return 1 if the two parameters are equal if $l is greater than $r, otherwise 0.

isle

isle_i(int $l, int $r --> int)
isle_n(num $l, num $r --> int)
isle_s(str $l, str $r --> int)
isle_I(Int $l, Int $r --> int)
isle_u(uint $l, uint $r --> int) moar jvm

Return 1 if $l is less than or equal to $r, otherwise 0.

islt

islt_i(int $l, int $r --> int)
islt_n(num $l, num $r --> int)
islt_s(str $l, str $r --> int)
islt_I(Int $l, Int $r --> int)
islt_u(uint $l, uint $r --> int) moar jvm

Return 1 if $l is less than $r, otherwise 0.

isne

isne_i(int $l, int $r --> int)
isne_n(num $l, num $r --> int)
isne_s(str $l, str $r --> int)
isne_I(Int $l, Int $r --> int)
isne_u(uint $l, uint $r --> int) moar jvm
isne_snfg(str $l, str $r --> int) js

Return 1 if the two parameters are not equal, otherwise 0.

isne_snfg is a JS specific opcode that first normalizes string arguments to NFC.

not

not_i(int $val --> int)

Return 1 if $val is 0, 0 otherwise.

NativeCall

buildnativecall

buildnativecall(obj &routine, str $lib, $symbol, str $conv, obj $arg_info, obj $ret_info -> int jit)

This opcode connects an nqp routine to a native function. The routine must have an attribute with NativeCall REPR as a box target.

Arguments are the routine itself, the name of the native library, the name of the symbol representing the native function, the calling convention, argument information and a hash with type information for the return type. It returns 1 if the call can be JITed and 0 otherwise. The call convention will usually be an empty string. arg_info is an array containing a hash for each parameter. The hashes contain the typeobj, rw, type (type code) and optionally a free_str flag for Str parameters and a similar structure in callback_args for callback parameters for Callable parameters The ret_info hash has similar keys with typeobj, type and free_str.

ret-info also has some additional fields not strictly related to return type: entry_point, resolve_lib_name and resolve_lib_name_arg.

resolve_lib_name is optional and contains a code object. This gets called with resolve_lib_name_arg to resolve this name to the actual name or path of the library to be loaded. This is used for relocatability of repositories and native libraries they contain (it keeps the absolute paths out of precomp files)

nativecall

nativecall(obj $return-type, obj $routine, @args -> obj)

Invoke native code. It takes a return type, the HLL sub itself and an array containing the arguments and returns the result.

nativecallcast

nativecallcast(obj $type, obj $cthing -> obj)

Given a C-based object, cast it to the given type, and return the new object.

nativecallglobal

nativecallglobal(str $lib, str $symbol, obj $type -> obj)

Given a C-library filename, a symbol name, and an object type, return an object that wraps the C variable.

nativecallinvoke

nativecallinvoke(obj $return-type, obj $routine, @args -> obj) moar

Low level version of nativecall(). Decontainerized values are required in the arguments array.

nativecallrefresh

nativecallrefresh(obj $cthing)

Refresh the C-based data backing the Raku object. This op should only be used if changes have been made to the C-data, and these changes are not being reflected in the Raku object.

nativecallsizeof

nativecallsizeof(obj $cthing -> int)

Return the size in bytes of the given C-based object. Works for both simple values like different sized integers, but also structs.

Numeric

base

base_I(Int $i, int $radix --> str)

Returns a string representing the integer $i in base $radix

ceil

ceil_n(num $n --> num)

Return the ceiling of a number.

exp

exp_n(num $exponent --> num)

Return the value of e raised to $exponent.

expmod

expmod_I(Int $base, Int $exponent, Int $modulus, Mu:T $type --> Int)

Return a bigint that is $base raised to $exponent modulus $modulus. _I variant returns an object of the given type.

floor

floor_n(num $n --> num)

Return the floor of a number.

inf

inf(--> num)

Return infinity.

log_n

log_n(num $n --> num)

Return the natural logarithm (base 𝑒) of a number.

nan

nan(--> num)

Return NaN.

neginf

neginf(--> num)

Return negative infinity.

pow

pow_i(int $base, int $exponent --> int)
pow_n(num $base, num $exponent --> num)
pow_I(Int $base, Int $exponent, Mu:T $type_num, Mu:T $type_bigint --> Int)

Return the value of $base raised to $exponent; _I variant returns an object of $type_num for negative exponents, and of type $type_bigint for positive exponents.

rand

rand_n(num $n --> num)
rand_i(int $i, Mu:T $type --> int) moar
rand_I(Int $i, Mu:T $type --> Int)

Returns a psuedo-random bigint up to the value of the given number. _I variant returns an object of the given type.

sqrt

sqrt_n(num $n--> num)

Return the square root of the given num.

srand

srand(int $n)

Sets and returns seed number for nqp::rand_* variants. Decimal numbers will be silently truncated, nqp::srand(1) and nqp::srand(1.1) are the same so always pass nqp::srand an integer.

Objects

attrinited

attrinited(Mu $obj. Mu:T $type, str $attributename --> int)

Test if the attribute of name $attributename of object $obj has been bound, see bindattr. Note that any access to the atribute that results in a getattr call causes it to be inited.

bind

bind(Mu $variable, Mu $value)

Binds $value to the $variable. Dies if $variable isn't actually a variable. Same as the := operator in NQP.

bindattr

bindattr(Mu $obj, Mu:T $type, str $attributename, Mu $new_value)
bindattr_i(Mu $obj, Mu:T $type, str $attributename, int $new_value)
bindattr_n(Mu $obj, Mu:T $type, str $attributename, num $new_value)
bindattr_s(Mu $obj, Mu:T $type, str $attributename, str $new_value)

Binds $new_value to the attribute of name $attributename of object $obj, where the attribute was declared in type $type. The notes in the getattr documentation also apply to bindattr.

bindcomp

bindcomp(str $base-class, Mu $compiler --> Mu)

Registers $compiler as the compiler for the language named $base-class, as in:

my $lang = My::Lang::Compiler.new();
nqp::bindcomp('My::Lang', $lang);

In general, though, $lang will inherit from HLL::Compiler, and the above will be achieved via:

$lang.language('My::Lang');

call

call()

This method is not documented yet.

Example:

nqp::call(nqp::getlexcaller('&say'), 'foo')

callmethod

callmethod(Mu $obj, str $methodname, *@pos, *%named --> Mu)

Uses findmethod to locate method $methodname on object $obj, and call to invoke the method with positional arguments *@pos and named arguments *%named.

Example:

class A { method x($a, $b, :$c) { say("$a $b $c") } }

nqp::callmethod(A, 'x', '4', '2', c => 'foo');
# same as: A.x(4, 2, c => 'foo')

can

can(Mu $obj, str $method --> int)

If the object has a method of the given name, return 1. Otherwise, return 0.

Returns 1 if $obj object has FALLBACK method.

clone

clone(Mu $obj --> Mu)
clone_nd(Mu $obj --> Mu)

Return a clone of the passed in object.

The _nd variant does not decontainerize the object.

create

create(Mu:T $type --> Mu)

Returns a newly allocated instance of type $type.

eqaddr

eqaddr(Mu $l, Mu $r --> int)

Returns 1 if the objects are the same object in the underlying VM, 0 otherwise.

findmethod

findmethod(Mu $obj, str $method --> Mu)

If the object has a method of the given name, return it. Otherwise, throw an exception.

getattr

getattr(Mu $obj, Mu:T $type, str $attributename --> Mu)
getattr_i(Mu $obj, Mu:T $type, str $attributename --> int)
getattr_n(Mu $obj, Mu:T $type, str $attributename --> num)
getattr_s(Mu $obj, Mu:T $type, str $attributename --> str)

Returns the attribute of name $attributename of object $obj, where the object was declared in class $type. The _n, _i, and _s variants are for natively typed attributes.

The following example demonstrates why the type object needs to passed along, and cannot be inferred from the object:

class A      { has str $!x }
class B is A { has str $!x }

my $obj := nqp::create(B);
nqp::bindattr_s($obj, A, '$!x', 'A.x');
nqp::bindattr_s($obj, B, '$!x', 'B.x');

nqp::say(nqp::getattr_s($obj, A, '$!x'));
nqp::say(nqp::getattr_s($obj, B, '$!x'));

Throws an exception if there is no such attribute in the class, the attribute is of the wrong type, or the object doesn't conform to the type.

Note that in languages that support a full-blown container model, you might need to decontainerize $obj before passing it to getattr, unless you actually want to access an attribute of the container.

getcomp

getcomp(str $base-class --> Mu)

Returns the compiler class registered for that $base-class. See bindcomp for more information.

how

how(Mu $obj --> Mu)
how_nd(Mu $obj --> Mu)

NQP equivalent for Raku's $obj.HOW.

The _nd variant does not decontainerize the object.

objectid

objectid($obj --> int)

Returns a numeric object ID unique for the given object.

rebless

rebless(Mu $obj, Mu:T $type --> Mu)

Convert $obj to be an object of the new $type.

reprname

reprname(Mu $obj --> str)

Return the name of the REPR for the given object.

setwho

setwho(Mu $obj, Mu $who --> Mu)

Replace $obj's WHO. Return $obj.

tryfindmethod

tryfindmethod(Mu $obj, str $method --> Mu)

If the object has a method of the given name, return it. Otherwise, return Mu.

what

what(Mu $obj --> Mu)
what_nd(Mu $obj --> Mu)

NQP equivalent for Raku's $obj.WHAT.

The _nd variant does not decontainerize the object.

where

where(Mu $obj --> int)

Return the memory address for this $obj. Please note that this is NOT a constant value for a given object. Please use objectid for that.

who

who(Mu $obj --> Mu)

NQP equivalent for Raku's $obj.WHO.

Parametric Extensions

setparameterizer

setparameterizer(type, parameterizer)

Makes a type as being parametric, and configures the code needed to parameterize it.

parameterizetype

parameterizetype(type, parameter_array)

Takes a parameterizable type and an array of parameters. Looks up and returns any existing matching parameterization. If it does not exist, invokes the parameterization producer for the parametric type, installs that in the lookup, and returns it. Note that the array is snapshotted, for the benefits of the type specializer.

typeparameterat

typeparameterat(type, idx)

Equivalent to nqp::atpos(nqp::typeparameters(type), idx), except much easieri for type specialization to understand and deal with and avoids an array construction.

typeparameterized

typeparameterized(type)

If the type specified is a parameterization of some other type, then returns that type. Otherwise, returns null.

typeparameters

typeparameters(type)

Gets the type parameters used to parameterize the type. Throws an exception if the type is not parametric.

Profiling

force_gc `moar` `jvm`

force_gc()

Force the garbage collector to run.

mvmendprofile `moar`

mvmendprofile(--> Object)

Turns off the profiler and returns data gathered.

heap

currently doesn't return anything. it does, however, cause one heap snapshot to be taken immediately.
instrumented

The first element is an array of arrays with information about the types that have been allocated. At the moment of writing, this array appears to have information about objects that were created, but for which there is no allocation information. It has the following structure:

0                                  - array with type information
├ 0 = 140415871842064               - unique ID for this type
└ 1                                 - hash with additional information
  ├ repr => P6opaque                  - name of the REPR of this type
  ├ type => Block                     - type object of type (aka, the .WHAT)
  ├ managed_size => 72                - size in bytes of instance
  └ has_unmanaged_data => 1           - is there additional data on heap?

The second element of the list returned by nqp::mvmendprofile, is a list of hashes, one for each thread on which data has been collected. It has the following structure (times are in microseconds, sizes are in bytes):

0                                 - hash with info of thread
├ thread => 1                       - OS thread ID
├ parent => 0                       - OS thread ID of parent thread
├ spesh_time => 0                   - amount of time spent in spesh
├ start_time => 0                   - when thread was started
├ total_time => 21004               - total time spent in thread
├ call_graph                        - hash with first Callee info
│ ├ id => 140328666076608             - unique ID of this Callee
│ ├ first_entry_time => 0             - when Callee was first called
│ ├ inclusive_time => 2               - time spent here + all sub-Callees
│ ├ exclusive_time => 2               - time spent in this Callee
│ ├ entries => 97897                  - number of times Callee was called
│ ├ inlined_entries => 56757          - times called when inlined
│ ├ jit_entries => 6566               - times called when jitted
│ ├ osr => 1                          - times Callee was OSR'd
│ ├ name => foo                       - name of Callee (if available)
│ ├ file => gen/moar/BOOTSTRAP.nqp    - filename of Callee
│ ├ line => 2070                      - line of Callee in file
│ ├ allocations => (2)                - array with Allocations
│ │ ├ 0                                 - hash with Allocation info
│ │ │ ├ count => 100                      - number of allocations
│ │ │ ├ replaced => 1                     - scalar replacements stopping alloc
│ │ │ └ id => 140329083232016             - type ID
│ └ callees => (2)                    - array with Callees called here
└ gcs                               - array with Garbage Collections
  └ 0                                 - hash with GC info
    ├ sequence => 0                     - ordinal number of GC
    ├ start_time => 1964                - when GC was started
    ├ time => 7222                      - time spent doing GC
    ├ full => 0                         - whether or not a full GC
    ├ responsible => 1                  - thread ID that triggered this GC
    ├ promoted_bytes => 212960          - bytes promoted from the nuresery
    ├ promoted_bytes_unmanaged => 54781 - additional bytes promoted
    ├ retained_bytes => 76576           - bytes *not* promoted
    ├ cleared_bytes => 3228716          - bytes cleared from the nursery
    ├ gen2 => 18402                     -
    ├ gen2_roots => 18402               - gen2 allocs rooted in nursery
    ├ deallocs                          - array with Deallocations
      ├ 0                                 - hash with deallocation info
        ├ id => 140329080607960             - type ID being deallocated
        ├ nursery_seen => 10                - seen before in a GC
        └ nursery_fresh => 6                - *not* seen before in a GC

mvmstartprofile `moar`

mvmstartprofile(hash $config)

Turns on one of MoarVM's profilers. The configuration must have a kind key that specifies which profiler will be turned on:

instrumented

takes no further configuration options. records call graph, garbage collection, and object allocation information.
heap

takes a path / filename in the path key. writes a snapshot of the heap's structure (objects and their connections) to the file every time the GC runs.

If a profiler is already active, an exception will be thrown; only one profiler can run at a time.

Serialization context

createsc

createsc($handle-string)

Creates a serialization context and returns it.

deserialize

deserialize()

forceouterctx

forceouterctx($code-object, $context)

Sets the code object's outer to the context's frame and also the code object's static frame's outer to the context's static frame.

Used to embed a separately compiled code object in a given context, e.g. to give an EVALed code a surrounding lexical scope.

freshcoderef

freshcoderef($code-object)

Creates a clone of the given code object and a clone of its static frame and connects the two. Returns the clone of the code object. Used for creating a fresh copy of a statically compiled piece of code so each of some high level code object can gets its own low level executable.

getobjsc

getobjsc($obj)

markcodestatic

markcodestatic($code-object)

Marks the code as "static" meaning it's not a closure and thus no closure will be serialized.

neverrepossess

neverrepossess($obj)

Prevents the object from ever getting repossessed. Repossession means that an object from a different serialization context, i.e. something we got from loading a module, gets added to our own serialization context as well. This is done to keep modifications to the object. Of course if different versions of the same object are loaded from different serialization contexts, there's a conflict that requires resolution -> resolve_reposession_conflicts. In the common case of the object being a Stash, we can just merge the different versions unless the keys overlap. For some objects we do not want repossession even if they were modified, i.e. they were only needed for compilation and/or there wouldn't be a way to resolve conflicts.

popcompsc

popcompsc($sc)

pushcompsc

pushcompsc($sc)

scgetdesc

scgetdesc($sc)

Get the descriptor set by scsetdec

scgethandle

scgethandle($sc)

Get the handle string used by createsc to create the SC $sc

scgetobjidx

scgetobjidx()

scobjcount

scobjcount()

scsetcode

scsetcode($sc, $index, $code-object)

Adds $code-object to the serialization context at block index $index

scsetdesc

scsetdesc($sc, $descriptor-string)

Set a descriptor for $sc created by createsc()

scsetobjc

scsetobj($sc, $idx, $obj)

serialize

serialize()

setobjsc

setobjsc($obj, $sc)

Stream Decoding

decoderaddbytes

decoderaddbytes(Decoder $dec, VMArray $blob)

Adds bytes to the decoder's internal buffer. Must have VMArray REPR, and must have elements of type int8 or uint8.

decoderbytesavailable

decoderbytesavailable(Decoder $dec --> int)

Returns the number of undecoded bytes available inside of the decoder. This is useful in the case that chunks of the input should also be pulled out as bytes, and may be useful for doing tuning or pre-fetching in various other cases. Note that the result does not include bytes that were decoded but have not yet been taken as characters, or that were decoded to code points that are still in the normalization buffer. Thus the result is only accurate before reading any chars or after decodertakechars or after decodertakeline with $incomplete-ok passed a non-zero value.

decoderconfigure

decoderconfigure(Decoder $dec, str $encoding, VMHash $config)

Configures the decoder with an encoding. The $config hash parameter is currently unused, and an empty hash or an nqp::null should be passed.

decoderempty

decoderempty(Decoder $dec --> int)

Returns 1 if the decoder is empty (this means that there are no undecoded bytes, no decoded but untaken chars, and nothing in the normalization buffer). Otherwise returns 0.

decodersetlineseps

decodersetlineseps(Decoder $dec, VMArray $separators)

Sets the line separators to be used for line-based reading. It should be a string array (nqp::list_s(...)).

decodertakeallchars

decodertakeallchars(Decoder $dec --> str)

Decodes all remaining undecoded bytes, and flushes the normalization buffer. Returns an NFG string consisting of the decoded characters. This is suitable to use when the end of a stream of bytes to decode has been reached (for example, EOF when reading a file).

decodertakeavailablechars

decodertakeavailablechars(Decoder $dec -->int)

Decodes all remaining undecoded bytes. Returns an NFG string consisting of the decoded characters. Does not flush the normalization buffer. This is suitable when performing streaming decoding, and a later byte buffer may provide a combining character.

decodertakebytes

decodertakebytes(Decoder $dec, VMArray $blob_type, int $bytes)

Takes up to $bytes bytes from the decode stream's undecoded buffer, makes an instance of the $blob_type, and places the bytes in it. The same set of caveats about decoded-but-untaken bytes in decoderbytesavailable apply.

decodertakechars

decodertakechars(Decoder $dec, int $num-chars --> str)

Returns an NFG string consisting of $num-chars graphemes, provided that many are available after decoding. If less than $num-chars characters can be decoded, then nqp::null_s will be returned. Note that a decoded codepoint at the end of a byte buffer may not be available as a character if the encoding allows the next character to be a combining character.

decodertakeline

decodertakeline(Decoder $dec, int $chomp, int $incomplete-ok --> str)

Decodes bytes until a line separator is reached, or all bytes have been decoded. If $incomplete-ok is zero and the separator was not found, then nqp::null_s will be returned. (Thus, $incomplete-ok is appropriate only when knowing that the end of the stream has been reached.) If $chomp is non-zero, then the separator--if present--will not be included in the resulting string.

String

chars

chars(str $str --> int)
charsnfg(str $str --> int) js

Return the number of characters in the string.

chr

chr(int $codepoint --> str)

Given a unicode codepoint, return a str containing its character. Will throw an exception on invalid codepoints.

codepointfromname

codepointfromname(str $name --> int)

Returns the codepoint for the given unicode character name, or -1 if no match was found.

codes

codes(str $str --> int)

Return the number of codepoints in the string.

concat

concat(str $l, str $r --> str)

Return a string that is the concatenation of the two passed in strings.

decode

decode($buffer, str $encoding --> str)

Returns an (NFG) string resulting from decoding the specified buffer assuming the specified encoding.

decodetocodes `moar`

decodetocodes($buffer, str $encoding, int $normalization, $codes)

Decodes the bytes in the specified buffer using the provided encoding. Applies normalization as requested (must be one of the nqp::const::NORMALIZE_* values; use nqp::const::NORMALIZE_NONE to apply no normalization). Places the code points into $codes, which should be some VMArray holding 32-bit integers.

encode

encode(str $string, str $encoding, $buffer)

Encodes an (NFG) string into the specified encoding, writing into the buffer provided. The data written is normalized according to NFC.

encodefromcodes `moar`

encodefromcodes($codes, str $encoding, $buffer)

Takes a 32-bit integer array of Unicode codepoints, encodes them using the chosen encoding, and writes them into the buffer. No normalization is applied.

encodenorm

encode(str $string, str $encoding, int $normalization, $buffer)

Encodes an (NFG) string into the specified encoding, writing into the buffer provided. The data written is normalized according to the normalization value passed (which must be one of the nqp::const::NORMALIZE_* values). Specifying NORMALIZE_NONE is equivalent to NFC.

escape

escape(str $str --> str)

Given a string, return an escaped version that replaces the following characters with their escaped equivalents: "\", "\b", "\n", "\r", "\t", "\f", """, "\a", and "\e".

fc

fc(str $str --> str)

Returns a Unicode "fold case" operation copy of string, suitable for doing caseless string comparisons.

findcclass

findcclass(int $class, str $str, int $i, int $count --> int)

Search the string starting at the $ith character, for $count characters. Return the position of the first character that is of the specified class (nqp::const::CCLASS_*). If no characters match, return the position of the first character after the given range, or the length of the string, whichever is smaller.

findnotcclass

findnotcclass(int $class, str $str, int $i, int $count --> int)

Search the string starting at the $ith character, for $count characters. Return the position of the first character that is not of the specified class (nqp::const::CCLASS_*). If no characters match, return the position of the first character after the given range, or the length of the string, whichever is smaller.

flip

flip(str $str --> str)

Return a string with the characters of $string in reverse order.

index

index(str $haystack, str $needle --> int)
index(str $haystack, str $needle, int $pos --> int)

Return the position in $haystack at which $needle appears, or -1 if $needle does not appear. Begin searching at position $pos if specified, or at 0, otherwise.

indexfrom(str $haystack, str $needle, int $pos) moar jvm Internal

index is converted to this internal opcode by the compiler.

indexic `moar`

indexic(str $haystack, str $needle, int $pos --> int)

This op has the same arguments and functionality as nqp::index, except it is case-insensitive. For now we only have it under MoarVM, but the plan is to support it on other platforms as well.

On MoarVM uses proper Unicode foldcase type comparison.

indexicim `moar`

indexicim(str $haystack, str $needle, int $pos)

Ignorecase and ignoremark index

indexim `moar`

indexim(str $haystack, str $needle, int $pos --> int)

Like index but decomposes and matches against the base character.

Example: indexim("bcá", "a", 0) → 2

indexingoptimized

indexingoptimized(str --> str)

If the input string is made up of strands, then returns a flattened string that is otherwise identical. If not, returns the input string.

Intended for strings that will be indexed into often, for example, when evaluating regexes.

iscclass

iscclass(int $class, str $str, int $i --> int)
iscclassnfg(int $class, str $str, int $i --> int) js

Return 1 if the $ith character of $str is of the specified class, (nqp::const::CCLASS_*), 0 otherwise.

join

join(str $delim, @arr --> str)

Joins the separate strings of @arr into a single string with fields separated by the value of EXPR, and returns that new string.

lc

lc(str $str --> str)

Return lowercase copy of string.

normalizecodes

normalizecodes($codes-in, int $normalization, $codes-out)

Takes the codepoints in $codes-in, applies the specified normalization, and places the result into the $codes-out array. Both arrays of codepoints must be 32-bit integer arrays.

numify

use nqp; say nqp::numify(nqp::unbox_s("42e0"));

Converts a string to one of the numeric types. Only used in HLL space, as in pure nqp +"42e0" performs the same numification. The op can be used, for example, to parse a Num out of a string.

ord

ord(str $str --> int)
ord(str $str, int $i --> int)

Return the unicode codepoint of the first character in $str, or at the $ith character, if it's specified.

ordat(str $str, int $i --> int) Internal
ordfirst(str $str --> int) moar jvm Internal

ord is converted to these internal opcodes by the compiler.

ordbaseat

ordbaseat(str $str, int $pos --> int)

Returns the Unicode codepoint which is the base (non extend/prepend character at that position). If it is a degenerate, and contains no base character, it then returns the first codepoint in that grapheme.

radix

radix(int $radix, str $str, int $pos, int $flags --> Mu)
radix_I(int $radix, str $str, int $pos, int $flags, Mu:T $type --> Mu)

Convert string $str into a number starting at offset $pos and using radix $radix. The result of the conversion returns an array with

out[0] = converted value
out[1] = $number-of-digits-converted
out[2] = offset after consuming digits, -1 if no digits consumed

The opcode skips single underscores between pairs of digits, per the Raku specification.

The $flags is a bitmask that modifies the parse and/or result:

0x01: negate the result (useful if you've already parsed a minus)
0x02: parse a leading +/- and negate the result on -
0x04: parse trailing zeroes but do not include in result
      (for parsing values after a decimal point)

replace

replace(str $str, int $offset, int $count, str $replacement --> str)

Return a copy of $str where the characters starting at $offset for $count characters have been replaced with the $replacement string.

rindex

rindex(str $haystack, str $needle --> int)
rindex(str $haystack, str $needle, int $pos --> int)

Searching backwards through the $haystack, return the position at which $needle appears, or -1 if it does not. Begin searching at $pos if specified, otherwise start from the last position.

rindexfrom(str $haystack, str $needle, int $pos) moar jvm Internal
rindexfromend(str $haystack, str $needle) jvm Internal

rindex is converted to this internal opcode by the compiler.

sha1

sha1(str $str -> str)

Given a UTF-8 string, return the SHA-1 digest for that string. This op is built for the specific purpose of hashing source code for dependency management purposes, and isn't intended to be used more widely.

split

split(str $delimiter, str $string --> Mu)

Splits the string $string into an array of elements; these elements are the substrings between delimiters in the original string.

If the original string begins or ends with the delimiter, the resulting array will begin or end with an empty element.

sprintf

sprintf(str $pattern, @values --> str)

Returns a string formatted by the printf conventions similar to Perl 5 / C. Machine sized numeric types, their limits and therefore overflows are not implemented though.

sprintfaddargumenthandler

sprintfaddargumenthandler(Mu $handler)

Lets you register a handler-instance that supports the sprintf op when it has to numify custom types. This handler has to provide two methods, mine and int. mine gets the the value in question and returns true if this handler is in charge for this type, false otherwise. The method int does the conversion for patterns like %d.

my class MyHandler {
    method mine($x) { $x ~~ MyType }
    method int($x) { $x.Int }
}

sprintfdirectives

sprintfdirectives(str $pattern)

This takes the same pattern as sprintf does, and computes the needed value-count that sprintf would have to provide.

strfromcodes

strfromcodes($codes --> str)

Returns an (NFG) string built from the specified codepoints, which must be provided as a 32-bit integer array.

strfromname

strfromname(str $name --> str)

Like codepointfromname except it returns a string instead of a codepoint. This function is able to return not just Unicode codepoints by name, but also Unicode Named Sequences, including Emoji Sequences and Emoji ZWJ Sequences and Name Aliases.

In addition it is also case-insensitive, unlike codepointfromname

See these links for a full list of Named Sequences, Emoji Sequences, Emoji ZWJ Sequences and Name Aliases.

strtocodes

strtocodes(str $str, int $normalization, $codes)

Takes an NFG string, and places the codepoints from it into the codes array, which must be a 32-bit integer array. Applies the specified normalization, specified as one of the nqp::const::NORMALIZE_* values; NORMALIZE_NONE is not allowed.

substr

substr(str $str, int $position --> str)
substr(str $str, int $position, int $length --> str)
substr_s(str $str, int $position --> str) moar
substr_s(str $str, int $position, int $length --> str) moar
substr2(str $str, int $position) jvm Internal
substr3(str $str, int $position, int $length) jvm Internal
substrnfg(str $str, int $position --> str) js
substrnfg(str $str, int $position, int $length --> str) js

Return the portion of the string starting at the given position. If $length is specified, only return that many characters. The numbered variants required the args specified - the unnumbered version may use either signature.

tc

tc(str $str --> str)

Return titlecase copy of string.

tclc

tclc(str $str --> str)

Return copy of string with first character titlecased, and remaining characters lowercased.

uc

uc(str $str --> str)

Return uppercase copy of string.

unicmp_s `moar` `js`

unicmp_s(str $str1, str Str2, int $mode, int $iso639, int $iso3166 --> int)

Compares strings using the Unicode Collation Algorithm (UCA).

Parameters:

$str1, $str2  # strings to compare
$mode         # collation mode (bitmask)
$iso639       # ISO 639 Language code
$iso3166      # ISO 3166 Country code

The collation mode defines whether we use Primary, Secondary, Tertiary and/or Quaternary sorting.

Compares two strings, using the Unicode Collation Algorithm Return values: 0 The strings are identical for the collation levels requested -1/1 String a is less than string b/String a is greater than string b

collation_mode acts like a bitfield. Each of primary, secondary and tertiary collation levels can be either: disabled, enabled, reversed. In the table below, where + designates sorting normal direction and

indicates reversed sorting for that collation level.

 Collation level | bitfield value
        Primary+ |   1
        Primary- |   2
      Secondary+ |   4
      Secondary- |   8
       Tertiary+ |  16
       Tertiary- |  32
     Quaternary+ |  64
     Quaternary- | 128

While the Primary, Secondary and Tertiary mean different things for different scripts, for the Latin script used in English they mostly correspond with Primary being Alphabetic, Secondary being Diacritics and Tertiary being Case.

Setting 0 for language and country will collate all scripts according to their own distinctions for Primary, Secondary, and Tertiary, although it will not take into account certain languages.

For example, some language based differences in collation:

“…include ch as in traditional Spanish, ä as in traditional German, and å as in Danish” ― Unicode Technical Report 10.

For more information see Unicode TR10.

*** Note ***

Currently only language and country insensitive sorting methods are implemented.

x

x(str $str, int $count --> str)

Return a new string containing $count copies of $str.

System Introspection

backendconfig

backendconfig(--> Mu)

Returns a hash containing backend-specific information, like backend-version, configure and build flags.

cpucores

cpucores()

Returns a native integer for the number of CPU cores that are reported to be available.

freemem

freemem()

Returns amount of free memory available in the system (not the NQP VM itself) (in bytes).

getenvhash

getenvhash(--> Mu)

Returns a hash containing the environment variables. Changing the hash doesn't affect the environment variables

getrusage

getrusage(int @rusage)

Accepts an integer array and fills it with usage data, of which the following elements are currently defined:

RUSAGE_UTIME_SEC Userland CPU usage: seconds part
RUSAGE_UTIME_MSEC Userland CPU usage: micro-seconds part
RUSAGE_STIME_SEC System CPU usage: seconds part
RUSAGE_STIME_MSEC System CPU usage: micro-seconds part
RUSAGE_MAXRSS Maximum resident set size: in bytes/Kbytes
RUSAGE_IXRSS Integral shared text memory size: in bytes/Kbytes
RUSAGE_IDRSS Integral unshared data size: in bytes/Kbytes
RUSAGE_ISRSS Integral unshared stack size: in bytes/Kbytes
RUSAGE_MINFLT Number of page reclaims: lower part
RUSAGE_MAJFLT Number of page reclaims: upper part
RUSAGE_NSWAP Number of swaps
RUSAGE_INBLOCK Number of block input operations
RUSAGE_OUBLOCK Number of block output operations
RUSAGE_MSGSND Number of messages sen
RUSAGE_MSGRCVA Number of messages received
RUSAGE_NSIGNALS Number of signals received
RUSAGE_NVCSW Number of voluntary context switches
RUSAGE_NIVCSW Number of involuntary context switches

Currently, the elements ending in RSS appear to return values in bytes rather than Kbytes on MacOS.

Elements may be 0 if it is impossible to determine that value in the current system.

getsignals

getsignals(--> Mu)

Returns a list containing signal names interleaved with the associated signum integer on the host platform (MacOSX, Linux, BSD, etc).

If the current backend does not support the registering of a signal handler for a given signal, the hash value will be a negative integer. For instance, the JVM only supports signal handlers for SIGINT and SIGKILL, so all the values will be negative except 2 (SIGINT) and 9 (SIGKILL). If a signal is not available on the host system, the hash value will be set to 0.

The complete list of signal entries is as follows:

* SIGHUP
* SIGINT
* SIGQUIT
* SIGILL
* SIGTRAP
* SIGABRT
* SIGEMT
* SIGFPE
* SIGKILL
* SIGBUS
* SIGSEGV
* SIGSYS
* SIGPIPE
* SIGALRM
* SIGTERM
* SIGURG
* SIGSTOP
* SIGTSTP
* SIGCONT
* SIGCHLD
* SIGTTIN
* SIGTTOU
* SIGIO
* SIGXCPU
* SIGXFSZ
* SIGVTALRM
* SIGPROF
* SIGWINCH
* SIGINFO
* SIGUSR1
* SIGUSR2
* SIGTHR
* SIGSTKFLT
* SIGPWR
* SIGBREAK

jvmclasspaths `jvm`

jvmclasspaths(--> Mu)

Converts the JVM property java.class.path into a list of paths, returns it.

jvmgetproperties `jvm`

jvmgetproperties(--> Hash)

Map the JVM's System.getProperties into a Hash usable in NQP. Normalizes some OS names (key: 'os.name'), returns all other data as is.

jvmgetunicodeversion `jvm`

jvmgetunicodeversion(--> String)

Returns the Unicode version that is supported by the Java Runtime.

totalmem

totalmem(--> int)

Returns the number of bytes of memory in use by the VM.

uname `moar` `js`

uname(--> Mu)

Returns a string array and fills it with uname data, of which the following elements are currently defined:

UNAME_SYSNAME Name of the operating system implementation
UNAME_RELEASE Release level of the operating system
UNAME_VERSION Version level of the operating system
UNAME_MACHINE Machine hardware platform

Threads

currentthread `moar` `jvm`

currentthread()

Returns the vm_thread object for the current thread.

newthread `moar` `jvm`

newthread(block, app_lifetime --> vm_thread)

Takes a block to execute in a thread, and a 1 to indicate that the thread will be killed if the main thread finishes, or 0 to keep the thread running even after the main thread has finished. Returns a vm_thread object that can be passed to the other thread related opcodes.

threadid `moar` `jvm`

threadid(vm_thread --> int)

Returns the numeric thread ID of the given vm_thread object.

threadjoin `moar` `jvm`

threadjoin(vm_thread)

Wait for the thread, indicated by the vm_thread object, to be finished.

threadlockcount `moar` `jvm`

threadlockcount(vm_thread)

Returns the number of locks held by the given thread.

threadrun `moar` `jvm`

threadrun(vm_thread)

Actually start running the code specified in the creation of the vm_thread object.

threadyield `moar` `jvm`

threadyield()

Tell the scheduler to prefer another thread then the thread this is being executed in, for now.

Timish

decodelocaltime

decodelocaltime(int $epoch --> int @tm)

Returns an integer array with localtime information, formatted like the C struct tm: $sec,$min,$hour,$mday,$mon,$year,$weekday,$yearday,$isdst. Note that contrary to C's localtime() function, the $year contains the actual year (A.D), and the $month has been normalized to 1..12.

sleep

sleep(num $seconds --> num)

Sleep for the given number of seconds (no guarantee is made how exact the time sleeping is spent.) Returns the passed in number.

time

time(--> int)

Return the time in nanoseconds since January 1, 1970 UTC (1970-01-01T00:00:00Z).

Trigonometric

acos

acos_n(num $n --> num)

Arccosine.

asin

asin_n(num $n --> num)

Arcsine.

atan

atan_n(num $n --> num)

Arctangent.

atan2

atan2_n(num $l, num $r --> num))

2-argument Arctangent.

cos

cos_n(num $n --> num))

Cosine.

cosh

cosh_n(num $n --> num))

Hyperbolic cosine.

sin

sin_n(num $n --> num))

Sine.

sinh

sinh_n(num $n --> num))

Hyperbolic sine.

tan

tan_n(num $n --> num))

Tangent.

tanh

tanh_n(num $n --> num))

Hyperbolic tangent.

Type / Conversion

bool

bool_I(Int $val)

Returns 0 if $val is 0, otherwise 1.

bootarray `moar` `jvm`

bootarray()

Returns a VM specific type object for a native array.

boothash `moar` `jvm`

boothash()

Returns a VM specific type object for a native hash.

bootint `moar` `jvm`

bootint()

Returns a VM specific type object that can box a native int.

bootintarray `moar` `jvm`

bootintarray()

Returns a VM specific type object for a native array of int.

bootnum `moar` `jvm`

bootnum()

Returns a VM specific type object that can box a native num.

bootnumarray `moar` `jvm`

bootnumarray()

Returns a VM specific type object for a native array of num.

bootstr `moar` `jvm`

bootstr()

Returns a VM specific type object that can box a native str.

bootstrarray `moar` `jvm`

bootstrarray()

Returns a VM specific type object for a native array of str.

box

box_i(int $val, Mu:T $type)
box_n(num $val, Mu:T $type)
box_s(str $val, Mu:T $type)
box_u(int $val, Mu:T $type) moar

Given a native value, return a Raku object of the given type with the same value.

decont

decont(Mu $val --> Mu)
decont_i(Int $val --> Mu)
decont_n(Num $val --> Mu)
decont_s(Str $val --> Mu)

Extract, or de-containerize, a value from a Scalar container. If the argument is not a container, the argument is returned unchanged:

use nqp;
my $a = (1, 2, 3);
.say for $a;              # OUTPUT: «(1, 2, 3)␤»
.say for nqp::decont($a); # OUTPUT: «1␤2␤3␤»

The decont_i decontainerizes to a native int value, decont_n to a native num value, and decont_s to a native str value.

defined

defined(Mu $obj --> int)

Returns 1 if the object is not null and is not a Type object, 0 otherwise.

fromI_I

fromI_I(Int $val --> Int)

Rebox Big Integer value, removing any potential mixins.

fromnum

fromnum_I(num $val, Mu:T $type --> Int)

Convert float value to a Big Integer of the given type, discarding any decimal portion.

fromstr

fromstr_I(str $val, Mu:T $type --> Int)

Convert string value to a Big Integer of the given type.

isbig

isbig_I(Int $obj --> int)

Returns a 1 if the object's numerical representation requires a big int, 0 otherwise.

iscoderef `moar`

iscoderef($obj --> int)

Returns a 1 if the object contains a code reference, 0 otherwise.

isconcrete

isconcrete(Mu $obj --> int)
isconcrete_nd(Mu $obj --> int)

Returns a 1 if the object is not a type object, 0 otherwise.

The _nd variant does not decontainerize the object.

iscont

iscont(Mu $obj --> int)
iscont_i(int $int --> int)
iscont_n(num $int --> int)
iscont_s(str $int --> int)

Returns a 1 if the object is a container type, 0 otherwise.

isfalse

isfalse(Mu $obj --> int)

Returns a 0 if the object has a truthy value, 1 otherwise.

ishash

ishash(Mu $obj --> int)

Returns a 1 if the object is a native Hash, 0 otherwise.

isint

isint(Mu $obj --> int)

Returns a 1 if the object is a native int type, 0 otherwise.

isinvokable

isinvokable(Mu $obj --> int)

Returns a 1 if the object represents something executable, 0 otherwise.

islist

islist(Mu $obj)

Returns a 1 if the object is an Array, 0 otherwise.

isnanorinf

isnanorinf(num $n --> int)

Return truth value indicating if this number represents any of the special values, positive infinity, negative infinity, or NaN.

isnull

isnull(Mu $obj --> int)
isnull_s(str $obj --> int)

Returns a 1 if the object is a null, 0 otherwise.

isnum

isnum(Mu $obj --> int)

Returns a 1 if the object is a native float type, 0 otherwise.

isprime

isprime_I(Int $obj --> int)

Returns a 1 if the integer value of the object is prime, 0 otherwise.

isrwcont

isrwcont(Mu $obj --> int)

Returns a 1 if the object is a container type and can be written to, 0 otherwise.

isstr

isstr(Mu $obj --> int)

Returns a 1 if the object is a native str type, 0 otherwise.

istrue

istrue(Mu $obj --> int)

Returns a 1 if the object has a truthy value, 0 otherwise.

isttyfh

isttyfh(Mu $obj --> int)

Returns a 1 if the object is an IO::Handle object that is a tty, 0 otherwise.

istype

istype(Mu $obj, Mu:T $obj --> int)
istype_nd(Mu $obj, Mu:T $obj --> int)

Returns a 1 if the object is of the given type, 0 otherwise.

The _nd variant does not decontainerize the object.

null

null(--> Mu)
null_s(--> str)

Generate a null value.

null_s returns a null string value that can be stored in a native str.

The value returned by null_s is VM dependant. Notably, it may stringify differently depending on the backend.

tonum

tonum_I(Int $val --> num)

Convert Big Integer value to a native number.

tostr

tostr_I(Int $val --> str)

Convert Big Integer value to a native string.

unbox

unbox_i(Mu $val --> int)
unbox_n(Mu $val --> num)
unbox_s(Mu $val --> str)
unbox_u(Mu $val --> str) moar

Given a Raku object, return a native with the same value, of the type indicated by the opcode suffix.

Unicode Properties

getuniname

getuniname(int $codepoint --> str)

Translate a codepoint to its Unicode name.

getuniprop_bool `moar`

getuniprop_bool(int $codepoint, int $propcode --> int)

Same thing, but fetches a boolean property value.

getuniprop_int `moar`

getuniprop_int(int $codepoint, int $propcode --> int)

Uses the table found by unipropcode to look up an integer property value for a given codepoint. Note that many properties that are officially numeric are really stored as strings, and if you try to use this op on such a property, you'll get a meaningless position in an enum table instead of the value you want.

getuniprop_str

getuniprop_str(int $codepoint, int $propcode --> str)

Same thing, but fetches a string property value.

hasuniprop `moar`

hasuniprop(str $string, int offset, int propcode, int pvalcode --> int)

Checks if the string has a specific property value at a specific offset. Requires both the propcode and the pvalcode to work.

matchuniprop `moar`

matchuniprop(int $codepoint, int $propcode, int $pvalcode --> int)

Looks up a codepoint property and return 1 if it matches the pval, 0 otherwise. The propcode and pvalcode may be looked up with the opcodes above. (Note that you can use the property value name (e.g. Nd) for both lookups.)

unipropcode

unipropcode(str $propname --> int)

Translates a property name to the backend's property code. This is not distinct across backends and is expected to change over time. For the most part only useful for calling getuniprop_int, get_uniprop_str or get_uniprop_bool or comparing whether two unicode property names resolve to the same propcode, for example 'Alpha', 'alpha', 'alphabetic' and 'Alphabetic' should return the same property code.

unipvalcode `moar`

unipvalcode(int $propcode, str $propname --> int)

Looks up a property name in its property category, and returns which table within that category to use.

Miscellaneous

const

const()

Not actually an opcode, but a collection of several constants. Each of the constants below can be used in nqp as (e.g.) nqp::const::CCLASS_ANY.

* CCLASS_ANY
* CCLASS_UPPERCASE Lu
* CCLASS_LOWERCASE Ll
* CCLASS_ALPHABETIC Lo | Ll | Lu | Lt | Lm
* CCLASS_NUMERIC Nd
* CCLASS_HEXADECIMAL
* CCLASS_WHITESPACE (9..13,32,133,160,5760,8192..8202,8232,8233,8239,8287,12228)
* CCLASS_PRINTING !(0..31, 127..159)
* CCLASS_BLANK Zs
* CCLASS_CONTROL (0..31, 127..159)
* CCLASS_PUNCTUATION
* CCLASS_ALPHANUMERIC Lo | Ll | Lu | Lt | Lm | Nd
* CCLASS_NEWLINE Zl Zp
* CCLASS_WORD Lo | Ll | Lu | Lt | Lm | Nd + "_"

* HLL_ROLE_NONE
* HLL_ROLE_INT
* HLL_ROLE_NUM
* HLL_ROLE_STR
* HLL_ROLE_ARRAY
* HLL_ROLE_HASH
* HLL_ROLE_CODE

* CONTROL_ANY
* CONTROL_NEXT
* CONTROL_REDO
* CONTROL_LAST
* CONTROL_RETURN
* CONTROL_TAKE
* CONTROL_WARN
* CONTROL_SUCCEED
* CONTROL_PROCEED
* CONTROL_LABELED
* CONTROL_AWAIT
* CONTROL_EMIT
* CONTROL_DONE

* STAT_EXISTS
* STAT_FILESIZE
* STAT_ISDIR
* STAT_ISREG
* STAT_ISDEV
* STAT_CREATETIME
* STAT_ACCESSTIME
* STAT_MODIFYTIME
* STAT_CHANGETIME
* STAT_BACKUPTIME
* STAT_UID
* STAT_GID
* STAT_ISLNK
* STAT_PLATFORM_DEV
* STAT_PLATFORM_INODE
* STAT_PLATFORM_MODE
* STAT_PLATFORM_NLINKS
* STAT_PLATFORM_DEVTYPE
* STAT_PLATFORM_BLOCKSIZE
* STAT_PLATFORM_BLOCKS

* OPEN_MODE_RO
* OPEN_MODE_WO
* OPEN_MODE_RW

* PIPE_INHERIT_IN
* PIPE_IGNORE_IN
* PIPE_CAPTURE_IN
* PIPE_INHERIT_OUT
* PIPE_IGNORE_OUT
* PIPE_CAPTURE_OUT
* PIPE_INHERIT_ERR
* PIPE_IGNORE_ERR
* PIPE_CAPTURE_ERR
* PIPE_MERGED_OUT_ERR

* TYPE_CHECK_CACHE_DEFINITIVE
* TYPE_CHECK_CACHE_THEN_METHOD
* TYPE_CHECK_NEEDS_ACCEPTS

* C_TYPE_CHAR
* C_TYPE_SHORT
* C_TYPE_INT
* C_TYPE_LONG
* C_TYPE_LONGLONG
* C_TYPE_SIZE_T
* C_TYPE_BOOL
* C_TYPE_ATOMIC_INT
* C_TYPE_FLOAT
* C_TYPE_DOUBLE
* C_TYPE_LONGDOUBLE

* NORMALIZE_NONE
* NORMALIZE_NFC
* NORMALIZE_NFD
* NORMALIZE_NFKC
* NORMALIZE_NFKD

* RUSAGE_UTIME_SEC
* RUSAGE_UTIME_MSEC
* RUSAGE_STIME_SEC
* RUSAGE_STIME_MSEC
* RUSAGE_MAXRSS
* RUSAGE_IXRSS
* RUSAGE_IDRSS
* RUSAGE_ISRSS
* RUSAGE_MINFLT
* RUSAGE_MAJFLT
* RUSAGE_NSWAP
* RUSAGE_INBLOCK
* RUSAGE_OUBLOCK
* RUSAGE_MSGSND
* RUSAGE_MSGRCV
* RUSAGE_NSIGNALS
* RUSAGE_NVCSW
* RUSAGE_NIVCSW

* BINARY_ENDIAN_LITTLE
* BINARY_ENDIAN_BIG
* BINARY_ENDIAN_NATIVE

* BINARY_SIZE_8_BIT
* BINARY_SIZE_32_BIT
* BINARY_SIZE_16_BIT
* BINARY_SIZE_64_BIT

* SOCKET_FAMILY_UNSPEC
* SOCKET_FAMILY_INET
* SOCKET_FAMILY_INET6
* SOCKET_FAMILY_UNIX

* DISP_NONE
* DISP_CALLSAME
* DISP_CALLWITH
* DISP_LASTCALL
* DISP_NEXTCALLEE
* DISP_ONLYSTAR
* DISP_DECONT
* DISP_BIND_SUCCESS
* DISP_BIND_FAILURE
* DISP_PROPAGATE_CALLWITH

* UNAME_SYSNAME
* UNAME_RELEASE
* UNAME_VERSION
* UNAME_MACHINE

debugnoop `jvm`

debugnoop(Mu $a)

Returns $a. Does nothing, exists only to provide a breakpoint location for debugging.

getcodename

getcodename($obj --> str)

Returns the name of the given concrete code object. Throws an exception if an object of the wrong type is passed.

js `moar` `js`

js(str)

Execute the string of JavaScript code passed in.

While this opcode exists in moar, it throws an exception declaring it is not implemented.

locallifetime

QAST::Op.new(:op<locallifetime>, :node($/), QAST::Stmt.new(...))

Defines when local variables can be considered dead. E.g. the temporary setting of $_ on the right side of ~~ uses that.

setcodename

setcodename($obj, str)

Sets the name of the given code object. Throws an exception if an object of the wrong type is passed.

setdebugtypename

setdebugtypename($obj, str)

In all backends, sets an attribute field on the object's STable, an internal low level representation of a type.

In MoarVM, uses the debug_name field. In JVM/JS, uses the debugName field.

Intended as a debugging tool only.

takeclosure

takeclosure(Block $innerblock)

Creates a lexical closure from the block's outer scope.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!