4 Pointer Functions
procedure
(ptr-equal? cptr1 cptr2) → boolean?
cptr1 : cpointer? cptr2 : cpointer?
If the values are both pointers that are not represented by #f, a byte string, a callback, or a pointer based on _fpointer, then the ptr-equal? comparison is the same as using equal?.
procedure
cptr : cpointer? offset : exact-integer? type : ctype? = _byte
The resulting cpointer keeps the base pointer and offset separate. The two pieces are combined at the last minute before any operation on the pointer, such as supplying the pointer to a foreign function. In particular, the pointer and offset are not combined until after all allocation leading up to a foreign-function call; if the called function does not itself call anything that can trigger a garbage collection, it can safely use pointers that are offset into the middle of a GCable object.
procedure
(offset-ptr? cptr) → boolean?
cptr : cpointer?
procedure
(ptr-offset cptr) → exact-integer?
cptr : cpointer?
procedure
(cpointer-gcable? cptr) → boolean?
cptr : cpointer?
4.1 Pointer Dereferencing
procedure
(set-ptr-offset! cptr offset [ctype]) → void?
cptr : cpointer? offset : exact-integer? ctype : ctype? = _byte
procedure
cptr : cpointer? offset : exact-integer? ctype : ctype? = _byte
procedure
cptr : cpointer? type : ctype? offset : exact-nonnegative-integer? = 0 (ptr-ref cptr type abs-tag offset) → any cptr : cpointer? type : ctype? abs-tag : (one-of/c 'abs) offset : exact-nonnegative-integer? (ptr-set! cptr type val) → void? cptr : cpointer? type : ctype? val : any/c (ptr-set! cptr type offset val) → void? cptr : cpointer? type : ctype? offset : exact-nonnegative-integer? val : any/c (ptr-set! cptr type abs-tag offset val) → void? cptr : cpointer? type : ctype? abs-tag : (one-of/c 'abs) offset : exact-nonnegative-integer? val : any/c
In each case, offset defaults to 0 (which is the
only value that should be used with ffi-obj objects, see
Unexported Primitive Functions). If an offset index is
non-0, the value is read or stored at that location,
considering the pointer as a vector of types —
Beware that the ptr-ref and ptr-set! procedure do not keep any meta-information on how pointers are used. It is the programmer’s responsibility to use this facility only when appropriate. For example, on a little-endian machine:
> (define block (malloc _int 5)) > (ptr-set! block _int 0 196353) > (map (lambda (i) (ptr-ref block _byte i)) '(0 1 2 3)) (1 255 2 0)
In addition, ptr-ref and ptr-set! cannot detect when offsets are beyond an object’s memory bounds; out-of-bounds access can easily lead to a segmentation fault or memory corruption.
procedure
cptr : cpointer? src-cptr : cpointer? count : exact-nonnegative-integer? type : ctype? = _byte (memmove cptr offset src-cptr count [type]) → void? cptr : cpointer? offset : exact-integer? src-cptr : cpointer? count : exact-nonnegative-integer? type : ctype? = _byte
(memmove cptr offset src-cptr src-offset count [ type]) → void? cptr : cpointer? offset : exact-integer? src-cptr : cpointer? src-offset : exact-integer? count : exact-nonnegative-integer? type : ctype? = _byte
procedure
cptr : cpointer? src-cptr : cpointer? count : exact-nonnegative-integer? type : ctype? = _byte (memcpy cptr offset src-cptr count [type]) → void? cptr : cpointer? offset : exact-integer? src-cptr : cpointer? count : exact-nonnegative-integer? type : ctype? = _byte
(memcpy cptr offset src-cptr src-offset count [ type]) → void? cptr : cpointer? offset : exact-integer? src-cptr : cpointer? src-offset : exact-integer? count : exact-nonnegative-integer? type : ctype? = _byte
procedure
cptr : cpointer? byte : byte? count : exact-nonnegative-integer? type : ctype? = _byte (memset cptr offset byte count [type]) → void? cptr : cpointer? offset : exact-integer? byte : byte? count : exact-nonnegative-integer? type : ctype? = _byte
procedure
(cpointer-tag cptr) → any
cptr : cpointer?
procedure
(set-cpointer-tag! cptr tag) → void?
cptr : cpointer? tag : any/c
4.2 Memory Management
For general information on C-level memory management with Racket, see Inside: Racket C API.
procedure
(malloc bytes-or-type [ type-or-bytes cptr mode fail-mode]) → cpointer?
bytes-or-type :
(or/c (and/c exact-nonnegative-integer? fixnum?) ctype?)
type-or-bytes :
(or/c (and/c exact-nonnegative-integer? fixnum?) ctype?) = absent cptr : cpointer? = absent
mode :
(one-of/c 'nonatomic 'stubborn 'uncollectable 'eternal 'interior 'atomic-interior 'raw) = absent fail-mode : (one-of/c 'failok) = absent
If a C type bytes-or-type is given, its size is used to the block allocation size.
If an integer bytes-or-type is given, it specifies the required size in bytes.
If both bytes-or-type and type-or-bytes are given, then the allocated size is for a vector of values (the multiplication of the size of the C type and the integer).
If a cptr pointer is given, its content is copied to the new block.
A symbol mode argument can be given, which specifies what allocation function to use. It should be one of 'nonatomic (uses scheme_malloc from Racket’s C API), 'atomic (scheme_malloc_atomic), 'stubborn (scheme_malloc_stubborn), 'uncollectable (scheme_malloc_uncollectable), 'eternal (scheme_malloc_eternal), 'interior (scheme_malloc_allow_interior), 'atomic-interior (scheme_malloc_atomic_allow_interior), or 'raw (uses the operating system’s malloc, creating a GC-invisible block).
If an additional 'failok flag is given, then scheme_malloc_fail_ok is used to wrap the call.
If no mode is specified, then 'nonatomic allocation is used when the type is a _gcpointer- or _scheme-based type, and 'atomic allocation is used otherwise.
procedure
(end-stubborn-change cptr) → void?
cptr : cpointer?
procedure
v : any/c
procedure
(free-immobile-cell cptr) → void?
cptr : cpointer?
The finalizer is invoked in a thread that is in charge of triggering will executors for register-finalizer. The given finalizer procedure should generally not rely on the environment of the triggering thread, such as its output ports or custodians, except that relying on a default logger is reasonable.
Finalizers are mostly intended to be used with cpointer objects (for
freeing unused memory that is not under GC control), but it can be
used with any Racket object—
For example, suppose that you’re dealing with a foreign function that returns a C string that you should free. Here is an attempt at creating a suitable type:
(define _sixteen-bytes/free (make-ctype _pointer #f ; a Racket bytes can be used as a pointer (lambda (x) (let ([b (make-sized-byte-string x 16)]) (register-finalizer x free) b))))
The above code is wrong: the finalizer is registered for x, which is no longer needed after the byte string is created. Changing the example to register the finalizer for b correct the problem, but then free is invoked b it instead of on x. In the process of fixing this problem, we might be careful and log a message for debugging:
(define _sixteen-bytes/free (make-ctype _pointer #f ; a Racket bytes can be used as a pointer (lambda (x) (let ([b (make-sized-byte-string x 16)]) (register-finalizer b (lambda (ignored) (log-debug (format "Releasing ~s\n" b)) (free x))) b))))
Now, we never see any logged event. The problem is that the finalizer is a closure that keeps a reference to b. Instead of referencing the value that is finalized, use the input argument to the finalizer; simply changing ignored to b above solves the problem. (Removing the debugging message also avoids the problem, since the finalization procedure would then not close over b.)
procedure
(make-sized-byte-string cptr length) → bytes?
cptr : cpointer? length : exact-nonnegative-integer?
If cptr is an offset pointer created by ptr-add, the offset is immediately added to the pointer. Thus, this function cannot be used with ptr-add to create a substring of a Racket byte string, because the offset pointer would be to the middle of a collectable object (which is not allowed).
4.3 Pointer Structure Property
The prop:cpointer property allows a structure instance to be used transparently as a C pointer value, or it allows a C pointer value to be transparently wrapped by a structure that may have additional values or properties.