73 lines
3.0 KiB
Racket
73 lines
3.0 KiB
Racket
#lang scribble/doc
|
|
@(require "utils.ss"
|
|
(for-label ffi/unsafe/alloc
|
|
ffi/unsafe/define
|
|
ffi/unsafe/atomic))
|
|
|
|
@title{Allocation and Finalization}
|
|
|
|
@defmodule[ffi/unsafe/alloc]{The
|
|
@schememodname[ffi/unsafe/alloc] library provides utilities for
|
|
ensuring that values allocated through foreign functions are reliably
|
|
deallocated.}
|
|
|
|
@defproc[((allocator [dealloc (any/c . -> . any)]) [alloc procedure?]) procedure?]{
|
|
|
|
Produces a procedure that behaves like @scheme[alloc], but the result
|
|
of @scheme[alloc] is given a finalizer that calls @scheme[dealloc] on
|
|
the result if it is not otherwise freed through a deallocator (as
|
|
designated with @scheme[deallocator]). In addition, @scheme[alloc] is
|
|
called in atomic mode (see @scheme[start-atomic]); its result is
|
|
received and registered in atomic mode, so that the result is reliably
|
|
freed.
|
|
|
|
The @scheme[dealloc] procedure itself need not be specifically
|
|
designated a deallocator (via @scheme[deallocator]). If a deallocator
|
|
is called explicitly, it need not be the same as @scheme[dealloc].}
|
|
|
|
@deftogether[(
|
|
@defproc[((deallocator [get-arg (list? . -> . any/c) car]) [dealloc procedure?])
|
|
procedure?]
|
|
@defproc[((releaser [get-arg (list? . -> . any/c) car]) [dealloc procedure?])
|
|
procedure?]
|
|
)]{
|
|
|
|
Produces a procedure that behaves like @scheme[dealloc]. The
|
|
@scheme[dealloc] procedure is called in atomic mode (see
|
|
@scheme[start-atomic]), and the reference count on one of its
|
|
arguments is decremented; if the reference count reaches zero, no
|
|
finalizer associated by an @scheme[allocator]- or
|
|
@scheme[referencer]-wrapped procedure is invoked when the value
|
|
becomes inaccessible.
|
|
|
|
The optional @scheme[get-arg] procedure determines which of
|
|
@scheme[dealloc]'s arguments correspond to the released object;
|
|
@scheme[get-arg] receives a list of arguments passed to
|
|
@scheme[dealloc], so the default @scheme[car] selects the first one.
|
|
|
|
The @scheme[releaser] procedure is a synonym for
|
|
@scheme[deallocator].}
|
|
|
|
|
|
@defproc[((retainer [release (any/c . -> . any)]
|
|
[get-arg (list? . -> . any/c) car])
|
|
[retain procedure?])
|
|
procedure?]{
|
|
|
|
Produces a procedure that behaves like @scheme[retain]. The procedure
|
|
is called in atomic mode (see @scheme[start-atomic]), and the
|
|
reference count on one of its arguments is incremented, with
|
|
@scheme[release] recorded as the corresponding release procedure to be
|
|
called by the finalizer on the retained object (unless some
|
|
deallocator, as wrapped by @scheme[deallocate], is explicitly called
|
|
first).
|
|
|
|
The optional @scheme[get-arg] procedure determines which of
|
|
@scheme[retain]'s arguments correspond to the retained object;
|
|
@scheme[get-arg] receives a list of arguments passed to
|
|
@scheme[retain], so the default @scheme[car] selects the first one.
|
|
|
|
The @scheme[release] procedure itself need not be specifically
|
|
designated a deallocator (via @scheme[deallocator]). If a deallocator
|
|
is called explicitly, it need not be the same as @scheme[release].}
|