I6 Template Layer

Short Block Format.

A short block begins with a word which is usually, but not always, a pointer to the long block. There are three possibilities:

(a) 0 means the short block has length 1 and the long block begins at the very next word in memory. This makes it more convenient for I7 to compile BV constants, but isn't otherwise used.

(b) 1 to 255 means the short block has length 2 or more. The value is expected to be a bitmap in bits 4 to 8 together with a nonzero ID in bits 1 to 4. If the BLK_BVBITMAP_LONGBLOCK bit is set, a pointer to the long block is stored in the second word of the short block.

(c) Otherwise the short block has length 1 and contains only a pointer to the long block.

Long Block Access.

Illustrating this:

Weak Kind.

This returns the weak kind ID of a block value. Most of the time this information is stored in the long block, but that poses a problem for BVs which have no long block: we must use the bitmap instead.

Reference counting.

Reference counts lie in a word at a fixed offset from the start of the long block: doctrinally, any block value with no long block at all (such as a piece of packed text) has reference count infinity.

Changing Reference Counts.

When incrementing, infinity's the limit; when decrementing, it never reduces. Note that the decrement function returns the new reference count, but the increment function returns nothing. It's only when reference counts go downwards that we have to worry about whether something happens.

Long Block Capacity.

As we've seen, the long block has some metadata in a header, but otherwise it's organised as if it were an array, with entries 8, 16 or 32 bits wide. At any given time, the "capacity" of the LB is the number of entries in this array: that doesn't mean that the BV is using them all at any given moment.

Long Block Array Access.

Though the customer thinks he's getting an array, in fact the storage in the LB is not necessarily contiguous, since it can span multiple Flex blocks. We abstract that with two routines to read and write entries.

BlkValueRead takes two compulsory arguments and one optional one. Thus:

reads the nth entry in the long block for bv, whereas

read it from the given long block directly. BlkValueWrite is similar.

First Zero Entry.

This returns the entry index of the first zero entry in the long block's array, or -1 if it has no zeros.

Mass Copy Entries.

This copies a given number of entries from one BV's long block to another; they must both be of the same word size but can differ in header size. Functionally, it's identical to

but it's much, much faster, and runs in a reasonably small number of cycles given what it needs to do.

Mass Copy From Array.

The following is helpful when reading an array of characters into a text:

KOVS Routines.

Different kinds of value use different data formats for both their short and long blocks, so it follows that each kind needs its own routines to carry out the fundamental operations of creating, destroying, copying and comparing. This is organised at run-time by giving each kind of block value a "KOVS", a "kind of value support" routine. These are named systematically by suffixing _Support: that is, the support function for TEXT_TY is called TEXT_TY_Support and so on.

I7 automatically compiles a function called KOVSupportFunction which returns the KOVS for a given kind. Note that this depends only on the weak kind, not the strong one: so "list of numbers" and "list of texts", for example, share a common KOVS which handles all list support.

The support function can be called with any of the following task constants as its first argument: it then has a further one to three arguments depending on the task in hand.

Creation.

To create a block value, call:

where K is its (strong) kind ID. Optionally, call:

to mandate that the short block needs to be located at the given address outside the heap: but don't do this unless you can guarantee that space of the necessary length will be available there for as long as the lifetime of the value; and please note, it really does matter that this address lies outside the heap, for reasons to be seen below.

These work by delegating to:

which returns the address of the short block for the new value.

Errors.

No I7 source text should ever result in a call to this, unless it does unpleasant things at the I6 level.

Short Block Allocation.

The first thing a KOVS does when creating a value is to initialise its short block. The following routines provide for a one-word and a two-word short block respectively. The KOVS should pass these routines the same short_block value it was called with. As can be seen, if this is zero then we need to conjure up memory from somewhere: we do this using Flex. That incurs a fair amount of overhead in time and memory, though. The SB data is stored in the data portion of the Flex block, which is why we get its address from by adding the data offset to the block address.

Block Values On Stack.

As noted above, it's wasteful to keep allocating short blocks using Flex. For the short blocks of block values in local variables, we store them on a stack instead. This is a top-down stack, so the current stack frame starts out just after the end of the stack area in memory (and therefore points to an empty stack frame); it drops down as new frames are created.

BlkValueCreateOnStack acts exactly like BlkValueCreate, but stores the short block at the given word offset in the current stack frame. (I7 compiles calls to these routines when compiling code to manage local variables.)

Freeing.

As noted above, every value returned by BlkValueCreate must later be freed by calling the following routine exactly once:

In particular, if a block value is stored in any I6 location which is about to be overwritten with a new value, it's essential to call this in order properly to dispose of the old value.

As noted above, short blocks are sometimes created within Flex blocks on the heap, using FlexAllocate; and if this is one of those, we need to free the relevant Flex block.

Quick Copy.

The basic method of copying block value B into block value A is to destroy the old contents of A, which are about to be overwritten; then copy the short block of A into the short block of B, a quick process; and increment the reference count of B.

The support function should respond to:

by copying the short blocks alone.

Short Block Copy.

