4 Pointer Functions

If the values are both pointers that are not represented by #f, a byte string, a callback, a pointer based on _fpointer, or a structure with the prop:cpointer property, then the ptr-equal? comparison is the same as using equal?.

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.

4.1 Pointer Dereferencing

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 — so the actual address is the pointer plus the size of type multiplied by offset. In addition, a 'abs flag can be used to use the offset as counting bytes rather then increments of the specified type.

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.

4.2 Memory Management

For general information on C-level memory management with Racket, see Inside: Racket C API.

• 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.

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—even ones that have nothing to do with foreign code. Note, however, that the finalizer is registered for the Racket object that represents the pointer. If you intend to free a pointer object, then you must be careful to not register finalizers for two cpointers that point to the same address. Also, be careful to not make the finalizer a closure that holds on to the 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.)

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.