Difference between revisions of "LlGetFreeMemory"

From Second Life Wiki
Jump to navigation Jump to search
Line 4: Line 4:
|return_type=integer
|return_type=integer
|func_desc
|func_desc
|return_text=that counts the bytes never yet used since reset in the free space of the task of the current script.
|return_text=that is the number of free bytes the Stack can use.
|spec
|func_footer
|spec=
The LSL memory space is divided into four sections: Byte-code, Stack, Free Memory, Heap. Free Memory isn't an allocated block of memory, it's just the space between Stack and Heap. The size of all four sections combined is 16384 bytes.
 
[[String]]s, [[list]]s and [[key]]s are stored in the Heap. Heap pointers (for [[string]]s, [[list]]s & [[key]]s), [[integer]]s, [[float]]s, [[vector]]s and [[rotation]]s are all temporarily stored in the stack as the script executes.
 
As the script executes the Stack grows and shrinks in size depending upon the complexity of the expressions being executed. Likewise the Heap grows as the script executes but unlike the stack, it never shrinks in size. When there is no free memory left for Stack or Heap to use they collide and a Stack-Heap Collision error is thrown causing the script to crash.
 
The Heap can become fragmented and blocks of memory in it can become unusable. There is no defragment function but there are techniques that can be used to reduce fragmentation.
|caveats=
|caveats=
*Does not return the count of free bytes (surprise!). Instead it returns the number of bytes never used.
*The number of free bytes the Heap can use may be greater but not less.
|constants
|constants
|examples=
|examples=
Line 56: Line 64:
<br/>
<br/>
We can concisely specify llGetFreeMemory in the context of the classic Unix model for a parallel task/ thread/ process. Think of the task of the script always holding 16384 bytes (16 KiB). Let the byte code and then stack grow up from the bottom, let the heap grow down from the top. llGetFreeMemory then returns the "historic lowest heap pointer minus the stack end pointer".<br/>
We can concisely specify llGetFreeMemory in the context of the classic Unix model for a parallel task/ thread/ process. Think of the task of the script always holding 16384 bytes (16 KiB). Let the byte code and then stack grow up from the bottom, let the heap grow down from the top. llGetFreeMemory then returns the "historic lowest heap pointer minus the stack end pointer".<br/>
<br/>
See the implications? llGetFreeMemory returns how many bytes of space were free, back when the heap was as large as the heap ever was, measured only since the last time when the script was reset. Mixing a partial history of the heap with the current state of the stack in this traditional Unix way can produce a positive or zero or negative return value, no matter how much freed memory the task now holds.<br/>
<br/>
<br/>
llGetFreeMemory does not count the bytes freed, llGetFreeMemory instead counts all the bytes never yet used.<br/>
llGetFreeMemory does not count the bytes freed, llGetFreeMemory instead counts all the bytes never yet used.<br/>
<br/>
<br/>
These facts astonish new people who have not yet learned to think of this function as if its name were llGetNeverYetUsedMemory. These facts continue to astonish people who feel some LSL function should free all memory that doesn't now need to be in use and then also count bytes of memory now freed.<br/>
See also: the "Script run-time error" "Stack-Heap Collision" among the [[LSL Errors]]<br/>
<br/>
See also: the "Script run-time error" "Stack-Heap Collision" among the [[LSL_Errors|LSL Errors]]<br/>
See also: [[Talk:LlGetFreeMemory]] for dispute of the theory that llGetFreeMemory may return negative numbers
See also: [[Talk:LlGetFreeMemory]] for dispute of the theory that llGetFreeMemory may return negative numbers
|permission
|negative_index
|cat1=Script
|cat1=Script
|cat2
|cat2

Revision as of 00:14, 18 September 2007

Summary

Function: integer llGetFreeMemory( );

Returns an integer that is the number of free bytes the Stack can use.

Specification

The LSL memory space is divided into four sections: Byte-code, Stack, Free Memory, Heap. Free Memory isn't an allocated block of memory, it's just the space between Stack and Heap. The size of all four sections combined is 16384 bytes.

Strings, lists and keys are stored in the Heap. Heap pointers (for strings, lists & keys), integers, floats, vectors and rotations are all temporarily stored in the stack as the script executes.

As the script executes the Stack grows and shrinks in size depending upon the complexity of the expressions being executed. Likewise the Heap grows as the script executes but unlike the stack, it never shrinks in size. When there is no free memory left for Stack or Heap to use they collide and a Stack-Heap Collision error is thrown causing the script to crash.

The Heap can become fragmented and blocks of memory in it can become unusable. There is no defragment function but there are techniques that can be used to reduce fragmentation.

Caveats

  • The number of free bytes the Heap can use may be greater but not less.
All Issues ~ Search JIRA for related Bugs

Examples

Calling llGetFreeMemory can look like this: 

integer Ki = 1024; // 1024 == (1 << 10);
float maxPerScript = 16 * Ki;
llOwnerSay((string) ((maxPerScript - llGetFreeMemory())/Ki) + " KiB of memory used once or more by this script since reset");
llOwnerSay((string) ((maxPerScript - llGetFreeMemory())/Ki) + " KiB of memory used once or more by this script since reset");

Chat showing that the heap grows over time after shrinking at reset can look like this: 

0.508789 KiB of memory used once or more by this script since reset
0.524414 KiB of memory used once or more by this script since reset

Shrinking the heap astonishingly does not reduce the value returned by llGetFreeMemory: 

default
{
    state_entry()
    {
        llSay(0,"llGetFreeMemory() returned: "+(string)llGetFreeMemory()+"byte(s)");
        //outputs what llGetFreeMemory() returns in bytes
        if(TRUE)
        {
            list TEST1;
            TEST1=[1,5334,"Blah, blah, blah",<345,3.78,34>,<0,0,0,1>,"TEST"];
            TEST1=TEST1+TEST1+llGetFreeMemory();
            integer i;
            for(i=0;i<llGetListLength(TEST1);i++)
            {
                llSay(0,"Item number "+(string)i+" in the list is: "+llList2String(TEST1,i));
            }
            TEST1 = [];
        }
        llSay(0,"List deleted!");
        llSay(0,"Now llGetFreeMemory returns: "+(string)llGetFreeMemory());
    }
} // http://wiki.secondlife.com/wiki/User:TxMasterG_Ping/llGetFreeMemory

Notes

This function does not count free memory, and the name of this function makes this function difficult for people to learn. People say this function may be redefined or superseded by another more useful function when the LSL VM moves to Mono.

We can concisely specify llGetFreeMemory in the context of the classic Unix model for a parallel task/ thread/ process. Think of the task of the script always holding 16384 bytes (16 KiB). Let the byte code and then stack grow up from the bottom, let the heap grow down from the top. llGetFreeMemory then returns the "historic lowest heap pointer minus the stack end pointer".

llGetFreeMemory does not count the bytes freed, llGetFreeMemory instead counts all the bytes never yet used.

See also: the "Script run-time error" "Stack-Heap Collision" among the LSL Errors
See also: Talk:LlGetFreeMemory for dispute of the theory that llGetFreeMemory may return negative numbers

Deep Notes

Search JIRA for related Issues

Signature

function integer llGetFreeMemory();
Retrieved from "https://wiki.secondlife.com/w/index.php?title=LlGetFreeMemory&oldid=31942"