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. Currently, the hint is used only in Racket 3m (the main variant of Racket).

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.