Documentation for Win32lib v0.60.6
Table of Contents

Memory management routines

Routines to allocate, use, and release of Random Access Memory (RAM).


Normally, a Euphoria program doesn't have to worry about this as it is handled quietly in the background. However, when working with external systems, such as the Windows API, the coder often needs to explicitly manage RAM as resource, primarily when sharing data between your application and Windows.

  • func w32acquire_mem( atom Owner, object structure )   Allocate memory for structure, and initialize to zero.
  • func w32address( structure address, field )    Get address of field in structure.
  • func w32allot( object FldDefn )   Allocate space in structure for a new field.
  • func w32allotted_handle(hDefn)   Returns the address of the supplied handle, but with fetch instructions
  • func w32allotted_size()   Return allocate size of structure, and reset for new structure.
  • func w32allotted_sofar()   Return size allotted sofar to the structure
  • proc w32ElemAddr( atom structure, sequence field )   Calculate the RAM address of a structure element.
  • func w32fetch( structure address, field )   Fetch field from structure.
  • func w32llSetAbort( i )   Sets the routine id of an Abort routine.
  • func w32manage_mem( atom Owner, atom Address)   Records an acquired memory for garbage collection.
  • func w32new_memset( )   Allocates a unique id for a memory set.
  • func w32peek_string( address )   Get sequence from address holding C-style string.
  • proc w32release_mem( atom structure )    Returns the memory allocated by w32acquire_mem() back to the system.
  • proc w32store( structure, field, value )   Store a value into a structure.
  • Var w32UsingSafeCode   Determines whether or not the 'safe' versions of peek and poke are used.

    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32acquire_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 = w32acquire_mem( UInt ) -- allocate a point structure pt = w32acquire_mem( mset, SIZEOF_POINT ) -- copy a Euphoria string to a 'C' string area. pstr = w32acquire_mem( mset, "My String Data" ) . . . give all the memory area in 'mset' back w32release_mem(mset)

    See Also: w32address, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32address
    ( 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 = w32address( memBitmapInfo, bmiColors )
    

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

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

    -- move to next quad rgbQuad += SIZEOF_RGBQUAD

    end for

    See Also: w32acquire_mem, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32allot
    ( 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           = w32allot( Long ),
    msTop            = w32allot( Long ),
    msRight          = w32allot( Long ),
    msBottom         = w32allot( Long ),
    msVelocity       = w32allot( Single ),
    msXYZ            = w32allot( {4, DWord} ),
    msReserved       = w32allot( 5 ),
    msName           = w32allot( Lpsz ),
    msBuffer         = w32allot( {128, Strz} ),
     SIZEOF_MYSTRUCT  = w32allotted_size()
    

    See Also: w32acquire_mem, w32address, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32allotted_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            = w32allot( Hndl ),
     pDemo            = w32allotted_handle( hDemo ),
     SIZEOF_DEMO      = w32allotted_size()
    . . .
    x = allocate_struct(SIZEOF_DEMO)
    initDEMO(x)
    

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

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32allotted_size
    ()

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

    Returns: INTEGER: Allotted size of structure.

    Category: Memory management routines

    Example:

    constant
     rectLeft            = w32allot( Long ),
     rectTop             = w32allot( Long ),
     rectRight           = w32allot( Long ),
     rectBottom          = w32allot( Long ),
     SIZEOF_RECT        = w32allotted_size()
    

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32allotted_sofar
    ()

    Return size allotted sofar to the structure

    Returns: INTEGER: Allotted size of structure.

    Category: Memory management routines

    Example:

    constant
     rectLeft            = w32allot( Long ),
     rectTop             = w32allot( Long ),
     SIZEOF_LT           = w32allotted_sofar()
     rectRight           = w32allot( Long ),
     rectBottom          = w32allot( Long ),
     SIZEOF_RECT        = w32allotted_size()
    

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_size, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    w32ElemAddr
    ( atom structure, sequence field )

    Calculate the RAM address of a structure element.

    Returns: ATOM: The RAM address of field within the struct

    Category: Memory management routines

    Example:

          atom Addr
          Addr = w32ElemAddr( lFR, FORMATRANGE_rcLeft )
    

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32fetch
    ( 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 = w32fetch( tm, tmAveCharWidth )
    

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

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

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32llSetAbort
    ( 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 = w32llSetAbort(RtnID)
    

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32manage_mem
    ( atom Owner, atom Address)

    Records an acquired memory for garbage collection.

    Category: Memory management routines

    Normally this is handled automatically by w32acquire_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 w32release_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 w32manage_mem(mset, pt) . . . give all the memory area in 'mset' back w32release_mem(mset)

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32new_memset, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32new_memset
    ( )

    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 w32release_mem()

    Example:

          atom ss
    

    ss = w32new_memset() b = w32acquire_mem(ss, "All you need is love") ... w32release_mem( ss ) -- Let go of set 'ss'

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32peek_string, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [func]
    w32peek_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 = w32peek_string( address )

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32release_mem, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    w32release_mem
    ( atom structure )

    Returns the memory allocated by w32acquire_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 w32acquire_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 = w32acquire_mem( UInt ) -- allocate a point structure pt = w32acquire_mem( mset, SIZEOF_POINT ) -- copy a Euphoria string to a 'C' string area. pstr = w32acquire_mem( mset, "My String Data" ) . . . give all the memory area in 'mset' back w32release_mem(mset)

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32store, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [proc]
    w32store
    ( 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 w32store( rect, rectLeft, x1 ) w32store( rect, rectTop, y1 ) w32store( rect, rectRight, x2 ) w32store( rect, rectBottom, y2 )

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

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32UsingSafeCode


    Documentation for Win32lib v0.60.6
    Table of Contents

    [Var]
    w32UsingSafeCode

    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..

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

    Example:

         --Ensure I can change RAM safely
         w32UsingSafeCode = 1
         l_SafePoke4( adr, 0)
    

    See Also: w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32ElemAddr, w32fetch, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32release_mem, w32store