mneumann / cplus2ruby Goto Github PK

---------------------------------------------------------
Cplus2Ruby - Gluing C++ and Ruby together in an OO manner
---------------------------------------------------------

COPYRIGHT

  Copyright (c) 2007, 2008 by Michael Neumann ([email protected]).
  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.commit('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.commit(module_name, force_compilation, cflags, ldflags) 

  For example:

    #
    # force_compilation => true regenerates and recompiles the 
    # C++ code every time.
    #
    Cplus2Ruby.commit("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