16.5 Phantom Byte Strings

► |  | The Racket Reference

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

▼ | 16 | Memory Management

16.1 | Weak Boxes
16.2 | Ephemerons
16.3 | Wills and Executors
16.4 | Garbage Collection
16.5 | Phantom Byte Strings

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