Native references

Functions
crocref_t	croc_ref_create (CrocThread *t, word_t idx)
word_t	croc_ref_push (CrocThread *t, crocref_t r)
void	croc_ref_remove (CrocThread *t, crocref_t r)

Detailed Description

Pinning Croc objects, letting native code hold on to references to them.

Function Documentation

crocref_t croc_ref_create	(	CrocThread *	t,
		word_t	idx
	)

Create a native reference to an object.

Native references are a way for native code to keep a reference to a Croc object without having it get collected. You create a reference to the object, then use croc_ref_push to get the object associated with that reference. When you no longer need to reference the object, use croc_ref_remove to remove it.

You can create multiple references to the same object. In this case, you must remove all the references separately. In this way it works something like a reference counting scheme. As long as at least one native reference to an object exists, it will never be collected.

Parameters

idx	is the stack slot of the object to get a reference to. It must be a GC-able type.

Returns

the unique reference value to be passed to the other native reference functions. This is a 64-bit count, so you don't have to worry about a reference value that was removed with croc_ref_remove ever being valid again (unless you generate millions of references per second for hundreds of thousands of years).

word_t croc_ref_push	(	CrocThread *	t,
		crocref_t	r
	)

Given a reference value that was returned from croc_ref_create, pushes the object associated with that reference onto the stack.

void croc_ref_remove	(	CrocThread *	t,
		crocref_t	r
	)

Given a reference value that was returned from croc_ref_create, removes the reference to the object.

The reference value will then be invalid for the rest of the life of the program.