5.15 Garbage Collection Callbacks

► |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

▼ | 5 | Derived Utilities

5.1 | Safe Homogenous Vectors
5.2 | Safe C Vectors
5.3 | Tagged C Pointer Types
5.4 | Serializable C Struct Types
5.5 | Static Callout and Callback Cores
5.6 | Defining Bindings
5.7 | Allocation and Finalization
5.8 | Custodian Shutdown Registration
5.9 | Atomic Execution
5.10 | Speculatively Atomic Execution
5.11 | Thread Scheduling
5.12 | Ports
5.13 | Process-Wide and Place-Wide Registration
5.14 | Operating System Threads
5.15 | Garbage Collection Callbacks
5.16 | Objective-C FFI
5.17 | Cocoa Foundation
5.18 | COM (Common Object Model)
5.19 | File Security-Guard Checks
5.20 | Windows API Helpers
5.21 | Virtual Machine Primitives

On this page:

unsafe-add-collect-callbacks
unsafe-remove-collect-callbacks

Racket
top contents ← prev up next →

### 5.15 Garbage Collection Callbacks🔗ℹ

(require ffi/unsafe/collect-callback) | package: base

The ffi/unsafe/collect-callback library provides functions to register constrained callbacks that are run just before and after a garbage collection.

Added in version 7.0.0.9 of package base.

> procedure (unsafe-add-collect-callbacks pre post) → any/c
> pre : (vectorof vector?)
> post : (vectorof vector?)

Registers descriptions of foreign functions to be called just before and just after a garbage collection. The foreign functions must not allocate garbage-collected memory, and they are called in a way that does not allocate, which is why pre_desc and post_desc are function descriptions instead of thunks.

A description is a vector of vectors, where each of the inner vectors describes a single call, and the calls are performed in sequence. Each call vector starts with a symbol that indicates the protocol of the foreign function to be called. The following protocols are supported: The apparently arbitrary and whimsical set of supported protocols is enough to allow DrRacket to show a garbage-collection icon.

- 'int->void corresponds to void (*)(int).

- 'ptr_ptr_ptr->void corresponds to void (*)(void*, void*, void*).

- 'ptr_ptr->save corresponds to void* (*)(void*, void*), but the result is recorded as the current “save” value. The current “save” value starts as NULL.

- 'save!_ptr->void corresponds to void (*)(void*, void*), but only if the current “save” value is not a NULL pointer, and passing that pointer as the function’s first argument (so that only one additional argument is us from the description vector).

- 'ptr_ptr_ptr_int->void corresponds to void (*)(void*, void*, void*, int).

- 'ptr_ptr_float->void corresponds to void (*)(void*, void*, float).

- 'ptr_ptr_double->void corresponds to void (*)(void*, void*, double).

- 'ptr_ptr_ptr_int_int_int_int_int_int_int_int_int->void corresponds to void (*)(void*, void*, void*, int, int, int, int, int, int, int, int, int).

- 'osapi_ptr_int->void corresponds to void (*)(void*, int), but using the stdcall calling convention on Windows.

- 'osapi_ptr_ptr->void corresponds to void (*)(void*, void*), but using the stdcall calling convention on Windows.

- 'osapi_ptr_int_int_int_int_ptr_int_int_long->void corresponds to void (*)(void*, int, int, int, int, void*, int, int, long), but using the stdcall calling convention on Windows.

After the protocol symbol, the vector should contain a pointer to a foreign function and then an element for each of the function’s arguments. Pointer values are represented as for the _pointer representation defined by ffi/unsafe.

The result is a key for use with unsafe-remove-collect-callbacks. If the key becomes inaccessible, then the callback will be removed automatically (but beware that the pre-callback will have executed and the post-callback will not have executed)

> procedure (unsafe-remove-collect-callbacks key) → void?
> key : any/c

Unregisters pre- and post-collection callbacks that were previously registered by a call to unsafe-add-collect-callbacks that returned v.
top contents ← prev up next →