GC Release Hooks
Resources a Script Opens
A library that opens something for a script, a client, a connection, a child process or a file handle, registers it with evaluator.TrackResource so it does not outlive the script’s use of it. The interpreter running the script then closes it on Reset(), ResetEnv() and Close(), and once the object the script holds is garbage collected:
func connect(ctx context.Context, url string) object.Object {
conn := dial(url)
inst := object.NewInstanceWithData(connClass, nil, conn)
conn.release = evaluator.TrackResource(ctx, inst, conn.Close)
return inst
}
// close() from the script: forget it, then close it.
func (c *Conn) Close() {
c.once.Do(func() {
c.release()
c.raw.Close()
})
}close must be safe to call more than once and from any goroutine, and neither it nor release may hold on to the object the script holds (inst), or that object could never be collected. Pass a nil owner to have only the interpreter close it.
GC Release Hooks
Scriptling exposes a small Go utility for attaching best-effort release hooks to heap objects:
target := &MyResource{}
err := object.SetGCReleaseHook(target, func() {
cleanupRemoteResource()
})
if err != nil {
return err
}Use object.ClearGCReleaseHook(target) when the resource has already been released explicitly:
releaseRemoteResource()
_ = object.ClearGCReleaseHook(target)Intended Use
GC release hooks are useful when a Go object owns a secondary resource and should send a cleanup signal if user code drops the object without calling an explicit release method.
Scriptling uses runtime.SetFinalizer in two places:
- All classes with
__del__(including pure Scriptling classes, Go builder classes, and plugin proxy objects): when an instance becomes unreachable, the finalizer calls__del__on it. - Plugin proxy objects: the finalizer also sends
object.destroyto the plugin server, which calls the server-side__del__to free plugin resources.
Limits
Go finalizers are not deterministic:
- They are not guaranteed to run promptly.
- They may not run before process exit.
- They must not be the only cleanup path for important resources.
- The hook must not capture the target object, or the object will remain reachable.
- The hook should avoid blocking work directly. Queue cleanup work elsewhere when cleanup may need IO, locks, or RPC.
- A script-defined
__del__collected by the finalizer runs with a five-second budget (past it the destructor is abandoned), under the environment’s interpreter lock (serialized against concurrent evaluation in that environment), and inside a panic boundary that contains failures without crashing the host.
Prefer explicit cleanup first, and use GC release hooks as a fallback.