From 83a37aeca74724ef76dee7c8246bdbb88132940d Mon Sep 17 00:00:00 2001 From: Mike Pall Date: Mon, 28 Feb 2011 16:48:13 +0100 Subject: FFI: Add ffi.gc() function for finalization of cdata objects. --- doc/ext_ffi_api.html | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'doc/ext_ffi_api.html') diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html index b8c52fb6..5bd4b80c 100644 --- a/doc/ext_ffi_api.html +++ b/doc/ext_ffi_api.html @@ -238,6 +238,34 @@ This functions is mainly useful to override the pointer compatibility checks or to convert pointers to addresses or vice versa.

+

cdata = ffi.gc(cdata, finalizer)

+

+Associates a finalizer with a pointer or aggregate cdata object. The +cdata object is returned unchanged. +

+

+This function allows safe integration of unmanaged resources into the +automatic memory management of the LuaJIT garbage collector. Typical +usage: +

+
+local p = ffi.gc(ffi.C.malloc(n), ffi.C.free)
+...
+p = nil -- Last reference to p is gone.
+-- GC will eventually run finalizer: ffi.C.free(p)
+
+

+A cdata finalizer works like the __gc metamethod for userdata +objects: when the last reference to a cdata object is gone, the +associated finalizer is called with the cdata object as an argument. The +finalizer can be a Lua function or a cdata function or cdata function +pointer. An existing finalizer can be removed by setting a nil +finalizer, e.g. right before explicitly deleting a resource: +

+
+ffi.C.free(ffi.gc(p, nil)) -- Manually free the memory.
+
+

C Type Information

The following API functions return information about C types. -- cgit v1.2.3-55-g6feb