📄 unit-lolevel.html
字号:
<html><head><title>CHICKEN User's Manual - Unit lolevel</title></head><body><p> </p><a name="unit-lolevel"></a><h1>Unit lolevel</h1><p>This unit provides a number of handy low-level operations. <strong>Use at your own risk.</strong></p><p>This unit uses the <tt>srfi-4</tt> and <tt>extras</tt> units.</p><a name="foreign-pointers"></a><h2>Foreign pointers</h2><a name="address-pointer"></a><h3>address→pointer</h3><pre>[procedure] (address->pointer ADDRESS)</pre><p>Creates a new foreign pointer object initialized to point to the address given in the integer <tt>ADDRESS</tt>.</p><a name="allocate"></a><h3>allocate</h3><pre>[procedure] (allocate BYTES)</pre><p>Returns a pointer to a freshly allocated region of static memory. This procedure could be defined as follows:</p><PRE>(<B><FONT COLOR="#A020F0">define</FONT></B> <B><FONT COLOR="#0000FF">allocate</FONT></B> (foreign-lambda c-pointer <B><FONT COLOR="#BC8F8F">"malloc"</FONT></B> integer))</PRE><a name="free"></a><h3>free</h3><pre>[procedure] (free POINTER)</pre><p>Frees the memory pointed to by <tt>POINTER</tt>. This procedure could be defined as follows:</p><PRE>(<B><FONT COLOR="#A020F0">define</FONT></B> <B><FONT COLOR="#0000FF">free</FONT></B> (foreign-lambda c-pointer <B><FONT COLOR="#BC8F8F">"free"</FONT></B> integer))</PRE><a name="null-pointer"></a><h3>null-pointer</h3><pre>[procedure] (null-pointer)</pre><p>Another way to say <tt>(address->pointer 0)</tt>.</p><a name="null-pointer"></a><h3>null-pointer?</h3><pre>[procedure] (null-pointer? PTR)</pre><p>Returns <tt>#t</tt> if <tt>PTR</tt> contains a <tt>NULL</tt> pointer, or <tt>#f</tt> otherwise.</p><a name="object-pointer"></a><h3>object→pointer</h3><pre>[procedure] (object->pointer X)</pre><p>Returns a pointer pointing to the Scheme object X, which should be a non-immediate object. Note that data in the garbage collected heap moves during garbage collection.</p><a name="pointer"></a><h3>pointer?</h3><pre>[procedure] (pointer? X)</pre><p>Returns <tt>#t</tt> if <tt>X</tt> is a foreign pointer object, and <tt>#f</tt> otherwise.</p><a name="pointer"></a><h3>pointer=?</h3><pre>[procedure] (pointer=? PTR1 PTR2)</pre><p>Returns <tt>#t</tt> if the pointer-like objects <tt>PTR1</tt> and <tt>PTR2</tt> point to the same address.</p><a name="pointer-address"></a><h3>pointer→address</h3><pre>[procedure] (pointer->address PTR)</pre><p>Returns the address, to which the pointer <tt>PTR</tt> points.</p><a name="pointer-object"></a><h3>pointer→object</h3><pre>[procedure] (pointer->object PTR)</pre><p>Returns the Scheme object pointed to by the pointer <tt>PTR</tt>.</p><a name="pointer-offset"></a><h3>pointer-offset</h3><pre>[procedure] (pointer-offset PTR N)</pre><p>Returns a new pointer representing the pointer <tt>PTR</tt> increased by <tt>N</tt>.</p><a name="pointer-u8-ref"></a><h3>pointer-u8-ref</h3><pre>[procedure] (pointer-u8-ref PTR)</pre><p>Returns the unsigned byte at the address designated by <tt>PTR</tt>.</p><a name="pointer-s8-ref"></a><h3>pointer-s8-ref</h3><pre>[procedure] (pointer-s8-ref PTR)</pre><p>Returns the signed byte at the address designated by <tt>PTR</tt>.</p><a name="pointer-u16-ref"></a><h3>pointer-u16-ref</h3><pre>[procedure] (pointer-u16-ref PTR)</pre><p>Returns the unsigned 16-bit integer at the address designated by <tt>PTR</tt>.</p><a name="pointer-s16-ref"></a><h3>pointer-s16-ref</h3><pre>[procedure] (pointer-s16-ref PTR)</pre><p>Returns the signed 16-bit integer at the address designated by <tt>PTR</tt>.</p><a name="pointer-u32-ref"></a><h3>pointer-u32-ref</h3><pre>[procedure] (pointer-u32-ref PTR)</pre><p>Returns the unsigned 32-bit integer at the address designated by <tt>PTR</tt>.</p><a name="pointer-s32-ref"></a><h3>pointer-s32-ref</h3><pre>[procedure] (pointer-s32-ref PTR)</pre><p>Returns the signed 32-bit integer at the address designated by <tt>PTR</tt>.</p><a name="pointer-f32-ref"></a><h3>pointer-f32-ref</h3><pre>[procedure] (pointer-f32-ref PTR)</pre><p>Returns the 32-bit float at the address designated by <tt>PTR</tt>.</p><a name="pointer-f64-ref"></a><h3>pointer-f64-ref</h3><pre>[procedure] (pointer-f64-ref PTR)</pre><p>Returns the 64-bit double at the address designated by <tt>PTR</tt>.</p><a name="pointer-u8-set"></a><h3>pointer-u8-set!</h3><pre>[procedure] (pointer-u8-set! PTR N)[procedure] (set! (pointer-u8-ref PTR) N)</pre><p>Stores the unsigned byte <tt>N</tt> at the address designated by <tt>PTR</tt>.</p><a name="pointer-s8-set"></a><h3>pointer-s8-set!</h3><pre>[procedure] (pointer-s8-set! PTR N)[procedure] (set! (pointer-s8-ref PTR) N)</pre><p>Stores the signed byte <tt>N</tt> at the address designated by <tt>PTR</tt>.</p><a name="pointer-u16-set"></a><h3>pointer-u16-set!</h3><pre>[procedure] (pointer-u16-set! PTR N)[procedure] (set! (pointer-u16-ref PTR) N)</pre><p>Stores the unsigned 16-bit integer <tt>N</tt> at the address designated by <tt>PTR</tt>.</p><a name="pointer-s16-set"></a><h3>pointer-s16-set!</h3><pre>[procedure] (pointer-s16-set! PTR N)[procedure] (set! (pointer-s16-ref PTR) N)</pre><p>Stores the signed 16-bit integer <tt>N</tt> at the address designated by <tt>PTR</tt>.</p><a name="pointer-u32-set"></a><h3>pointer-u32-set!</h3><pre>[procedure] (pointer-u32-set! PTR N)[procedure] (set! (pointer-u32-ref PTR) N)</pre><p>Stores the unsigned 32-bit integer <tt>N</tt> at the address designated by <tt>PTR</tt>.</p><a name="pointer-s32-set"></a><h3>pointer-s32-set!</h3><pre>[procedure] (pointer-s32-set! PTR N)[procedure] (set! (pointer-s32-ref PTR) N)</pre><p>Stores the 32-bit integer <tt>N</tt> at the address designated by <tt>PTR</tt>.</p><a name="pointer-f32-set"></a><h3>pointer-f32-set!</h3><pre>[procedure] (pointer-f32-set! PTR N)[procedure] (set! (pointer-f32-ref PTR) N)</pre><p>Stores the 32-bit floating-point number <tt>N</tt> at the address designated by <tt>PTR</tt>.</p><a name="pointer-f64-set"></a><h3>pointer-f64-set!</h3><pre>[procedure] (pointer-f64-set! PTR N)[procedure] (set! (pointer-f64-ref PTR) N)</pre><p>Stores the 64-bit floating-point number <tt>N</tt> at the address designated by <tt>PTR</tt>.</p><a name="align-to-word"></a><h3>align-to-word</h3><pre>[procedure] (align-to-word PTR-OR-INT)</pre><p>Accepts either a machine pointer or an integer as argument and returns a new pointer or integer aligned to the native word size of the host platform.</p><a name="tagged-pointers"></a><h2>Tagged pointers</h2><p><em>Tagged</em> pointers are foreign pointer objects with an extra tag object.</p><a name="tag-pointer"></a><h3>tag-pointer</h3><pre>[procedure] (tag-pointer PTR TAG)</pre><p>Creates a new tagged pointer object from the foreign pointer <tt>PTR</tt> with the tag <tt>TAG</tt>, which may an arbitrary Scheme object.</p><a name="tagged-pointer"></a><h3>tagged-pointer?</h3><pre>[procedure] (tagged-pointer? X TAG)</pre><p>Returns <tt>#t</tt>, if <tt>X</tt> is a tagged pointer object with the tag <tt>TAG</tt> (using an <tt>eq?</tt> comparison), or <tt>#f</tt> otherwise.</p><a name="pointer-tag"></a><h3>pointer-tag</h3><pre>[procedure] (pointer-tag PTR)</pre><p>If <tt>PTR</tt> is a tagged pointer object, its tag is returned. If <tt>PTR</tt> is a normal, untagged foreign pointer object <tt>#f</tt> is returned. Otherwise an error is signalled.</p><a name="extending-procedures-with-data"></a><h2>Extending procedures with data</h2><a name="extend-procedure"></a><h3>extend-procedure</h3><pre>[procedure] (extend-procedure PROCEDURE X)</pre><p>Returns a copy of the procedure <tt>PROCEDURE</tt> which contains an additional data slot initialized to <tt>X</tt>. If <tt>PROCEDURE</tt> is already an extended procedure, then its data slot is changed to contain <tt>X</tt> and the same procedure is returned.</p><a name="extended-procedure"></a><h3>extended-procedure?</h3><pre>[procedure] (extended-procedure? PROCEDURE)</pre><p>Returns <tt>#t</tt> if <tt>PROCEDURE</tt> is an extended procedure, or <tt>#f</tt> otherwise.</p><a name="procedure-data"></a><h3>procedure-data</h3><pre>[procedure] (procedure-data PROCEDURE)</pre><p>Returns the data object contained in the extended procedure <tt>PROCEDURE</tt>, or <tt>#f</tt> if it is not an extended procedure.</p><a name="set-procedure-data"></a><h3>set-procedure-data!</h3><pre>[procedure] (set-procedure-data! PROCEDURE X)</pre><p>Changes the data object contained in the extended procedure <tt>PROCEDURE</tt> to <tt>X</tt>.</p><PRE>(<B><FONT COLOR="#A020F0">define</FONT></B> <B><FONT COLOR="#0000FF">foo</FONT></B> (<B><FONT COLOR="#A020F0">letrec</FONT></B> ((f (<B><FONT COLOR="#A020F0">lambda</FONT></B> () (procedure-data x))) (x #f) ) (<B><FONT COLOR="#A020F0">set!</FONT></B> x (extend-procedure f 123)) x) )(foo) =<B><FONT COLOR="#A020F0">=></FONT></B> 123(set-procedure-data! foo 'hello)(foo) =<B><FONT COLOR="#A020F0">=></FONT></B> hello</PRE><a name="data-in-unmanaged-memory"></a><h2>Data in unmanaged memory</h2><a name="object-evict"></a><h3>object-evict</h3><pre>[procedure] (object-evict X [ALLOCATOR])</pre><p>Copies the object <tt>X</tt> recursively into the memory pointed to by the foreign pointer object returned by <tt>ALLOCATOR</tt>, which should be a procedure of a single argument (the number of bytes to allocate). The freshly copied object is returned. This facility allows moving arbitrary objects into static memory, but care should be taken when mutating evicted data: setting slots in evicted vector-like objects to non-evicted data is not allowed. It <strong>is</strong> possible to set characters/bytes in evicted strings or byte-vectors, though. It is advisable <strong>not</strong> to evict ports, because they might be mutated by certain file-operations. <tt>object-evict</tt> is able to handle circular and shared structures, but evicted symbols are no longer unique: a fresh copy of the symbol is created, so</p><PRE>(<B><FONT COLOR="#A020F0">define</FONT></B> <B><FONT COLOR="#0000FF">x</FONT></B> 'foo)(<B><FONT COLOR="#A020F0">define</FONT></B> <B><FONT COLOR="#0000FF">y</FONT></B> (object-evict 'foo))y =<B><FONT COLOR="#A020F0">=></FONT></B> foo(eq? x y) =<B><FONT COLOR="#A020F0">=></FONT></B> #f(<B><FONT COLOR="#A020F0">define</FONT></B> <B><FONT COLOR="#0000FF">z</FONT></B> (object-evict '(bar bar)))(eq? (car z) (cadr z)) =<B><FONT COLOR="#A020F0">=></FONT></B> #t</PRE><p>The <tt>ALLOCATOR</tt> defaults to <tt>allocate</tt>.</p><a name="object-evict-to-location"></a><h3>object-evict-to-location</h3><pre>[procedure] (object-evict-to-location X PTR [LIMIT])</pre><p>As <tt>object-evict</tt> but moves the object at the address pointed to by the machine pointer <tt>PTR</tt>. If the number of copied bytes exceeds the optional <tt>LIMIT</tt> then an error is signalled (specifically a composite condition of types <tt>exn</tt> and <tt>evict</tt>. The latter provides a <tt>limit</tt> property which holds the exceeded limit. Two values are returned: the evicted object and a new pointer pointing to the first free address after the evicted object.</p><a name="object-evicted"></a><h3>object-evicted?</h3><pre>[procedure] (object-evicted? X)</pre><p>Returns <tt>#t</tt> if <tt>X</tt> is a non-immediate evicted data object, or <tt>#f</tt> otherwise.</p><a name="object-size"></a><h3>object-size</h3><pre>[procedure] (object-size X)</pre><p>Returns the number of bytes that would be needed to evict the data object <tt>X</tt>.</p><a name="object-release"></a><h3>object-release</h3><pre>[procedure] (object-release X [RELEASER])</pre><p>Frees memory occupied by the evicted object <tt>X</tt> recursively. <tt>RELEASER</tt> should be a procedure of a single argument (a foreign pointer object to the static memory to be freed) and defaults to <tt>free</tt>.</p><a name="object-unevict"></a><h3>object-unevict</h3><pre>[procedure] (object-unevict X [FULL])</pre><p>Copies the object <tt>X</tt> and nested objects back into the normal Scheme heap. Symbols are re-interned into the symbol table. Strings and byte-vectors are <strong>not</strong> copied, unless <tt>FULL</tt> is given and not <tt>#f</tt>.</p><a name="locatives"></a><h2>Locatives</h2><p>A <em>locative</em> is an object that points to an element of a containing object, much like a <em>pointer</em> in low-level, imperative programming languages like <em>C</em>. The element can be accessed and changed indirectly, by performing access or change operations on the locative. The container object can be computed by calling the <tt>location->object</tt> procedure.</p><p>Locatives may be passed to foreign procedures that expect pointer arguments. The effect of creating locatives for evicted data (see <tt>object-evict</tt>) is undefined.</p><a name="make-locative"></a><h3>make-locative</h3><pre>[procedure] (make-locative EXP [INDEX])</pre><p>Creates a locative that refers to the element of the non-immediate object <tt>EXP</tt> at position <tt>INDEX</tt>. <tt>EXP</tt> may be a vector, pair, string, blob, SRFI-4 number-vector, or record. <tt>INDEX</tt> should be a fixnum. <tt>INDEX</tt> defaults to 0.</p><a name="make-weak-locative"></a><h3>make-weak-locative</h3><pre>[procedure] (make-weak-locative EXP [INDEX])</pre><p>Creates a <em>weak</em> locative. Even though the locative refers to an element of a container object, the container object will still be reclaimed by garbage collection if no other references to it exist.</p><a name="locative"></a><h3>locative?</h3><pre>[procedure] (locative? X)</pre><p>Returns <tt>#t</tt> if <tt>X</tt> is a locative, or <tt>#f</tt> otherwise.</p><a name="locative-ref"></a><h3>locative-ref</h3><pre>[procedure] (locative-ref LOC)</pre><p>Returns the element to which the locative <tt>LOC</tt> refers. If the containing object has been reclaimed by garbage collection, an error is signalled.</p><a name="locative-set"></a><h3>locative-set!</h3><pre>[procedure] (locative-set! LOC X)[procedure] (set! (locative-ref LOC) X)</pre><p>Changes the element to which the locative <tt>LOC</tt> refers to <tt>X</tt>. If the containing object has been reclaimed by garbage collection, an error is signalled.</p><a name="locative-object"></a><h3>locative→object</h3><pre>[procedure] (locative->object LOC)</pre><p>Returns the object that contains the element referred to by <tt>LOC</tt> or <tt>#f</tt> if the container has been reclaimed by garbage collection.</p><a name="accessing-toplevel-variables"></a><h2>Accessing toplevel variables</h2><a name="global-bound"></a><h3>global-bound?</h3><pre>[procedure] (global-bound? SYMBOL)</pre><p>Returns <tt>#t</tt>, if the global (<em>toplevel</em>) variable with the name <tt>SYMBOL</tt> is bound to a value, or <tt>#f</tt> otherwise.</p><a name="global-ref"></a><h3>global-ref</h3><pre>[procedure] (global-ref SYMBOL)</pre><p>Returns the value of the global variable <tt>SYMBOL</tt>. If no variable under that name is bound, an error is signalled.</p><p>Note that it is not possible to access a toplevel binding with <tt>global-ref</tt> or <tt>global-set!</tt> if it has been hidden in compiled code via <tt>(declare (hide ...))</tt>, or if the code has been compiled in <tt>block</tt> mode.</p><a name="global-set"></a><h3>global-set!</h3><pre>[procedure] (global-set! SYMBOL X)[procedure] (set! (global-ref SYMBOL) X)</pre><p>Sets the global variable named <tt>SYMBOL</tt> to the value <tt>X</tt>.</p><a name="low-level-data-access"></a><h2>Low-level data access</h2><a name="block-ref"></a><h3>block-ref</h3><pre>[procedure] (block-ref BLOCK INDEX)</pre><p>Returns the contents of the <tt>INDEX</tt>th slot of the object <tt>BLOCK</tt>. <tt>BLOCK</tt> may be a vector, record structure, pair or symbol.</p><a name="block-set"></a><h3>block-set!</h3><pre>[procedure] (block-set! BLOCK INDEX X)[procedure] (set! (block-ref BLOCK INDEX) X)</pre><p>Sets the contents of the <tt>INDEX</tt>th slot of the object <tt>BLOCK</tt> to the value of <tt>X</tt>. <tt>BLOCK</tt> may be a vector, record structure, pair or symbol.</p><a name="object-copy"></a><h3>object-copy</h3><pre>[procedure] (object-copy X)</pre><p>Copies <tt>X</tt> recursively and returns the fresh copy. Objects allocated in static memory are copied back into garbage collected storage.</p><a name="make-record-instance"></a><h3>make-record-instance</h3><pre>[procedure] (make-record-instance SYMBOL ARG1 ...)</pre><p>Returns a new instance of the record type <tt>SYMBOL</tt>, with its slots initialized to <tt>ARG1 ...</tt>. To illustrate:</p><PRE>(define-record point x y)</PRE><p>expands into something quite similar to:</p><PRE>(<B><FONT COLOR="#A020F0">begin</FONT></B>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -