September 21, 2023, 08:02:49 PM


IonicWind Snippit Manager 2.xx Released!  Install it on a memory stick and take it with you!  With or without IWBasic!

Undocumented internals

Started by Parker, March 27, 2006, 08:58:27 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.


One of the biggest things I didn't like when using IBasic was all the hidden stuff, like how PRINT worked, or what the HEAP type is for. So as a partner developer having access to it, I'm going to attempt to explain the undocumented parts of the language that are "reserved for internal use".

1) The HEAP type.
If you look in the includes in the bin directory (mainly the strings one), you'll find some functions that return the HEAP type. Here is an example function that returns the heap type:
global sub WTOCHAR(int num),heap
void *ret = AllocHeap( 4 );
// Num should equal 0000 char, since a little endian machine will translate this as
// (word)char, 0000.
%define num ebp+8
%define ret ebp-4

mov eax, [num]
and eax, 0xFFFF ; clear the top bits, what will be the last word
mov dword ebx, [ret] ; ebx contains ret, which contains the address of a heap.
mov dword [ebx], eax
%undef num
%undef ret
return ret;

it's a very small bit of assembly, and if you can read it you'll see that I operate on the HEAP return just as if it was a pointer (which it is declared as). Here is the aurora equivalent, for the assembly-challenged ;)
global sub WTOCHAR(int num),heap
void *ret = AllocHeap( 4 );
*(int)ret = num & 0xFFFF;
return ret;

Aurora has a few heap handling functions, the ones we're dealing with now are AllocHeap and FreeHeap. The AllocHeap functions very similarly to the NEW() operator on non-classes. It just allocates memory. So obviously FreeHeap cleans up the memory created by AllocHeap, and we can say (they have these on standardized tests) NEW : DELETE :: AllocHeap : FreeHeap.
Wait though... if that's correct then don't I need to call FreeHeap when I'm done? I thought you always had to free the memory.
That's true, and that's the purpose of the HEAP type. It was created for string usage, but it can be used for other things since it's just memory.

When a function returns the HEAP type, the compiler makes sure that when the function return is no longer used, FreeHeap is called on eax (the register where non-floating point returns are always stored).

More later... time to go.

Ionic Wind Support Team

The HEAP type is used for string and structure returns.  Just to clarify. 

And the average user doesn't need to worry about it since returning a structure is handled automatically, without needing to declare it as HEAP.  Also if your returning a fixed length string then the only advantage to using the HEAP type on return is one less copy operation internally, for speed that is.

Just returning a STRING type will automatically use the heap.  And for those that are wondering why it is because local variables don't exist when a function returns so the heap is a place to copy things to so they exist beyong the scope of a function.

There are some functions in acommon.lib that you should never use, such as PushHeap, PopHeap and HeapClear.  Trying to use any of those from native Aurora code will definately cause your program to bomb.  Which is why they were undocumented in IBasic as they have no use to anyone except the compiler itself.  And will be marked DO NOT USE in the documentation for Aurora.
Ionic Wind Support Team

Bruce Peaslee

That's too bad, as PopHeap has such a great ring to it.ÂÃ,  ;)
Bruce Peaslee
"Born too loose."
iTired (There's a nap for that.)
Well, I headed for Las Vegas
Only made it out to Needles