Table of Contents

Memory Management routines

Low-Level Memory management routines


  • func acquire_mem( atom Owner, object structure )   Allocate memory for structure, and initialize to zero.
  • func address( structure address, field )    Get address of field in structure.
  • func allot( object FldDefn )   Allocate space in structure for a new field.
  • func allotted_handle(hDefn)   Returns the address of the supplied handle, but with fetch instructions
  • func allotted_size()   Return allocate size of structure, and reset for new structure.
  • func allotted_sofar()   Return size allotted sofar to the structure
  • func fetch( structure address, field )   Fetch field from structure.
  • func llSetAbort( i )   Sets the routine id of an Abort routine.
  • func llSetSafetyBuffer( integer bufsize )   Sets the number of extra bytes allocated as a safety buffer
  • func manage_mem( atom Owner, atom Address)   Records an acquired memory for garbage collection.
  • func new_memset( a )   Allocates a unique id for a memory set.
  • func peek_handle( handle )   Get address from a Handle.
  • func peek_string( address )   Get sequence from address holding C-style string.
  • proc release_all_mem()   Free all the acquired memory
  • proc release_mem( atom structure )    Returns the memory allocated by acquire_mem() back to the system.
  • func SafePeek(object addr)   This is an enhanced version of Euphoria's peek() function
  • func SafePeek4s(object addr)   This is an enhanced version of Euphoria's peek4s() function
  • func SafePeek4u(object addr)   This is an enhanced version of Euphoria's peek4u() function
  • func SafePoke(object addr)   This is an enhanced version of Euphoria's poke() function
  • func SafePoke4(object addr)   This is an enhanced version of Euphoria's poke4() function
  • proc store( structure, field, value )   Store a value into a structure.
  • Var UsingSafeCode   Determines whether or not the 'safe' versions of peek and poke are used.
  • func zStringLength( address )   Get the length of a C-style string.


    Table of Contents

    [func]
    acquire_mem
    ( atom Owner, object structure )

    Allocate memory for structure, and initialize to zero.

    Returns: Address of allocated memory.

    Category: Memory Management routines

    The memory allocated is linked to the Owner and all the owner's memory can be released by one call.
    If structure is a string, it is copied to the memory location along with a zero byte.

    If structure is an atom, it specifies that amount of memory to acquire (a minimum of 4 bytes will always be acquired) and the memory is set to all zeros.

    Example:

    atom mset, pt, pstr
    

    -- Establish a new memory set. mset = new_memset() -- get enough memory to hold a UInt datatype xy = acquire_mem( UInt ) -- allocate a point structure pt = acquire_mem( mset, SIZEOF_POINT ) -- copy a Euphoria string to a 'C' string area. pstr = acquire_mem( mset, "My String Data" ) . . . give all the memory area in 'mset' back release_mem(mset)

    See Also: address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    address
    ( structure address, field )

    Get address of field in structure.

    Returns: ATOM: Address of the field in the structure.

    Category: Memory Management routines

    This is typically used if the structure contains an array.

    In this snippet, the memBitmapInfo structure contains an array of RGBQUAD colors. The array is populated with the values in the pal:

    -- get the start of the rgbQuad array
    rgbQuad = address( memBitmapInfo, bmiColors )
    

    -- copy the pal to memory for i = 1 to colors do

    -- store values store( rgbQuad, rgbRed, pal[i][1] ) store( rgbQuad, rgbGreen, pal[i][2] ) store( rgbQuad, rgbBlue, pal[i][3] ) store( rgbQuad, rgbReserved, 0 )

    -- move to next quad rgbQuad += SIZEOF_RGBQUAD

    end for

    See Also: acquire_mem, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    allot
    ( object FldDefn )

    Allocate space in structure for a new field.

    Returns: SEQUENCE: Definition to allotted memory.

    Category: Memory Management routines

    FldDefn is either a number of bytes to allocate, one of the predefined datatypes (listed below), or a 2-element sequence containing a repeat count and a datatype or length.

    If a number of bytes is supplied, the field is aligned to the next 32-bit boundry before allocation.

    The returned allotment definition is used by store and fetch. It has the following structure.
    The definition has four items:
    An offset, a datatype, a repeat length, and a unit bytesize
    Allowable types are:

  • Byte: 8 bit value
  • Int8: Signed 8 bit integer, same as Byte.
  • Word: 16 bit value
  • Integer: 16 bit value, same as Word
  • Int16: 16 bit value, same as Word
  • Long: Signed 32 bit value
  • DWord: 32 bit value, same as Long
  • Int32: 32 bit value, same as Long
  • UInt: Unsigned 32 bit value.
  • Ptr: 32 bit value, same as UInt
  • ULong: 32 bit value, same as UInt
  • Hndl: 32 bit value, a pointer to a pointer
  • HndlAddr: 32 bit value,
  • Lpsz: Long pointer (32 bits) to zero delimited string
  • Strz: Fixed size buffer that holds a zero-delim string
  • Single: 32-bit IEEE floating point value
  • Float: Same as Single
  • Double: 64-bit IEEE floating point value

    Example:

    constant
    msLeft           = allot( Long ),
    msTop            = allot( Long ),
    msRight          = allot( Long ),
    msBottom         = allot( Long ),
    msVelocity       = allot( Single ),
    msXYZ            = allot( {4, DWord} ),
    msReserved       = allot( 5 ),
    msName           = allot( Lpsz ),
    msBuffer         = allot( {128, Strz} ),
     SIZEOF_MYSTRUCT  = allotted_size()
    

    See Also: acquire_mem, address, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    allotted_handle
    (hDefn)

    Returns the address of the supplied handle, but with fetch instructions

    Returns: SEQUENCE: Handle's "offset" into a structure.

    Category: Memory Management routines

    to get the address from the handle, rather than the handle itself.
    An empty sequence is returned if the parameter was invalid.

    Example:

    constant
     hDemo            = allot( Hndl ),
     pDemo            = allotted_handle( hDemo ),
     SIZEOF_DEMO      = allotted_size()
    . . .
    x = allocate_struct(SIZEOF_DEMO)
    initDEMO(x)
    

    h = fetch(x, hDemo) a = fetch(x, pDemo) -- 'h' will contain the handle, and 'a' the address from the handle.

    See Also: acquire_mem, address, allot, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    allotted_size
    ()

    Return allocate size of structure, and reset for new structure.

    Returns: INTEGER: Allotted size of structure.

    Category: Memory Management routines

    Example:

    constant
     rectLeft            = allot( Long ),
     rectTop             = allot( Long ),
     rectRight           = allot( Long ),
     rectBottom          = allot( Long ),
     SIZEOF_RECT        = allotted_size()
    

    See Also: acquire_mem, address, allot, allotted_handle, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    allotted_sofar
    ()

    Return size allotted sofar to the structure

    Returns: INTEGER: Allotted size of structure.

    Category: Memory Management routines

    Example:

    constant
     rectLeft            = allot( Long ),
     rectTop             = allot( Long ),
     SIZEOF_LT           = allotted_sofar()
     rectRight           = allot( Long ),
     rectBottom          = allot( Long ),
     SIZEOF_RECT        = allotted_size()
    

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    fetch
    ( structure address, field )

    Fetch field from structure.

    Returns: OBJECT: Field from a structure.

    Category: Memory Management routines

    Data conversion is automatic. For example, if the field is an Lpsz, a sequence containing the string will automatically be returned.

    Example:

    -- fetch the average character width from the text metrics structure
     width = fetch( tm, tmAveCharWidth )
    

    -- Here we get individual elements from an allot array. constant bCoords = allot( {4, Long} ) . . . x = fetch( rect, bCoords & 1) y = fetch( rect, bCoords & 2)

    -- To get all the values at once sequence coords coords = fetch( rect, bCoords)

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    llSetAbort
    ( i )

    Sets the routine id of an Abort routine.

    Returns: The previous value set.

    Category: Memory Management routines

    Used to indicate if an error routine needs to be called in the event of a catastophic error. The error routine is assumed to be a procedure that accepts a single sequence (typically an message string).

    Example:

    integer RtnID, OldID
    RtnID = routine_id("abortErr")
    OldID = llSetAbort(RtnID)
    

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    llSetSafetyBuffer
    ( integer bufsize )

    Sets the number of extra bytes allocated as a safety buffer

    Returns: Returns the current value of the buffer.

    Category: Memory Management routines

    This is primarily a debugging aid. If you suspect that memory overrun problems are happening, you can use this to test the idea.

    bufsize must be zero or more. A negative size does not change the current setting.
    The initial setting is 0 bytes. That is, there is no safety buffer.

    Example:

           -- Cause a 4-byte buffer to be added to all memory allocations.
           oldval = llSetSafetyBuffer( 4 )
    

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    manage_mem
    ( atom Owner, atom Address)

    Records an acquired memory for garbage collection.

    Category: Memory Management routines

    Normally this is handled automatically by acquire_mem() but if you are expected to manage some memory acquired by another means, such as a Windows call or a 'C' routine, you can use this to record the memory for subsequent release by release_mem().

    Example:

    atom mset, pt, pstr
    

    -- Establish a new memory set. mset = new_memset() -- calls a routine which returns a structure address. pt = c_func( xyz, {abc}) -- register this memory manage_mem(mset, pt) . . . give all the memory area in 'mset' back release_mem(mset)

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    new_memset
    ( a )

    Allocates a unique id for a memory set.

    Returns: ATOM: An id for a new memory set (memset).

    Category: Memory Management routines

    A memset id is actually a machine address of a 4-bytes location. You can use this 4-byte area for anything you like, until you call release_mem()

    Example:

          atom ss
    

    ss = new_memset() b = acquire_mem(ss, "All you need is love") ... release_mem( ss ) -- Let go of set 'ss'

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    peek_handle
    ( handle )

    Get address from a Handle.

    Returns: ATOM: address.

    Category: Memory Management routines

    This is typically done automatically by the fetch function.

    Example:

          -- get the address from handle
          atom a, h
    

    a = peek_handle( h )

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    peek_string
    ( address )

    Get sequence from address holding C-style string.

    Returns: SEQUENCE: containing the C-style string.

    Category: Memory Management routines

    This is typically done automatically by the fetch function.

    Example:

          -- get a C-string from address
          sequence s
    

    s = peek_string( address )

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [proc]
    release_all_mem
    ()

    Free all the acquired memory

    Category: Memory Management routines

    This gives back to the system, all the memory acquired by calling acquire_mem(). You must not use any previously acquired memory blocks after this has been called.

    NOTE: When using the Win32Lib library, it is not required to call this function as that is done automatically when WinMain() completes.

    WARNING: Calling this before WinMain() has ended will probably cause the the Win32Lib routines to crash.

    Example:

          -- Return all the memory areas
          release_all_mem()
    

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [proc]
    release_mem
    ( atom structure )

    Returns the memory allocated by acquire_mem() back to the system.

    Category: Memory Management routines

    If structure is a memory set id, as returned by new_memset(), then all the memory owned in the memory set is returned and the memory set id is released. That is, it cannot be reused.
    If structure is a memory address returned by acquire_mem(), then just that memory is released. The memory set it belonged to is still usable.

    Example:

    atom mset, pt, pstr
    

    -- Establish a new memory set. mset = new_memset() -- get enough memory to hold a UInt datatype xy = acquire_mem( UInt ) -- allocate a point structure pt = acquire_mem( mset, SIZEOF_POINT ) -- copy a Euphoria string to a 'C' string area. pstr = acquire_mem( mset, "My String Data" ) . . . give all the memory area in 'mset' back release_mem(mset)

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    SafePeek
    (object addr)

    This is an enhanced version of Euphoria's peek() function

    Returns: see peek() for details.

    Category: Memory Management routines

    If UsingSafeCode is not zero, this does a memory access check first.

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    SafePeek4s
    (object addr)

    This is an enhanced version of Euphoria's peek4s() function

    Returns: see peek4s() for details.

    Category: Memory Management routines

    If UsingSafeCode is not zero, this does a memory access check first.

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    SafePeek4u
    (object addr)

    This is an enhanced version of Euphoria's peek4u() function

    Returns: see peek4u() for details.

    Category: Memory Management routines

    If UsingSafeCode is not zero, this does a memory access check first.

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePoke, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    SafePoke
    (object addr)

    This is an enhanced version of Euphoria's poke() function

    Returns: see poke() for details.

    Category: Memory Management routines

    If UsingSafeCode is not zero, this does a memory access check first.

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke4, store, UsingSafeCode, zStringLength



    Table of Contents

    [func]
    SafePoke4
    (object addr)

    This is an enhanced version of Euphoria's poke4() function

    Returns: see poke4() for details.

    Category: Memory Management routines

    If UsingSafeCode is not zero, this does a memory access check first.

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, store, UsingSafeCode, zStringLength



    Table of Contents

    [proc]
    store
    ( structure, field, value )

    Store a value into a structure.

    Category: Memory Management routines

    Type conversion is automatic. For example, if an Lpsz field is used, the value is automatically converted from a sequence to a C-style string, and the address of that string is stored in the structure.

    Example:

          -- allocate RECT structure, and populate it
          atom rect
    

    -- allocate the structure rect = allocate_struct( SIZEOF_RECT )

    -- store values into the structure store( rect, rectLeft, x1 ) store( rect, rectTop, y1 ) store( rect, rectRight, x2 ) store( rect, rectBottom, y2 )

    -- Here we store individual elements to an allot array. constant bCoords = allot( {4, Long} ) . . . store( rect, bCoords & 1, Col) store( rect, bCoords & 2, Row)

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, UsingSafeCode, zStringLength



    Table of Contents

    [Var]
    UsingSafeCode

    Determines whether or not the 'safe' versions of peek and poke are used.

    Category: Memory Management routines

    This is primarily as debugging aid. You only need to set this if you suspect that your program is causing memory corruptions or accessing strange locations.

    Set this to zero to turn off the safe versions. Any other value causes the functions SafePeek(), SafePeek4s(), SafePeek4u(), SafePoke(), and SafePoke4() to perform memory access tests prior to fetching or changing memory.

    The initial setting is 0. That is, the safe versions are not being used.

    Example:

         --Ensure I can change RAM safely
         UsingSafeCode = 1
         SafePoke4( adr, 0)
    

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, zStringLength



    Table of Contents

    [func]
    zStringLength
    ( address )

    Get the length of a C-style string.

    Returns: INTEGER: The length of the string pointed to by address

    Category: Memory Management routines

    Example:

          -- get length of a C-string from address
          integer len
    

    len = zStringLength( address )

    See Also: acquire_mem, address, allot, allotted_handle, allotted_size, allotted_sofar, fetch, llSetAbort, llSetSafetyBuffer, manage_mem, new_memset, peek_handle, peek_string, release_all_mem, release_mem, SafePeek, SafePeek4s, SafePeek4u, SafePoke, SafePoke4, store, UsingSafeCode