source: project/wiki/man/5/Module (chicken memory) @ 36755

Last change on this file since 36755 was 36755, checked in by kooda, 6 months ago

Fix a few links in man/5/Module (chicken memory)

File size: 10.2 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Module (chicken memory)
5
6The procedures from this module operate directly on memory, at a very
7low level.  This makes them unsafe, unlike most other Scheme
8procedures.  '''Use at your own risk.'''
9
10=== Foreign pointers
11
12The abstract class of ''pointer'' is divided into 2 categories:
13
14; ''pointer object'' : is a regular or [[#Tagged pointers|tagged]] foreign pointer object.
15
16; ''pointer-like object'' : is a closure, port, [[Module (chicken locative)|locative]], or a pointer object.
17
18Note that Locatives, while technically pointers, are not considered a ''pointer
19object'', but a ''pointer-like object''. The distinction is artificial.
20
21
22==== address->pointer
23
24<procedure>(address->pointer ADDRESS)</procedure>
25
26Creates a new foreign pointer object initialized to point to the address
27given in the integer {{ADDRESS}}.
28
29
30==== allocate
31
32<procedure>(allocate BYTES)</procedure>
33
34Returns a foreign pointer object to a freshly allocated region of static
35memory.
36
37This procedure could be defined as follows:
38
39<enscript highlight=scheme>
40(define allocate (foreign-lambda c-pointer "malloc" integer))
41</enscript>
42
43
44==== free
45
46<procedure>(free POINTER)</procedure>
47
48Frees the memory pointed to by {{POINTER}}.
49
50This procedure could be defined as follows:
51
52<enscript highlight=scheme>
53(define free (foreign-lambda void "free" c-pointer))
54</enscript>
55
56
57==== object->pointer
58
59<procedure>(object->pointer X)</procedure>
60
61Returns a foreign pointer object pointing to the Scheme object X, which should
62be a non-immediate object. ("foreign" here is a bit of a misnomer.)
63
64Note that data in the garbage collected heap moves during garbage collection.
65
66
67==== pointer->object
68
69<procedure>(pointer->object POINTER)</procedure>
70
71Returns the Scheme object pointed to by the pointer object {{POINTER}}.
72
73Whether the {{POINTER}} actually points to a Scheme object is not guaranteed. Use
74at your own risk.
75
76==== pointer?
77
78<procedure>(pointer? X)</procedure>
79
80Returns {{#t}} if {{X}} is a pointer object, or {{#f}} otherwise.
81
82
83==== pointer-like?
84
85<procedure>(pointer-like? X)</procedure>
86
87Returns {{#t}} if {{X}} is a pointer-like object, or {{#f}} otherwise.
88
89
90==== pointer=?
91
92<procedure>(pointer=? POINTER*1 POINTER*2)</procedure>
93
94Returns {{#t}} if the pointer-like objects {{POINTER*1}} and {{POINTER*2}} point
95to the same address, or {{#f}} otherwise.
96
97
98==== pointer->address
99
100<procedure>(pointer->address POINTER*)</procedure>
101
102Returns the address, to which the pointer-like object {{POINTER*}} points.
103
104
105==== pointer+
106
107<procedure>(pointer+ POINTER* N)</procedure>
108
109Returns a new foreign pointer object representing the pointer-like object
110{{POINTER*}} address value increased by the byte-offset {{N}}.
111
112Use of anything other than a pointer object as an argument is questionable.
113
114
115==== align-to-word
116
117<procedure>(align-to-word POINTER*-OR-INT)</procedure>
118
119Accepts either a pointer-like object or an integer as the argument and returns
120a new foreign pointer or integer aligned to the native word size of the host
121platform.
122
123Use of anything other than an integer or pointer object as an argument is
124questionable.
125
126
127=== SRFI-4 Foreign pointers
128
129These procedures actually accept a pointer-like object as the {{POINTER}} argument.
130However, as usual, use of anything other than a pointer object is questionable.
131
132
133==== pointer-u8-ref
134
135<procedure>(pointer-u8-ref POINTER)</procedure>
136
137Returns the unsigned byte at the address designated by {{POINTER}}.
138
139
140==== pointer-s8-ref
141
142<procedure>(pointer-s8-ref POINTER)</procedure>
143
144Returns the signed byte at the address designated by {{POINTER}}.
145
146
147==== pointer-u16-ref
148
149<procedure>(pointer-u16-ref POINTER)</procedure>
150
151Returns the unsigned 16-bit integer at the address designated by {{POINTER}}.
152
153
154==== pointer-s16-ref
155
156<procedure>(pointer-s16-ref POINTER)</procedure>
157
158Returns the signed 16-bit integer at the address designated by {{POINTER}}.
159
160
161==== pointer-u32-ref
162
163<procedure>(pointer-u32-ref POINTER)</procedure>
164
165Returns the unsigned 32-bit integer at the address designated by {{POINTER}}.
166
167
168==== pointer-s32-ref
169
170<procedure>(pointer-s32-ref POINTER)</procedure>
171
172Returns the signed 32-bit integer at the address designated by {{POINTER}}.
173
174==== pointer-u64-ref
175
176<procedure>(pointer-u64-ref POINTER)</procedure>
177
178Returns the unsigned 64-bit integer at the address designated by {{POINTER}}.
179
180
181==== pointer-s64-ref
182
183<procedure>(pointer-s64-ref POINTER)</procedure>
184
185Returns the signed 64-bit integer at the address designated by {{POINTER}}.
186
187
188==== pointer-f32-ref
189
190<procedure>(pointer-f32-ref POINTER)</procedure>
191
192Returns the 32-bit float at the address designated by {{POINTER}}.
193
194
195==== pointer-f64-ref
196
197<procedure>(pointer-f64-ref POINTER)</procedure>
198
199Returns the 64-bit double at the address designated by {{POINTER}}.
200
201
202==== pointer-u8-set!
203
204<procedure>(pointer-u8-set! POINTER N)</procedure><br>
205<procedure>(set! (pointer-u8-ref POINTER) N)</procedure>
206
207Stores the unsigned byte {{N}} at the address designated by {{POINTER}}.
208
209
210==== pointer-s8-set!
211
212<procedure>(pointer-s8-set! POINTER N)</procedure><br>
213<procedure>(set! (pointer-s8-ref POINTER) N)</procedure>
214
215Stores the signed byte {{N}} at the address designated by {{POINTER}}.
216
217
218==== pointer-u16-set!
219
220<procedure>(pointer-u16-set! POINTER N)</procedure><br>
221<procedure>(set! (pointer-u16-ref POINTER) N)</procedure>
222
223Stores the unsigned 16-bit integer {{N}} at the address designated by {{POINTER}}.
224
225
226==== pointer-s16-set!
227
228<procedure>(pointer-s16-set! POINTER N)</procedure><br>
229<procedure>(set! (pointer-s16-ref POINTER) N)</procedure>
230
231Stores the signed 16-bit integer {{N}} at the address designated by {{POINTER}}.
232
233
234==== pointer-u32-set!
235
236<procedure>(pointer-u32-set! POINTER N)</procedure><br>
237<procedure>(set! (pointer-u32-ref POINTER) N)</procedure>
238
239Stores the unsigned 32-bit integer {{N}} at the address designated by {{POINTER}}.
240
241
242==== pointer-s32-set!
243
244<procedure>(pointer-s32-set! POINTER N)</procedure><br>
245<procedure>(set! (pointer-s32-ref POINTER) N)</procedure>
246
247Stores the 32-bit integer {{N}} at the address designated by {{POINTER}}.
248
249
250==== pointer-u64-set!
251
252<procedure>(pointer-u64-set! POINTER N)</procedure><br>
253<procedure>(set! (pointer-u64-ref POINTER) N)</procedure>
254
255Stores the unsigned 64-bit integer {{N}} at the address designated by {{POINTER}}.
256
257
258==== pointer-s64-set!
259
260<procedure>(pointer-s64-set! POINTER N)</procedure><br>
261<procedure>(set! (pointer-s64-ref POINTER) N)</procedure>
262
263Stores the 64-bit integer {{N}} at the address designated by {{POINTER}}.
264
265
266==== pointer-f32-set!
267
268<procedure>(pointer-f32-set! POINTER N)</procedure><br>
269<procedure>(set! (pointer-f32-ref POINTER) N)</procedure>
270
271Stores the 32-bit floating-point number {{N}} at the address designated by {{POINTER}}.
272
273
274==== pointer-f64-set!
275
276<procedure>(pointer-f64-set! POINTER N)</procedure><br>
277<procedure>(set! (pointer-f64-ref POINTER) N)</procedure>
278
279Stores the 64-bit floating-point number {{N}} at the address designated by {{POINTER}}.
280
281
282
283=== Tagged pointers
284
285''Tagged'' pointers are foreign pointer objects with an extra tag object.
286
287
288==== tag-pointer
289
290<procedure>(tag-pointer POINTER* TAG)</procedure>
291
292Creates a new tagged foreign pointer object from the pointer-like object
293{{POINTER*}} with the tag {{TAG}}, which may an arbitrary Scheme object.
294
295Use of anything other than a pointer object is questionable.
296
297==== tagged-pointer?
298
299<procedure>(tagged-pointer? X [TAG])</procedure>
300
301Returns {{#t}} if {{X}} is a tagged foreign pointer object, or {{#f}} otherwise.
302
303Further, returns {{#t}} when {{X}} has the optional tag {{TAG}} (using an
304{{equal?}} comparison), or {{#f}} otherwise.
305
306
307==== pointer-tag
308
309<procedure>(pointer-tag POINTER*)</procedure>
310
311If {{POINTER}} is a tagged foreign pointer object, its tag is returned. If {{POINTER*}}
312is any other kind of pointer-like object {{#f}} is returned. Otherwise an
313error is signalled.
314
315
316=== Pointer vectors
317
318''Pointer vectors'' are specialized and space-efficient vectors for
319foreign pointer objects. All procedures defined below that accept
320a pointer object allow {{#f}} as an alternative representation of
321the {{NULL}}-pointer.
322
323
324==== make-pointer-vector
325
326<procedure>(make-pointer-vector LENGTH [INIT])</procedure>
327
328Creates a pointer-vector of the given length and optionally initializes each
329element to {{INIT}}, which should be a pointer or {{#f}}, which represents the
330{{NULL}} pointer.
331
332==== pointer-vector?
333
334<procedure>(pointer-vector? X)</procedure>
335
336Returns {{#t}} if {{X}} is a pointer-vector or {{#f}} otherwise.
337
338==== pointer-vector
339
340<procedure>(pointer-vector POINTER ...)</procedure>
341
342Returns a pointer-vector from the given pointer arguments.
343
344==== pointer-vector-length
345
346<procedure>(pointer-vector-length POINTERVECTOR)</procedure>
347
348Returns the length of the given pointer-vector.
349
350==== pointer-vector-ref
351
352<procedure>(pointer-vector-ref POINTERVECTOR INDEX)</procedure>
353
354Returns the pointer at {{INDEX}} in the given pointer-vector or
355{{#f}} if the element is a {{NULL}}- pointer.
356
357==== pointer-vector-set!
358
359<procedure>(pointer-vector-set! POINTERVECTOR INDEX POINTER)</procedure>
360
361Sets the element at the position {{INDEX}} in the given pointer-vector to
362{{POINTER}}. The alternative syntax
363
364  (set! (pointer-vector-ref POINTERVECTOR INDEX) POINTER)
365
366is also allowed.
367
368==== pointer-vector-fill!
369
370<procedure>(pointer-vector-fill! POINTERVECTOR POINTER)</procedure>
371
372Set every element in the {{POINTERVECTOR}} to {{POINTER}}.
373
374
375=== Moving memory
376
377==== move-memory!
378
379<procedure>(move-memory! FROM TO [BYTES [FROM-OFFSET [TO-OFFSET]]])</procedure>
380
381Copies {{BYTES}} bytes of memory from {{FROM}} to {{TO}}. {{FROM}} and {{TO}}
382may be strings, blobs, [[Module srfi-4|SRFI-4 number-vectors]], memory
383mapped files, foreign pointers (as obtained from a call to {{foreign-lambda}},
384for example), tagged-pointers or locatives. if {{BYTES}} is not given and the
385size of the source or destination operand is known then the maximal number of
386bytes will be copied. Moving memory to the storage returned by locatives will
387cause havoc, if the locative refers to containers of non-immediate data, like
388vectors or pairs.
389
390The additional fourth and fifth argument specify starting offsets (in bytes)
391for the source and destination arguments.
392
393Signals an error if any of the above constraints is violated.
394
395---
396Previous: [[Module (chicken locative)]]
397
398Next: [[Module (chicken memory representation)]]
Note: See TracBrowser for help on using the repository browser.