►The Racket Reference
▼16 Memory Management
On this page:
phantom-bytes?
make-phantom-bytes
set-phantom-bytes!
  top  ← prev  up  next → 

16.5 Phantom Byte Strings

A phantom byte string is a small Racket value that is treated by the Racket memory manager as having an arbitrary size, which is specified when the phantom byte string is created or when it is changed via set-phantom-bytes!.

A phantom byte string acts as a hint to Racket’s memory manager that memory is allocated within the process but through a separate allocator, such as through a foreign library that is accessed via ffi/unsafe. This hint is used to trigger garbage collections or to compute the result of current-memory-use.

procedure

(phantom-bytes? v) → boolean?

  v : any/c
Returns #t if v is a phantom byte string, #f otherwise.

procedure

(make-phantom-bytes k) → phantom-bytes?

  k : exact-nonnegative-integer?
Creates a phantom byte string that is treated by the Racket memory manager as being k bytes in size. For a large enough k, the exn:fail:out-of-memory exception is raised—either because the size is implausibly large, or because a memory limit has been installed with custodian-limit-memory.

procedure

(set-phantom-bytes! phantom-bstr k) → phantom-bytes?

  phantom-bstr : phantom-bytes?
  k : exact-nonnegative-integer?
Adjusts the size of a phantom byte string as it is treated by the Racket memory manager.

For example, if the memory that phantom-bstr represents is released through a foreign library, then (set-phantom-bytes! phantom-bstr 0) can reflect the change in memory use.

When k is larger than the current size of phantom-bstr, then this function can raise exn:fail:out-of-memory, like make-phantom-bytes.

  top  ← prev  up  next →