108 lines
3.9 KiB
Racket
108 lines
3.9 KiB
Racket
#lang scribble/doc
|
|
@(require "utils.ss")
|
|
|
|
@title{Custodians}
|
|
|
|
When an extension allocates resources that must be explicitly freed
|
|
(in the same way that a port must be explicitly closed), a Scheme
|
|
object associated with the resource should be placed into the
|
|
management of the current custodian with @cppi{scheme_add_managed}.
|
|
|
|
Before allocating the resource, call
|
|
@cppi{scheme_custodian_check_available} to ensure that the relevant
|
|
custodian is not already shut down. If it is,
|
|
@cpp{scheme_custodian_check_available} will raise an exception. If
|
|
the custodian is shut down when @cpp{scheme_add_managed} is called,
|
|
the close function provided to @cpp{scheme_add_managed} will be called
|
|
immediately, and no exception will be reported.
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@function[(Scheme_Custodian* scheme_make_custodian
|
|
[Scheme_Custodian* m])]{
|
|
|
|
Creates a new custodian as a subordinate of @var{m}. If @var{m} is
|
|
@cpp{NULL}, then the main custodian is used as the new custodian's
|
|
supervisor. Do not use @cpp{NULL} for @var{m} unless you intend to
|
|
create an especially privileged custodian.}
|
|
|
|
@function[(Scheme_Custodian_Reference* scheme_add_managed
|
|
[Scheme_Custodian* m]
|
|
[Scheme_Object* o]
|
|
[Scheme_Close_Custodian_Client* f]
|
|
[void* data]
|
|
[int strong])]{
|
|
|
|
Places the value @var{o} into the management of the custodian
|
|
@var{m}. If @var{m} is @cpp{NULL}, the current custodian is used.
|
|
|
|
The @var{f} function is called by the custodian if it is ever asked to
|
|
``shutdown'' its values; @var{o} and @var{data} are passed on to
|
|
@var{f}, which has the type
|
|
|
|
@verbatim{
|
|
typedef void (*Scheme_Close_Custodian_Client)(Scheme_Object *o,
|
|
void *data);
|
|
}
|
|
|
|
If @var{strong} is non-zero, then the newly managed value will
|
|
be remembered until either the custodian shuts it down or
|
|
@cpp{scheme_remove_managed} is called. If @var{strong} is
|
|
zero, the value is allowed to be garbaged collected (and automatically
|
|
removed from the custodian).
|
|
|
|
Independent of whether @var{strong} is zero, the value @var{o} is
|
|
initially weakly held. A value associated with a custodian can
|
|
therefore be finalized via will executors.
|
|
|
|
The return value from @cpp{scheme_add_managed} can be used to refer
|
|
to the value's custodian later in a call to
|
|
@cpp{scheme_remove_managed}. A value can be registered with at
|
|
most one custodian.
|
|
|
|
If @var{m} (or the current custodian if @var{m} is @cpp{NULL})is shut
|
|
down, then @var{f} is called immediately, and the result is
|
|
@cpp{NULL}.}
|
|
|
|
@function[(void scheme_custodian_check_available
|
|
[Scheme_Custodian* m]
|
|
[const-char* name]
|
|
[const-char* resname])]{
|
|
|
|
Checks whether @var{m} is already shut down, and raises an error if
|
|
so. If @var{m} is @cpp{NULL}, the current custodian is used. The
|
|
@var{name} argument is used for error reporting. The @var{resname}
|
|
argument will likely be used for checking pre-set limits in the
|
|
future; pre-set limits will have symbolic names, and the
|
|
@var{resname} string will be compared to the symbols.}
|
|
|
|
@function[(void scheme_remove_managed
|
|
[Scheme_Custodian_Reference* mref]
|
|
[Scheme_Object* o])]{
|
|
|
|
Removes @var{o} from the management of its custodian. The @var{mref}
|
|
argument must be a value returned by @cpp{scheme_add_managed} or
|
|
@cpp{NULL}.}
|
|
|
|
@function[(void scheme_close_managed
|
|
[Scheme_Custodian* m])]{
|
|
|
|
Instructs the custodian @var{m} to shutdown all of its managed values.}
|
|
|
|
@function[(void scheme_add_atexit_closer
|
|
[Scheme_Exit_Closer_Func f])]{
|
|
|
|
Installs a function to be called on each custodian-registered item and
|
|
its closer when MzScheme is about to exit. The registered function
|
|
has the type
|
|
|
|
@verbatim[#:indent 2]{
|
|
typedef
|
|
void (*Scheme_Exit_Closer_Func)(Scheme_Object *o,
|
|
Scheme_Close_Custodian_Client *f,
|
|
void *d);
|
|
}
|
|
|
|
where @var{d} is the second argument for @var{f}.}
|
|
|