memref

Function

Package: system

Arguments: object offset pos type &optional coerce

This function and memref-int provide low-level memory access in Allegro CL. However, even though their names are exported and they are documented, we recommend against using them in user code. Instead, we recommend using higher-level functions, such as those linked to below. However, the function are useful in the development cycle for debugging purposes.

Each function calculates an address in memory and performs a read from that address. The width and style of the read depends upon the type.

These functions are setf-able. The setf functions write to the addressed memory instead of reading. WARNING: except when the type is :lisp, these setf-functions do not do any setf-protection. If they are used to store non-lisp values into a memory location that was intended to hold a lisp value, then GC death will occur.

Some checking can be done. When the setf functions for sys:memref and memref-int are given an optional true fifth coerce argument, then runtime checking and coersion is done on the value before it is stored. This is especially useful when the argument is a float value, but of the wrong type, as in

(setf (sys:memref array 0 0 :double-float :coerce) 1.0s0)

Note that when this fifth argument is supplied, then the call is not open-coded when compiled.

object (the first argument of memref) can be any lisp object, whose address (including the tag bits) is used as the base for the memory access. address (the first argument of memref-int) can be any integer that represents a valid address in the lisp. The value of this address (which may be a bignum) is used as the base for the memory access.

offset and pos are equivalent and interchangeable. They are both added as byte-offsets to the base address to determine the final memory address. Usually, the offset is some constant that adjusts for the start of the data in the object being accessed. Some of the offsets for lisp objects are described in [Allegro directory]/misc/lisp.h in the Allegro CL distribution. In an earlier version of this documentation, it was stated that the offsets are available in Lisp itself by calling certain otherwise undocumented functions. That statement was incorrect. The offsets are not reliably available with Lisp.

The access-types that are available include:

:unsigned-byte
:signed-byte (1-byte access, 1-byte integer result)
:unsigned-word
:signed-word (2-byte access, 2-byte integer result)
:unsigned-long
:signed-long 
  ;; 4-byte access, 4-byte integer result in 32-bit lisps
  ;; undetermined (4-byte or 8-byte) in 64-bit lisps
:unsigned-long32 (4-byte access, 4-byte integer result)
:unsigned-long64 (8-byte access, 8-byte integer result on 64-bit
                  Lisps and Compaq Alpha and SGI32-bit Lisps
                  but 4-byte access, 4-byte integer result
                  on all others)
:fixnum (4-byte access, fixnum result [top bits lost on overflow])
:lisp (4-byte access, lisp result [careful, could confuse gc])
:single-float (or single-float) (4-byte access, 4-byte single-float result)  
:double-float (or double-float) (8-byte access, 8-byte double-float result)
:signed-natural 
:unsigned-natural
  ;; For these last two, in 32-bit lisps, these will 
  ;; construct 32-bit values, and in 64-bit lisps, it will construct 
  ;; 64-bit values
:nybble (4-bit -- half-byte -- value)

Be aware that though the access types might look similar to C types, they are not actually identical.

For more information on :signed-natural and :unsigned-natural, see 64 bit Allegro CL Implementations in implementation.htm.

In place of using memref and memref-int, operators like single-float-to-shorts, double-float-to-shorts, shorts-to-single-float, shorts-to-double-float may be used for accessing/creating floats. A foreign type can be defined (see ftype.htm). See also write-vector.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.