free 0.1.2 → 0.2.0pre1

data/HISTORY

@@ -1,2 +1,10 @@
+4/1/2011 version 0.2.0
+* added destructors
+* added greater error checking
+
+3/1/2011 version 0.1.2
+* added 1.8 and 1.9 support
+* now compiles on linux 
+
 2/1/2011 version 0.1.0
 * first release

data/README.md

@@ -9,16 +9,17 @@ free provides the `Object#free` method enabling a user to garbage
 collect an object on demand and free all its internal structures.
 
 * Install the [gem](https://rubygems.org/gems/free)
-* Read the [documentation](http://rdoc.info/github/banister/free/master/file/README.markdown)
+* Read the [documentation](http://rdoc.info/github/banister/free/master/file/README.md)
 * See the [source code](http://github.com/banister/free)
 
-Example: 
---------
+Example: Freeing a String
+-------------------------
 
 Let's free a String:
 
     hello = "hello world"
     id = hello.object_id
+
     hello.free
 
     # Note we go through the id as accessing the freed object directly
@@ -26,20 +27,36 @@ Let's free a String:
     ObjectSpace._id2ref(id) #=> RangeError: _id2ref': 0x1c1a63c is recycled object 
 
 
+Example: Destructors
+--------------------
+
+Free also supports object destructors. If the `__destruct__` method is
+implemented on the object being freed it will be called before freeing
+takes place; and the return value of `free` will be the return value of `__destruct__`:
+
+    o = Object.new
+    def o.__destruct__
+      :killed
+    end
+
+    o.free #=> :killed
+
 Features and limitations
 -------------------------
 
 ### Features
 
-* Can free any object (except immediate values, that do not need
-  freeing)
-* Works in both Ruby 1.8 and 1.9, MRI and YARV only.
+* Can free any object (but be careful, see below)
+* Works in both Ruby 1.8 and 1.9.
+* Some protection from freeing critical objects and immediate values.
+* Supports object destructors
 
 ### Limitations
 
 * Beta software, beware.
-* Can be dangerous - `free` will force garbage collection on an object
-  even if references to it still exist. Trying to access an already freed object may result in unexpected behaviour or segfaults.
+* Supports MRI and YARV only.
+* Not complete protection from freeing silly things, e.g core classes. Be sensible :)
+* Can be dangerous - `free` will force garbage collection on an object even if references to it still exist. Trying to access an already freed object may result in unexpected behaviour or segfaults.
   
 Contact
 -------

data/ext/free/free.c

@@ -46,10 +46,6 @@ typedef struct RVALUE {
     struct SCOPE   scope;
 #endif
   } as;
-#ifdef GC_DEBUG
-  const char *file;
-  int   line;
-#endif
 } RVALUE;
 
 #define RANY(o) ((RVALUE*)(o))
@@ -97,16 +93,55 @@ make_deferred(RVALUE *p)
 
 VALUE object_free(VALUE obj)
 {
-#ifdef RUBY_19
-  switch (BUILTIN_TYPE(obj)) {
+  ID id_destructor = rb_intern("__destruct__");
+
+  /* value returned by destructor */
+  VALUE destruct_value = Qnil;
+  
+  /* prevent freeing of immediates */
+  switch (TYPE(obj)) {
   case T_NIL:
   case T_FIXNUM:
   case T_TRUE:
   case T_FALSE:
-    rb_bug("obj_free() called for broken object");
+  case T_SYMBOL:
+    rb_raise(rb_eTypeError, "obj_free() called for immediate value");
     break;
   }
 
+  /* prevent freeing of *some* critical objects */
+  if ((obj == rb_cObject) ||
+      (obj == rb_cClass) ||
+      (obj == rb_cModule) ||
+      (obj == rb_cSymbol) ||
+      (obj == rb_cFixnum) ||
+      (obj == rb_cFloat) ||
+      (obj == rb_cString) ||
+      (obj == rb_cRegexp) ||
+      (obj == rb_cInteger) ||
+      (obj == rb_cArray) ||
+      (obj == rb_cNilClass) ||
+      (obj == rb_cFalseClass) ||
+      (obj == rb_cTrueClass) ||
+      (obj == rb_cNumeric) ||
+      (obj == rb_cBignum) ||
+      (obj == rb_cStruct)) 
+    rb_raise(rb_eTypeError, "obj_free() called for critical object");
+   
+  /* run destructor (if one is defined) */
+  if (rb_respond_to(obj, id_destructor))
+    destruct_value = rb_funcall(obj, id_destructor, 0);
+
+#ifdef RUBY_19
+      switch (BUILTIN_TYPE(obj)) {
+      case T_NIL:
+      case T_FIXNUM:
+      case T_TRUE:
+      case T_FALSE:
+        rb_bug("obj_free() called for broken object");
+        break;
+      }
+
   if (FL_TEST(obj, FL_EXIVAR)) {
     rb_free_generic_ivar((VALUE)obj);
     FL_UNSET(obj, FL_EXIVAR);
@@ -346,7 +381,7 @@ VALUE object_free(VALUE obj)
 
   rb_gc_force_recycle(obj);
 
-  return Qnil;
+  return destruct_value;
 }
 
 void

data/lib/free.rb

@@ -9,10 +9,15 @@ require "#{direc}/free/version"
 module Free
 
   # Force garbage collection on an object and free its internal structures.
-  # @return nil
+  # @return [nil, Object] Return value of \_\_destruct\_\_ method (if
+  #   defined) or nil (if no \_\_destruct\_\_ method)
   # @example
   #   h = "hello"
-  #   h.free
+  #   def h.__destruct__
+  #     :killed
+  #   end
+  #   
+  #   h.free #=> :killed
   def free() end
 end
 

data/lib/free/version.rb

@@ -1,3 +1,3 @@
 module Free
-  VERSION = "0.1.2"
+  VERSION = "0.2.0pre1"
 end     

data/test/test.rb

@@ -32,4 +32,33 @@ describe Free do
       (ObjectSpace._id2ref(id)  != v || lambda { ObjectSpace._id2ref(id) } rescue true).should == true
     end
   end
+
+  it 'should run destructor before freeing object' do
+    o = Object.new
+    
+    def o.__destruct__
+      :killed
+    end
+
+    o.free.should == :killed
+  end
+
+  it 'should return nil if no destructor specified' do
+    o = Object.new
+    o.free.should == nil
+  end
+
+  it 'should raise when trying to free immediate values' do
+    [nil, 0, true, false, :symbol].each do |v|
+      lambda { v.free }.should.raise TypeError
+    end
+  end
+
+  it 'should raise when trying to free critical objects' do
+    [Object, Class, Module, Symbol, Fixnum, Float,
+     String, Regexp, Integer, Array, NilClass, FalseClass,
+     TrueClass, Numeric, Bignum, Struct].each do |v|
+      lambda { v.free }.should.raise TypeError
+    end
+  end
 end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: free
 version: !ruby/object:Gem::Version 
-  hash: 31
-  prerelease: false
+  prerelease: true
   segments: 
   - 0
-  - 1
   - 2
-  version: 0.1.2
+  - 0pre1
+  version: 0.2.0pre1
 platform: ruby
 authors: 
 - John Mair (banisterfiend)
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-03 00:00:00 +13:00
+date: 2011-01-04 00:00:00 +13:00
 default_executable: 
 dependencies: []
 
@@ -72,19 +71,19 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
 
 rubyforge_project: