cplus2ruby 1.0.0

data/README

@@ -0,0 +1,210 @@
+---------------------------------------------------------
+Cplus2Ruby - Gluing C++ and Ruby together in an OO manner
+---------------------------------------------------------
+
+COPYRIGHT
+
+  Copyright (c) 2007, 2008 by Michael Neumann (mneumann@ntecs.de).
+  All rights reserved.
+
+LICENSE
+
+  Ruby License.
+
+ABOUT
+
+  Cplus2Ruby (or "C++Ruby") makes it easy to mix Ruby and C++ in
+  a seamless way. You can use the power of the Ruby object model
+  and where needed switch to C++ methods for ultimate performance!
+
+  Cplus2Ruby generates getter and setter methods for C++ properties,
+  and wrapper methods so that you can call your C++ methods from
+  Ruby without writing a single line of C++ wrapper code. In the same
+  way stub methods enable your C++ methods to directly call a Ruby
+  method.
+
+  As mentioned above shortly, the main purpose of Cplus2Ruby is speed.
+  Accessing instance variables in Ruby is somewhat slow compared to
+  accessing an C++ attribute. Calling a C++ method is as well *a lot*
+  faster than calling a Ruby method. Cplus2Ruby now allows you to
+  write your performance critical methods in C++, which can call other
+  C++ methods and access C++ attributes with native C++ performance.
+
+INSTALLATION
+
+  gem install cplus2ruby
+
+DEPENDENCIES
+
+  * gem install facets
+  * C++ compiler and make
+
+EXAMPLE
+
+  Take a look at the following example. You should also take a look
+  at the generated C++ source file (work/*.cc). Note that properties
+  are actually members of a C++ class, not instance variables, and as
+  such, their access from C++ is very fast. As calling a method is
+  quite slow in Ruby, a method defined in C++ ("method") can be called
+  directly from C++, which again is very fast! 
+
+    $LOAD_PATH.unshift './lib'
+    require 'rubygems'
+    require 'cplus2ruby'
+
+    class NeuralEntity; cplus2ruby
+      property :id
+    end
+
+    class Neuron < NeuralEntity
+      property :potential,       :float
+      property :last_spike_time, :float
+      property :pre_synapses
+
+      method :stimulate, {:at => :float},{:weight => :float}, %{
+        // This is C++ Code
+        @potential += at*weight;
+
+        // call a Ruby method
+        log(@potential);
+      }
+
+      stub_method :log, {:pot => :float}
+
+      def log(pot)
+        puts "log(#{pot})"
+      end
+
+      def initialize
+        self.pre_synapses = []
+      end
+    end
+
+    if __FILE__ == $0
+      #
+      # Generate C++ code, compile and load shared library. 
+      #
+      Cplus2Ruby.startup('work/neural') 
+
+      n = Neuron.new
+      n.id = "n1"
+      n.potential = 1.0
+      n.stimulate(1.0, 2.0)
+      p n.potential # => 3.0
+    end
+
+FEATURES
+
+  You can disable the substitution of "@" to "this->" in the generated
+  C++ source code with:
+
+      Cplus2Ruby.settings :substitute_iv_ats => false
+
+  A method signature to return a value (in our case an integer) looks like:
+
+    method :abc, {:arg1 => :int}, {:arg2 => :float}, {:returns => :int}, %{
+      ...
+    }
+
+  Mixins can be used:
+
+    module Mixin; cplus2ruby
+      property :a
+    end
+
+    class C; cplus2ruby
+      include Mixin
+    end
+
+  They don't generate a C++ class, instead get inlined into the class
+  into which they are mixed in.
+
+  You can use type aliases:
+
+    Cplus2Ruby.add_type_alias 'MyIntegerType' => 'unsigned int'
+
+  After that Cplus2Ruby knows about this type and how to convert it
+  (if it knows how to convert the 'unsigned int' type) and you can
+  use it wherever you want.
+
+  Inline, static and virtual methods can be declared like this:
+
+    method :abc, {:a1 => :int}, %{
+      body
+    }, :inline => true, :static => true, :virtual => true
+
+  There is also a static_method short-cut for static methods, so instead
+  of:
+
+    method :abc, {:a1 => :int}, %{
+      ...
+    }, :static => true
+  
+  you can write:
+
+    static_method :abc, {:a1 => :int}, %{
+      ...
+    }
+ 
+  To mark a method in a class hierarchy forever as virtual, you can 
+  write: 
+
+    virtual :method1, :method2
+
+  You can also define a class that is purely used from within C++.
+  If you don't want to generate wrapper code etc. specify:
+
+    cplus2ruby :no_wrap => true
+
+  You can use Strings, Symbols and Classes for types in signatures or
+  in property declarations. There is no distinction between Strings and
+  Symbols. If you specify a class, it must be known to Cplus2Ruby,
+  either explicitly:
+
+    class A
+      cplus2ruby # marks it known to Cplus2Ruby
+    end
+
+  Or using inheritance:
+
+    class A
+      cplus2ruby # marks it known to Cplus2Ruby
+    end
+
+    class B < A  # implicit by inheritance
+    end
+
+  Global code (mostly type declarations etc.) can be added as shown
+  below:
+
+    Cplus2Ruby << %q{
+      #include <assert.h>
+      #include <math.h>
+
+      #define real_exp expf
+      #define real_fabs fabsf
+
+      #define THROW(str) rb_raise(rb_eRuntimeError, str)
+    }
+
+  Compilation flags etc.:
+
+    Cplus2Ruby.startup(module_name, force_compilation, cflags, ldflags) 
+
+  For example:
+
+    #
+    # force_compilation => true regenerates and recompiles the 
+    # C++ code every time.
+    #
+    Cplus2Ruby.startup("work/mymodule", true, '-DNDEBUG -Winline -Wall', '-lm') 
+
+BUGS
+
+  * I get an "illegal instruction" (sig 4) when the C++ code is compiled
+    with -pthread. This is the default in the ports on FreeBSD 7.0 even 
+    when WITH_PTHREAD is defined. It is somehow related to the GC, 
+    because when I disable the GC everything is fine (except memory
+    usage :).
+
+END 

data/cplus2ruby.gemspec

@@ -0,0 +1,19 @@
+require 'rubygems'
+
+spec = Gem::Specification.new do |s|
+  s.name = "cplus2ruby"
+  s.version = "1.0.0"
+  s.summary = "Gluing C++ and Ruby together in an OO manner"
+  s.files = Dir['**/*']
+  s.add_dependency('facets', '>= 2.3.0')
+
+  s.author = "Michael Neumann"
+  s.email = "mneumann@ntecs.de"
+  s.homepage = "http://www.ntecs.de/projects/cplus2ruby/"
+  s.rubyforge_project = "cplus2ruby"
+end
+
+if __FILE__ == $0
+  Gem::manage_gems
+  Gem::Builder.new(spec).build
+end

data/example.rb

@@ -0,0 +1,44 @@
+require 'rubygems'
+$LOAD_PATH.unshift './lib'
+require 'cplus2ruby'
+
+class NeuralEntity; cplus2ruby
+  property :id
+end
+
+class Neuron < NeuralEntity
+  property :potential,       :float
+  property :last_spike_time, :float
+  property :pre_synapses
+
+  method :stimulate, {:at => :float},{:weight => :float}, %{
+    // This is C++ Code
+    @potential += at*weight;
+
+    // call a Ruby method
+    log(@potential);
+  }
+
+  stub_method :log, {:pot => :float}
+
+  def log(pot)
+    puts "log(#{pot})"
+  end
+
+  def initialize
+    self.pre_synapses = []
+  end
+end
+
+if __FILE__ == $0
+  #
+  # Generate C++ code, compile and load shared library. 
+  #
+  Cplus2Ruby.startup('work/neural') 
+
+  n = Neuron.new
+  n.id = "n1"
+  n.potential = 1.0
+  n.stimulate(1.0, 2.0)
+  p n.potential # => 3.0
+end

data/lib/cplus2ruby/code_generator.rb

@@ -0,0 +1,52 @@
+class Cplus2Ruby::CodeGenerator
+  require 'fileutils'
+
+  def initialize(model=Cplus2Ruby.model)
+    @model = model
+  end
+
+  # 
+  # Allows preprocessing of generated code.
+  #
+  def write_out(file, str)
+    if @model.settings()[:substitute_iv_ats] 
+      str.gsub!('@', 'this->')
+    end
+    FileUtils.mkdir_p(File.dirname(file))
+    File.open(file, 'w+') {|out| out.puts str}
+  end
+
+  def no_wrap?(klass)
+    (klass.local_annotations[:__options__] || {})[:no_wrap]
+  end
+
+  def wrap?(klass)
+    not no_wrap?(klass)
+  end
+
+  def all_properties_of(klass)
+    klass.local_annotations.each do |name, options|
+      next if options[:class] != Cplus2Ruby::Property
+      yield name, options
+    end
+  end
+
+  def all_methods_of(klass)
+    klass.local_annotations.each do |name, options|
+      next if options[:class] != Cplus2Ruby::Method
+      yield name, options
+    end
+  end
+
+  def args_convertable?(args)
+    #FIXME: Facets 2.3.0 has a bug in Dictionary#all?
+    ##args.all? {|_, type| @model.typing.can_convert?(type) }
+    args.each {|_, type| return false unless @model.typing.can_convert?(type) }
+    return true
+  end
+
+  def arity(args)
+    args.size - (args.include?(:returns) ? 1 : 0)
+  end 
+
+end

data/lib/cplus2ruby/compiler.rb

@@ -0,0 +1,84 @@
+class Cplus2Ruby::Compiler
+  require 'cplus2ruby/cpp_code_generator'
+  require 'cplus2ruby/wrapper_code_generator'
+
+  def initialize(model=Cplus2Ruby.model)
+    @model = model
+  end
+
+  def write_files(mod_name)
+    cpp_cg = Cplus2Ruby::CppCodeGenerator.new(@model)
+    wrap_cg = Cplus2Ruby::WrapperCodeGenerator.new(@model)
+    cpp_cg.write_files(mod_name)
+    wrap_cg.write_files(mod_name)
+  end
+
+  def startup(file, force_compilation=false, cflags="", libs="", &block) 
+    n = names(file)
+
+    if not force_compilation
+      begin
+        require n[:ld]
+        block.call if block
+        return
+      rescue LoadError
+      end
+    end
+
+    compile(file, cflags, libs)
+    require n[:ld]
+    block.call if block
+  end
+
+  #
+  # Compiles +file+. Returns the name of the shared object to
+  # use by +require+.
+  #
+  def compile(file, cflags="", libs="")
+    n = names(file)
+
+    require 'win32/process' if RUBY_PLATFORM.match('mswin')
+    require 'fileutils'
+
+    FileUtils.mkdir_p(n[:dir])
+
+    make = RUBY_PLATFORM.match('mswin') ? 'nmake' : 'make'
+
+    Dir.chdir(n[:dir]) do
+      system("#{make} clean") if File.exist?('Makefile')
+      write_files(n[:mod])
+
+      pid = fork do
+        require 'mkmf'
+        $CFLAGS = cflags
+        $LIBS << (" -lstdc++ " + libs)
+        create_makefile(n[:mod])
+        exec "#{make}"
+      end
+      _, status = Process.waitpid2(pid)
+
+      if RUBY_PLATFORM.match('mswin')
+        raise if status != 0
+      else
+        raise if status.exitstatus != 0
+      end
+    end
+
+    return n[:ld]
+  end
+
+  def names(file) 
+    require 'rbconfig'
+    base = File.basename(file)
+    dir = File.dirname(file)
+    mod, ext = base.split(".") 
+    ld = "#{dir}/#{mod}.#{Config::CONFIG['DLEXT']}"
+    { :file => file,
+      :base => base,
+      :dir  => dir,
+      :mod  => mod,
+      :ext  => ext,
+      :ld   => ld }
+  end
+
+end

data/lib/cplus2ruby/cpp_code_generator.rb

@@ -0,0 +1,287 @@
+require 'cplus2ruby/code_generator'
+
+class Cplus2Ruby::CppCodeGenerator < Cplus2Ruby::CodeGenerator
+  DEFAULT_INCLUDES = [:"stdlib.h", "ruby.h"] 
+
+  def gen_rubyObject
+    %[
+      struct RubyObject {
+        VALUE __obj__;
+        RubyObject() { __obj__ = Qnil; }
+        virtual ~RubyObject() {};
+        static void __free(void *ptr) { ((RubyObject*)ptr)->__free__(); }
+        static void __mark(void *ptr) { ((RubyObject*)ptr)->__mark__(); }
+        virtual void __free__() { delete this; }
+        virtual void __mark__() { }
+      };
+    ]
+  end
+
+  def gen_include(inc)
+    "#include " + 
+    case inc
+    when Symbol
+      %{<#{inc}>}
+    when String
+      %{"#{inc}"}
+    else
+      raise ArgumentError, "invalid header"
+    end
+  end
+
+  def gen_includes(includes)
+    includes.map {|inc| gen_include(inc) }.join("\n")
+  end
+
+  def gen_type_alias(from, to)
+    "typedef #{to} #{from};"
+  end
+
+  # 
+  # Type aliases is a hash in the form from => to.
+  #
+  def gen_type_aliases(type_aliases)
+    type_aliases.map {|from, to| gen_type_alias(from, to) }.join("\n")
+  end
+
+  #
+  # +kind+ is either :free or :mark
+  #
+  def gen_free_or_mark_method(klass, kind)
+    stmts = stmts_for_free_or_mark_method(klass, kind)
+    return "" if stmts.empty?
+    stmts << "super::__#{kind}__()"
+    %[
+      void #{klass.name}::__#{kind}__()
+      {
+        #{stmts.join(";\n")};
+      }
+    ]
+  end
+
+  def gen_constructor(klass)
+    stmts = []
+    all_properties_of(klass) do |name, options|
+      init = @model.typing.lookup_entry(:init, options, options[:type])
+      stmts << @model.typing.var_assgn("this->#{name}", init) unless init.nil?
+    end
+    #return "" if stmts.empty?
+    %[
+      #{klass.name}::#{klass.name}()
+      {
+        #{stmts.join(";\n")};
+      }
+    ]
+  end
+
+  def gen_property(name, options)
+    @model.typing.var_decl(options[:type], name)
+  end
+
+  #
+  # If +klassname+ is nil, then it doesn't include the
+  # Klassname:: prefix. 
+  #
+  # Doesn't include the semicolon at the end.
+  #
+  def gen_method_sig(klassname, name, options, is_declaration)
+    args = options[:arguments].dup
+    returns = args.delete(:returns) || "void"
+
+    out = ""
+    if is_declaration
+      out << "static " if options[:static] 
+      out << "inline " if options[:inline]
+      out << "virtual " if options[:virtual]
+    end
+    out << @model.typing.var_decl(returns, "")
+    out << " "
+
+    s = args.map {|aname, atype| @model.typing.var_decl(atype, aname) }.join(", ")
+
+    out << "#{klassname}::" if klassname
+    out << "#{name}(#{s})"
+    return out
+  end
+
+  def gen_method_body(klassname, name, options)
+    if options[:stub]
+      gen_stub_method(klassname, name, options)
+    else
+      "{\n" + (options[:body] || @model.settings[:default_body_when_nil]) + "}\n"
+    end
+  end
+
+  #
+  # Generates a C++ method that forwards the call to the Ruby method
+  # of the same name.
+  #
+  def gen_stub_method(klassname, name, options)
+    raise "Stub method with body is invalid!" if options[:body]
+
+    args = options[:arguments].dup
+    unless args_convertable?(args)
+      raise "ERROR: Cannot convert stub method #{klassname}::#{name}"
+    end
+
+    returns = args.delete(:returns) || "void"
+
+    out = ""
+    out << "{\n"
+    out << "VALUE __res__ = " if returns != 'void'
+
+    # TODO: move rb_intern out
+    call_args = ["@__obj__", %{rb_intern("#{name}")}, args.size] + 
+      args.map {|n, k| @model.typing.convert(k, n, :c2ruby) }
+
+    out << %{rb_funcall(#{call_args.join(', ')});}
+
+    # check return type
+    if returns != 'void' 
+      out << @model.typing.convert(returns, '__res__', :ruby2c_checktype)
+      retval = @model.typing.convert(returns, '__res__', :ruby2c) 
+      out << "return #{retval};\n"
+    end
+
+    out << "}\n"
+
+    return out
+  end
+
+  def gen_method(klassname, name, options, include_body, is_declaration)
+    str = gen_method_sig(klassname, name, options, is_declaration)
+    str << gen_method_body(klassname, name, options) if include_body
+    str
+  end
+
+  def gen_class_declaration(klass)
+    if klass.superclass == Object
+      sc = "RubyObject"
+    else
+      sc = klass.superclass.name
+    end
+
+    #
+    # Do we have free or mark methods defined?
+    #
+    m = {}
+    [:free, :mark].each do |kind|
+      if not stmts_for_free_or_mark_method(klass, kind).empty?
+        m[kind] = "virtual void __#{kind}__();"
+      end
+    end
+
+    #
+    # Write out property declarations and method signatures.
+    #
+    stmts = []
+
+    all_properties_of(klass) {|name, options| 
+      stmts << gen_property(name, options)
+    }
+
+    all_methods_of(klass) {|name, options|
+      stmts << gen_method(nil, name, options, options[:inline], true)
+    }
+       
+    if no_wrap?(klass)
+      %[
+        struct #{klass.name} 
+        {
+          #{stmts.join("; \n")};
+        };
+      ]
+    else
+      %[
+        struct #{klass.name} : #{sc}
+        {
+          typedef #{sc} super;
+
+          #{klass.name}();
+
+          #{m[:free]}
+          #{m[:mark]}
+          
+          #{stmts.join("; \n")};
+        };
+      ]
+    end
+  end
+
+  def gen_class_impl(klass)
+    # FIXME: helper_codes
+
+    stmts = [] 
+
+    if wrap?(klass)
+      stmts << gen_constructor(klass)
+
+      [:free, :mark].each {|kind| 
+        stmts << gen_free_or_mark_method(klass, kind)
+      }
+    end
+
+    all_methods_of(klass) do |name, options|
+      next if options[:inline]
+      stmts << gen_method(klass.name, name, options, true, false)
+    end
+
+    stmts.join("\n")
+  end
+
+  def gen_header_file
+    out = ""
+    out << gen_includes(DEFAULT_INCLUDES + @model.includes)
+    out << gen_rubyObject()
+    out << gen_type_aliases(@model.typing.aliases)
+    out << @model.code
+
+    # forward class declarations
+    @model.entities_ordered.each do |klass|
+      out << "struct #{klass.name};\n"
+    end
+
+    # FIXME: helper_headers
+
+    #
+    # class declarations
+    #
+    @model.entities_ordered.each do |klass|
+      out << gen_class_declaration(klass)
+    end
+
+    return out
+  end
+
+  def gen_impl_file(mod_name)
+    out = ""
+    out << %{#include "#{mod_name}.h"\n\n}
+
+    #
+    # class declarations
+    #
+    @model.entities_ordered.each do |klass|
+      out << gen_class_impl(klass)
+    end
+
+    return out
+  end
+
+  def write_files(mod_name)
+    write_out(mod_name + ".h", gen_header_file())
+    write_out(mod_name + ".cc", gen_impl_file(mod_name))
+  end
+
+  protected
+
+  def stmts_for_free_or_mark_method(klass, kind)
+    stmts = []
+    all_properties_of(klass) do |name, options|
+      if free_mark = @model.typing.lookup_entry(kind, options, options[:type])
+        stmts << free_mark.gsub('%s', "this->#{name}") # FIXME: use a common replacement function
+      end
+    end
+    stmts
+  end
+
+end