In fact, most of the work of copying a short block is standard. If a SB consists only a single word pointing to the LB, the first routine below handles all the work needed to handle the COPYSB_KOVS task. The surprising line in this routine is to deal with the convention that a pointer value of 0 means the LB immediately follows the SB: if that's true in from_bv, it won't be true in to_bv, so we must correct it.

Slow Copy.

Why don't we always do this? Consider the case where B is a list of rooms, and A is a list of objects. If we give A's short block a pointer to the long block of B, A will suddenly change its kind as well as its contents, because the strong kind of a list is stored inside the long block. So there are a few cases where it's not safe to make a quick copy. In any case, sooner or later you have to duplicate actual data, not just rearrange pointers to it, and here's where.

We first call:

which asks for an ID for the kinds stored in the BV: for example, for a list of rooms it would return the kind ID for "room". We ask for this because it's information stored in the long block, which is about to be overwritten.

As with the quick copy, we must now make sure any data currently in the destination is properly destroyed. We could do so by making the destination mutable and then destroying its contents, but that would be inefficient, in that it might create a whole lot of temporary copies and then delete them again. So if the long block has a high reference count, we decrement it and then replace the short block (in place) with a fresh one pointing to empty data; we only destroy the contents if the long block has reference count 1.

All of which finally means we can scribble over the destination without spoiling anybody else's day. We resize it to make room for the incoming data; we copy the raw data of the long block; and finally we:

This is where the KOVS should make a proper copy, using BlkValueCopy and thus perhaps recursing, if any of that data contained block values in turn: as for instance it will if we're copying a list of texts. Note that k is the value given us by KINDDATA_KOVS.

Copy.

As noted above, some copies are quick, and some are slow. We decide by asking the kind's support function:

which should return true if a quick copy is okay, or false if not.

Destruction.

We will also need primitives for two different forms of destruction. This is something which should happen whenever a block value is thrown away, not to be used again: either because it's being freed, or because new contents are being copied into it.

The idea of destruction is that any data stored in the long block should safely be disposed of. If the reference count of the long block is 2 or more, there's no problem, because we can simply decrement the count and let other people worry about the data from now on. But if it's only 1, then destroying the data is on us. Since we don't know what's in the long block, we have to ask the KOVS to do this by means of:

Note that all of this frequently causes recursion: destruction leads to freeing of some of the data, which in turn means that that data must be destroyed, and so on. So it's essential that block values be well-founded: a list must not, for example, contain itself.

Recycling.

This is like destruction in that it disposes of the value safely, but it tries to keep the long block for reuse, rather than deallocating it. This won't work if other people are still using it, so in the case where its reference count is 2 or more, we simply reduce the count by 1 and then replace the small block with a new one (at the same address).

Mutability.

A block value is by definition mutable if it has a long block with reference count 1, because then the data in the long block can freely be changed without corrupting other block values.

We offer the KOVS a chance to handle this for us:

should return 0 to say that it has done so, or else return the size of the short block in words to ask us to handle it. The way we do this is to create a temporary value to make a safe copy into; it would be unnecessarily slow to allocate the short block for this safe copy on the heap and then free it again moments later, so instead we put the short block on the stack, making a temporary one-value stack frame instead to hold it.

Casting.

We can also perform an assignment to an already-created block value in the form of a cast, that is, a conversion of data from one kind to another: or at least, for some kinds of value we can.

casts from the given value, with the given kind, into the existing block value to_bv. Note that the source value doesn't need to be a BV itself. This mechanism is used, for example, to cast snippets to text.

Comparison.

And it's a similar story with comparison:

looks at the data in the two BVs and returns 0 if they are equal, a positive number if bv_right is "greater than" bv_left, and a negative number if not. The interpretation of "greater than" depends on the kind, but should be something which the user would find natural.

Hashing.

Given a value of any kind, assign it a hash code which fits in a single virtual machine word, maximizing the chances that two different values will have different hash codes.

If the value can be stored in a single word already, it can be its own hash code. Otherwise, we ask:

to return one for us. Whatever this does, it must at minimum have the property that two equivalent blocks (for which COMPARE_KOVS returns 0) produce the same hash value.

Serialisation.

Some block values can be written to external files (on Glulx): others cannot. The following routines abstract that.

If ch is -1, then:

returns true or false according to whether it is possible to read data from an auxiliary file auxf into the block value bv. If ch is any other value, then the routine should do exactly that, taking ch to be the first character of the text read from the file which makes up the serialised form of the data.

is simpler because, strictly speaking, it doesn't write to a file at all: it simply prints a serialised form of the data in bv to the output stream. Since it is called only when that output stream has been redirected to an auxiliary file, and since the serialised form would often be illegible on screen, it seems reasonable to call it a file input-output function just the same. The WRITE_FILE_KOVS should return true or false according to whether it was able to write the data.

Debugging.

Surprisingly, the above system of reference-counted double indirection didn't work first time, so it turned out to be useful to have these routines on hand.

Printing Memory Addresses.

The point of the anonymity flag is that, with this set, the output can be used as the required output in an Inform test case without tiny movements in memory between builds invalidating this required output.

Hexadecimal Printing.