► |  | The Racket Reference

1 | Language Model
2 | Syntactic Forms
3 | Datatypes
4 | Structures
5 | Classes and Objects
6 | Units
7 | Contracts
8 | Pattern Matching
9 | Control Flow
10 | Concurrency and Parallelism
11 | Macros
12 | Input and Output
13 | Reflection and Security
14 | Operating System
15 | Memory Management
16 | Unsafe Operations
17 | Running Racket
| Bibliography
| Index

▼ | 15 | Memory Management

15.1 | Weak Boxes
15.2 | Ephemerons
15.3 | Wills and Executors
15.4 | Garbage Collection
15.5 | Phantom Byte Strings

On this page:

phantom-bytes?
make-phantom-bytes
set-phantom-bytes!

top ← prev up next →

#### 15.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).

> > 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 →