FixTask Documentation

Back to summary

import "task/task";

ParentRef class

ParentRef allows to access references in parent heap when using the ComputeTask::run_parallel function. If not used from compute tasks the current heap is used instead to allow code that works in both modes the same.

Internally the references are just the integer portion of the reference. Therefore the references are weak: you must make sure that there exists a strong reference to such objects. It also allows to embed the references directly in shared arrays.

Security implications: this class allows to access arbitrary objects in the current heap. This may be an issue for specific usages (eg. native code that has some hidden objects in the heap that are normally not accessible and reading them has security implications or if they contain shared arrays as these are writable). You can protect such objects using the fixscript_set_protected function.

Functions

static function create(obj): ParentRef

Creates a new reference to parent heap. This just converts the integer part of the reference to a pure integer. The same can be achieved by using (obj as Integer)|0. Additionally it checks for floats so it leaves them as is so you should use this constructor in general case (also for better readibility).

function length(): Integer

Returns the length of the array or hash.

function array_get(idx: Integer): ParentRef

Returns the reference (or integer/float value) at given index in an array.

function is_array(): Boolean
function is_string(): Boolean
function is_hash(): Boolean
function is_shared(): Boolean
function is_funcref(): Boolean
function is_weakref(): Boolean
function is_handle(): Boolean


Returns whether the reference is one of these types. You should use normal is_float for detecting floats as these are passed directly. Integers can't be tested for.

function get(): Dynamic
function clone(): Dynamic


Returns the deep clone of the reference. The get function caches the clone so it will always return the same cloned reference.

function get_shared_count(): Integer

Returns the number of referenced heaps for given shared array.

function get_element_size(): Integer

Returns the (current) element size of the array.

function copy_to(dest, dest_off: Integer, src_off: Integer, count: Integer)

Copies the deep cloned values (each value independently) from the array reference.

function extract(off: Integer, count: Integer): Dynamic

Extracts the portion of the array (each value is deep cloned independently).

function weakref_get(): ParentRef

Returns the target reference of this weak reference.

function hash_get(key, default_value): ParentRef

Returns the value for given key (the key is value in current heap) or the provided default value in case the key is not found.

function hash_contains(key): Boolean

Returns true when the hash table contains the given key (the key is value in current heap).

function to_string(): String
function to_string(newlines: Boolean): String


Returns the string representation of the reference.