5.7 Allocation and Finalization

► |  | 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:

allocator
deallocator
releaser
retainer

Racket
top contents ← prev up next →

### 5.7 Allocation and Finalization🔗ℹ

(require ffi/unsafe/alloc) | package: base

The ffi/unsafe/alloc library provides utilities for ensuring that values allocated through foreign functions are reliably deallocated.

> > procedure
> > ((allocator |  | dealloc |
> > | [ | #:merely-uninterruptible? uninterruptible?]) |
> > alloc) |
> → (or/c procedure? #f)
> dealloc : (any/c . -> . any)
> uninterruptible? : any/c = #f
> alloc : (or/c procedure? #f)

Produces an allocator procedure that behaves like alloc, but each result v of the allocator, if not #f, is given a finalizer that calls dealloc on v—unless the call has been canceled by applying a deallocator (produced by deallocator) to v. Any existing dealloc registered for v is canceled. If and only if alloc is #f, ((allocator alloc) dealloc) produces #f.

The resulting allocator calls alloc in atomic mode (see call-as-atomic), unless uninterruptible? is true, in which case uninterruptible mode is used (see call-as-uninterruptible). The result from alloc is received and registered in atomic or uninterruptible mode, so that the result is reliably deallocated as long as no exception is raised.

The dealloc procedure will be called in atomic mode, and it must obey the same constraints as a finalizer procedure provided to register-finalizer. The dealloc procedure itself need not be specifically a deallocator produced by deallocator. If a deallocator is called explicitly, it need not be the same as dealloc.

When a non-main place exits, after all custodian-shutdown actions, for every dealloc still registered via an allocator or retainer (from allocator or retainer), the value to deallocate is treated as immediately unreachable. At that point, dealloc functions are called in reverse order of their registrations. Note that references in a dealloc function’s closure do not prevent running a dealloc function for any other value. If deallocation needs to proceed in an order different than reverse of allocation, use a retainer to insert a new deallocation action that will run earlier.

Changed in version 7.0.0.4 of package base: Added atomic mode for dealloc and changed non-main place exits to call all remaining deallocs.
Changed in version 7.4.0.4: Produce #f when alloc is #f.
Changed in version 8.17.0.7: Added the #:merely-uninterruptible? optional argument.

> > procedure
> > ((deallocator | [ | get-arg |
> > |  | #:merely-uninterruptible? uninterruptible?]) |
> > dealloc) |
> → procedure?
> get-arg : (list? . -> . any/c) = car
> uninterruptible? : any/c = #f
> dealloc : procedure?
> procedure ((releaser [get-arg]) dealloc) → procedure?
> get-arg : (list? . -> . any/c) = car
> dealloc : procedure?

Produces a deallocator procedure that behaves like dealloc. The deallocator calls dealloc in atomic mode (see call-as-atomic) or uninterruptible mode (see call-as-uninterruptible), and for one of its arguments, the it cancels the most recent remaining deallocator registered by a allocator or retainer.

The optional get-arg procedure determines which of dealloc’s arguments correspond to the released object; get-arg receives a list of arguments passed to dealloc, so the default car selects the first one. Note that get-arg can only choose one of the by-position arguments to dealloc, though the deallocator will require and accept the same keyword arguments as dealloc, if any.

The releaser procedure is a synonym for deallocator.

Changed in version 8.17.0.7 of package base: Added the #:merely-uninterruptible? optional argument.

> > procedure
> > ((retainer |  | release |
> > | [ | get-arg |
> > |  | #:merely-uninterruptible? uninterruptible?]) |
> > retain) |
> → procedure?
> release : (any/c . -> . any)
> get-arg : (list? . -> . any/c) = car
> uninterruptible? : any/c = #f
> retain : procedure?

Produces a retainer procedure that behaves like retain. A retainer acts the same as an allocator produced by allocator, except that

- a retainer does not cancel any existing release or dealloc registrations when registering release; and

- release is registered for a value v that is is an argument to the retainer, instead of the result for an allocator.

The optional get-arg procedure determines which of the retainer’s arguments (that is, which of retain’s arguments) correspond to the retained object v; get-arg receives a list of arguments passed to retain, so the default car selects the first one. Note that get-arg can only choose one of the by-position arguments to retain, though the retainer will require and accept the same keyword arguments as retain, if any.

Changed in version 7.0.0.4 of package base: Added atomic mode for release and changed non-main place exits to call all remaining releases.
Changed in version 8.17.0.7: Added the #:merely-uninterruptible? optional argument.

top contents ← prev up next →