← Back to branch summary

~ubuntu-branches/ubuntu/trusty/jruby/trusty-proposed

« back to all changes in this revision

Viewing changes to lib/ruby/site_ruby/shared/ffi/autopointer.rb

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Delafond
  • Date: 2009-12-10 12:34:42 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20091210123442-df7t1v36qtfkj5df
Tags: 1.4.0-1
* New upstream release.
* Updated watch file.
* Updated copyright file to reflect addition of new third-party jars.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/ruby/site_ruby/shared/ffi/autopointer.rb
 
1
module FFI
 
2
  class AutoPointer
 
3
 
 
4
    # call-seq:
 
5
    #   AutoPointer.new(pointer, method)     => the passed Method will be invoked at GC time
 
6
    #   AutoPointer.new(pointer, proc)       => the passed Proc will be invoked at GC time (SEE WARNING BELOW!)
 
7
    #   AutoPointer.new(pointer) { |p| ... } => the passed block will be invoked at GC time (SEE WARNING BELOW!)
 
8
    #   AutoPointer.new(pointer)             => the pointer's release() class method will be invoked at GC time
 
9
    #
 
10
    # WARNING: passing a proc _may_ cause your pointer to never be GC'd, unless you're careful to avoid trapping a reference to the pointer in the proc. See the test specs for examples.
 
11
    # WARNING: passing a block will cause your pointer to never be GC'd. This is bad.
 
12
    #
 
13
    # Please note that the safest, and therefore preferred, calling
 
14
    # idiom is to pass a Method as the second parameter. Example usage:
 
15
    #
 
16
    #   class PointerHelper
 
17
    #     def self.release(pointer)
 
18
    #       ...
 
19
    #     end
 
20
    #   end
 
21
    #
 
22
    #   p = AutoPointer.new(other_pointer, PointerHelper.method(:release))
 
23
    #
 
24
    # The above code will cause PointerHelper#release to be invoked at GC time.
 
25
    #
 
26
    # The last calling idiom (only one parameter) is generally only
 
27
    # going to be useful if you subclass AutoPointer, and override
 
28
    # release(), which by default does nothing.
 
29
    #
 
30
  end
 
31
end