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
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
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:
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
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
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
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
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
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
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
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
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 ssss = 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
This is typically done automatically by the fetch function.
Example:
-- get the address from handle atom a, ha = 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
This is typically done automatically by the fetch function.
Example:
-- get a C-string from address sequence ss = 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
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
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
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
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
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
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
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
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
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
Example:
-- get length of a C-string from address integer lenlen = 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