source: project/release/4/object-evict/object-evict.wiki @ 31138

Last change on this file since 31138 was 31138, checked in by felix winkelmann, 6 years ago

added preliminary eggs for extraction from core libraries

File size: 5.0 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== object-evict
5
6
7=== Introduction
8
9
10This extension allows to copy arbitrary Scheme data into unmanaged
11memory, not subject to garbage collection (called /eviction/). This
12may be useful for "pinning" down data to be used by foreign code.
13
14Note that the evicted data needs to be released manually.
15
16
17=== Requirements
18
19[[srfi-69]]
20
21
22=== Usage
23
24{{(require-extension objectg-evict)}}
25
26
27=== Programming interface
28
29==== object-evict
30
31<procedure>(object-evict X [ALLOCATOR])</procedure>
32
33Copies the object {{X}} recursively into the memory pointed to by the foreign
34pointer object returned by {{ALLOCATOR}}.  The freshly copied object is
35returned.  {{ALLOCATOR}} should be a procedure of a single argument
36(the number of bytes to allocate), and defaults to {{allocate}}.
37
38This facility allows moving arbitrary objects into static memory, but care
39should be taken when mutating evicted data: setting slots in evicted
40vector-like objects to non-evicted data is not allowed. It '''is''' possible to
41set characters/bytes in evicted strings or byte-vectors, though.  It is
42advisable '''not''' to evict ports, because they might be mutated by certain
43file-operations.  {{object-evict}} is able to handle circular and shared
44structures.
45
46Evicted symbols are no longer unique: a fresh copy of the
47symbol is created, so
48
49<enscript highlight=scheme>
50(define x 'foo)
51(define y (object-evict 'foo))
52y                              ==> foo
53(eq? x y)                      ==> #f
54(define z (object-evict '(bar bar)))
55(eq? (car z) (cadr z))         ==> #t
56</enscript>
57
58This loss of uniqueness also implies that an evicted structure --
59such as one created with {{define-record}} -- cannot be operated on with
60the existing predicate or accessors, as internally a symbol is used to
61denote the type:
62
63<enscript highlight=scheme>
64(define-record point x y)
65(point? (make-point x y))                  ; => #t
66(point? (object-evict (make-point x y)))   ; => #f
67</enscript>
68
69==== object-evict-to-location
70
71<procedure>(object-evict-to-location X POINTER* [LIMIT])</procedure>
72
73As {{object-evict}} but moves the object at the address pointed to by
74the pointer-like object {{POINTER*}}. If the number of copied bytes exceeds
75the optional {{LIMIT}} then an error is signalled (specifically a composite
76condition of types {{exn}} and {{evict}}. The latter provides
77a {{limit}} property which holds the exceeded limit. Two values are
78returned: the evicted object and a new pointer pointing to the first
79free address after the evicted object.
80
81Use of anything other than a pointer object as the {{POINTER*}} argument is
82questionable.
83
84==== object-evicted?
85
86<procedure>(object-evicted? X)</procedure>
87
88Returns {{#t}} if {{X}} is a non-immediate evicted data object, or {{#f}}
89otherwise.
90
91
92==== object-release
93
94<procedure>(object-release X [RELEASER])</procedure>
95
96Frees memory occupied by the evicted object {{X}} recursively.
97{{RELEASER}} should be a procedure of a single argument (a foreign
98pointer object to the static memory to be freed) and defaults to
99{{free}}.
100
101
102==== object-unevict
103
104<procedure>(object-unevict X [FULL])</procedure>
105
106Copies the object {{X}} and nested objects back into the normal Scheme heap.
107Symbols are re-interned into the symbol table. Strings and byte-vectors are
108'''not''' copied, unless {{FULL}} is given and not {{#f}}.
109
110
111==== object-size
112
113<procedure>(object-size X)</procedure>
114
115Returns the number of bytes that would be needed to evict the data object
116{{X}}. If {{X}} is an immediate object, zero is returned.
117
118
119
120=== Author
121
122The CHICKEN Team
123
124
125=== License
126
127 Copyright (c) 2014, The CHICKEN Team
128 All rights reserved.
129 
130 Redistribution and use in source and binary forms, with or without
131 modification, are permitted provided that the following conditions
132 are met:
133 1. Redistributions of source code must retain the above copyright
134    notice, this list of conditions and the following disclaimer.
135 2. Redistributions in binary form must reproduce the above copyright
136    notice, this list of conditions and the following disclaimer in the
137    documentation and/or other materials provided with the distribution.
138 3. The name of the authors may not be used to endorse or promote products
139    derived from this software without specific prior written permission.
140 
141 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
142 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
143 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
144 IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
145 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
146 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
147 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
148 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
149 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
150 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
151 
152
153=== Version History
154
155; 1.0 : Extracted from {{lolevel}} core library unit and released as an egg.
Note: See TracBrowser for help on using the repository browser.