* ext/dl/cptr.c (rb_dlptr_s_malloc, rb_dlptr_initialize): adding

documentation
* test/dl/test_cptr.rb (**): testing that malloc works when passed free
  functions

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@25678 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ext/dl/cptr.c

@@ -123,6 +123,15 @@ rb_dlptr_s_allocate(VALUE klass)
     return obj;
 }
 
+/*
+ * call-seq:
+ *    DL::CPtr.new(address)                   => dl_cptr
+ *    DL::CPtr.new(address, size)             => dl_cptr
+ *    DL::CPtr.new(address, size, freefunc)   => dl_cptr
+ *
+ * Create a new pointer to +address+ with an optional +size+ and +freefunc+.
+ * +freefunc+ will be called when the instance is garbage collected.
+ */
 static VALUE
 rb_dlptr_initialize(int argc, VALUE argv[], VALUE self)
 {
@@ -163,6 +172,16 @@ rb_dlptr_initialize(int argc, VALUE argv[], VALUE self)
     return Qnil;
 }
 
+/*
+ * call-seq:
+ *
+ *    DL::CPtr.malloc(size, freefunc = nil)  => dl cptr instance
+ *
+ * Allocate +size+ bytes of memory and associate it with an optional
+ * +freefunc+ that will be called when the pointer is garbage collected.
+ * +freefunc+ must be an address pointing to a function or an instance of
+ * DL::CFunc
+ */
 static VALUE
 rb_dlptr_s_malloc(int argc, VALUE argv[], VALUE klass)
 {

test/dl/test_cptr.rb

@@ -3,6 +3,22 @@ require_relative '../ruby/envutil'
 
 module DL
   class TestCPtr < TestBase
+    def test_malloc_free_func_int
+      free = CFunc.new(@libc['free'], TYPE_VOID, 'free')
+
+      ptr  = CPtr.malloc(10, free.to_i)
+      assert_equal 10, ptr.size
+      assert_equal free.to_i, ptr.free.to_i
+    end
+
+    def test_malloc_free_func
+      free = CFunc.new(@libc['free'], TYPE_VOID, 'free')
+
+      ptr  = CPtr.malloc(10, free)
+      assert_equal 10, ptr.size
+      assert_equal free.to_i, ptr.free.to_i
+    end
+
     def test_to_str
       str = "hello world"
       ptr = CPtr[str]