rltk 1.2.0 → 2.0.0

data/lib/rltk/cg/context.rb

@@ -0,0 +1,51 @@
+# Author:		Chris Wailes <chris.wailes@gmail.com>
+# Project: 	Ruby Language Toolkit
+# Date:		2012/03/20
+# Description:	This file defines the Context class.
+
+############
+# Requires #
+############
+
+# Ruby Language Toolkit
+require 'rltk/cg/bindings'
+
+#######################
+# Classes and Modules #
+#######################
+
+module RLTK::CG # :nodoc:
+	
+	# Bindings for LLVM contexts.
+	class Context
+		include BindingClass
+		
+		#################
+		# Class Methods #
+		#################
+		
+		# @return [Context] A global context.
+		def self.global
+			self.new(Bindings.get_global_context())
+		end
+		
+		####################
+		# Instance Methods #
+		####################
+		
+		# @param [FFI::Pointer, nil] ptr Pointer representing a context.  If nil, a new context is created.
+		def initialize(ptr = nil)
+			@ptr = ptr || Bindings.context_create()
+		end
+		
+		# Frees the resources used by LLVM for this context.
+		#
+		# @return [void]
+		def dispose
+			if @ptr
+				Bindings.context_dispose(@ptr)
+				@ptr = nil
+			end
+		end
+	end
+end

data/lib/rltk/cg/execution_engine.rb

@@ -0,0 +1,172 @@
+# Author:		Chris Wailes <chris.wailes@gmail.com>
+# Project: 	Ruby Language Toolkit
+# Date:		2012/03/15
+# Description:	This file defines the ExecutionEngine class, along with its
+#			subclasses.
+
+############
+# Requires #
+############
+
+# Ruby Language Toolkit
+require 'rltk/util/abstract_class'
+require 'rltk/cg/bindings'
+require 'rltk/cg/pass_manager'
+
+#######################
+# Classes and Modules #
+#######################
+
+module RLTK::CG # :nodoc:
+	
+	# The ExecutionEngine class and its subclasses execute code from the
+	# provided module, as well as providing a {PassManager} and
+	# {FunctionPassManager} for optimizing modules.
+	#
+	# @abstract Implemented by {Interpreter} and {JITCompiler}.
+	class ExecutionEngine
+		include AbstractClass
+		include BindingClass
+		
+		# @return [Module]
+		attr_reader :module
+		
+		# Create a new execution engine.
+		#
+		# @param [Module]	mod		Module to be executed.
+		# @param [Proc]	block	Block used by subclass constructors.  Don't use this parameter.
+		#
+		# @raise [RuntimeError] An error is raised if something went horribly wrong inside LLVM during the creation of this engine.
+		def initialize(mod, &block)
+			block = Proc.new { |ptr, error| Bindings.create_execution_engine_for_module(ptr, mod, error) } if block == nil
+			
+			ptr		= FFI::MemoryPointer.new(:pointer)
+			error	= FFI::MemoryPointer.new(:pointer)
+			status	= block.call(ptr, error)
+			
+			if status.zero?
+				@ptr		= ptr.read_pointer
+				@module	= mod
+		
+			else
+				errorp  = error.read_pointer
+				message = errorp.null? ? 'Unknown' : errorp.read_string
+		
+				error.autorelease = false
+		
+				Bindings.dispose_message(error)
+		
+				raise "Error creating execution engine: #{message}"
+			end
+		end
+		
+		# Frees the resources used by LLVM for this execution engine..
+		#
+		# @return [void]
+		def dispose
+			if @ptr
+				Bindings.dispose_execution_engine(@ptr)
+				
+				@ptr = nil
+			end
+		end
+		
+		# @return [FunctionPassManager] Function pass manager for this engine.
+		def function_pass_manager
+			@function_pass_manager ||= FunctionPassManager.new(self, @module)
+		end
+		alias :fpm :function_pass_manager
+		
+		# @return [PassManager] Pass manager for this engine.
+		def pass_manager
+			@pass_manager ||= PassManager.new(self, @module)
+		end
+		alias :pm :pass_manager
+		
+		# Builds a pointer to a global value.
+		#
+		# @param [GlobalValue] global Value you want a pointer to.
+		#
+		# @return [FFI::Pointer]
+		def pointer_to_global(global)
+			Bindings.get_pointer_to_global(@ptr, global)
+		end
+		
+		# Execute a function in the engine's module with the given arguments.
+		# The arguments may be either GnericValue objects or any object that
+		# can be turned into a GenericValue.
+		#
+		# @param [Function]					fun	Function object to be executed.
+		# @param [Array<GenericValue, Object>]	args	Arguments to be passed to the function.
+		#
+		# @return [GenericValue]
+		def run_function(fun, *args)
+			new_values = Array.new
+			
+			new_args =
+			fun.params.zip(args).map do |param, arg|
+				if arg.is_a?(GenericValue)
+					arg
+					
+				else
+					returning(GenericValue.new(arg)) { |val| new_values << val }
+				end
+			end
+			
+			args_ptr = FFI::MemoryPointer.new(:pointer, args.length)
+			args_ptr.write_array_of_pointer(new_args)
+			
+			returning(GenericValue.new(Bindings.run_function(@ptr, fun, args.length, args_ptr))) do
+				new_values.each { |val| val.dispose }
+			end
+		end
+		alias :run :run_function
+		
+		# Execute a function in the engine's module with the given arguments
+		# as the main function of a program.
+		#
+		# @param [Function]		fun	Function object to be executed.
+		# @param [Array<String>]	args	Arguments to be passed to the function.
+		#
+		# @return [GenericValue]
+		def run_function_as_main(fun, *args)
+			# Prepare the ARGV parameter.
+			argv = FFI::MemoryPointer.new(:pointer, argc)
+			argv.write_array_of_pointer(args.map { |str| FFI::MemoryPointer.from_string(str) })
+			
+			# Prepare the ENV parameter.
+			env = FFI::MemoryPointer.new(:pointer, ENV.size)
+			env.write_array_of_pointer(ENV.to_a.map { |pair| FFI::MemoryPointer.from_string(pair[0] + '=' + pair[1]) })
+			
+			GenericValue.new(Bindings.run_function_as_main(@ptr, fun, args.length, argv, env))
+		end
+		alias :run_main :run_function_as_main
+	end
+	
+	# An execution engine that interprets the given code.
+	class Interpreter < ExecutionEngine
+		
+		# Create a new interpreter.
+		#
+		# @param [Module] mod Module to be executed.
+		def initialize(mod)
+			super(mod) do |ptr, error|
+				Bindings.create_interpreter_for_module(ptr, mod, error)
+			end
+		end
+	end
+	
+	# An execution engine that compiles the given code when needed.
+	class JITCompiler < ExecutionEngine
+		
+		# Create a new just-in-time compiler.
+		#
+		# @param [Module]	mod		Module to be executed.
+		# @param [1, 2, 3]	opt_level	Optimization level; determines how much optimization is done during execution.
+		def initialize(mod, opt_level = 3)
+			super(mod) do |ptr, error|
+				Bindings.create_jit_compiler_for_module(ptr, mod, opt_level, error)
+			end
+		end
+	end
+end

data/lib/rltk/cg/function.rb

@@ -0,0 +1,224 @@
+# Author:		Chris Wailes <chris.wailes@gmail.com>
+# Project: 	Ruby Language Toolkit
+# Date:		2012/04/06
+# Description:	This file defines the Function class.
+
+############
+# Requires #
+############
+
+# Ruby Language Toolkit
+require 'rltk/cg/bindings'
+require 'rltk/cg/basic_block'
+require 'rltk/cg/value'
+
+#######################
+# Classes and Modules #
+#######################
+
+module RLTK::CG # :nodoc:
+	
+	# An LLVM IR function.
+	class Function < GlobalValue
+		# @return [FunctionType] FunctionType object describing this function's type.
+		attr_reader :type
+		
+		# Define a new function in a given module.  You can also use the
+		# {Module::FunctionCollection#add} method to add functions to
+		# modules.
+		#
+		# @param [FFI::Pointer, Module]				overloaded	Pointer to a function objet or a module.
+		# @param [String]							name			Name of the function in LLVM IR.
+		# @param [FunctionType, Array(Type, Array<Type>)]	type_info		FunctionType or Values that will be passed to {FunctionType#initialize}.
+		# @param [Proc]							block		Block to be executed inside the context of the function.
+		#
+		# @raise [RuntimeError] An error is raised if the overloaded parameter is of an incorrect type.
+		def initialize(overloaded, name = '', *type_info, &block)
+			@ptr =
+			case overloaded
+			when FFI::Pointer
+				overloaded
+			
+			when RLTK::CG::Module
+				@type = if type_info.first.is_a?(FunctionType) then type_info.first else FunctionType.new(*type_info) end
+				
+				Bindings.add_function(overloaded, name.to_s, @type)
+				
+			else
+				raise 'The first argument to Function.new must be either a pointer or an instance of RLTK::CG::Module.'
+			end
+			
+			self.instance_exec(self, &block) if block
+		end
+		
+		# @return [FunctionAttrCollection] Proxy object for inspecting function attributes.
+		def attributes
+			@attributes ||= FunctionAttrCollection.new(self)
+		end
+		alias :attrs :attributes
+		
+		# @return [BasicBlockCollection] Proxy object for inspecting a function's basic blocks.
+		def basic_blocks
+			@basic_blocks ||= BasicBlockCollection.new(self)
+		end
+		alias :blocks :basic_blocks
+		
+		# Get a function's calling convention.
+		#
+		# @see Bindings._enum_call_conv_
+		#
+		# @return [Symbol]
+		def calling_convention
+			Bindings.enum_type(:call_conv)[Bindings.get_function_call_conv(@ptr)]
+		end
+		
+		# Set a function's calling convention.
+		#
+		# @see Bindings._enum_call_conv_
+		#
+		# @param [Symbol] conv Calling convention to set.
+		def calling_convention=(conv)
+			Bindings.set_function_call_conv(@ptr, Bindings.enum_type(:call_conv)[conv])
+			
+			conv
+		end
+		
+		# @return [ParameterCollection] Proxy object for inspecting a function's parameters.
+		def parameters
+			@parameters ||= ParameterCollection.new(self)
+		end
+		alias :params :parameters
+		
+		# Verify that the function is valid LLVM IR.
+		#
+		# @return [nil, String] Human-readable description of any invalid constructs if invalid.
+		def verify
+			do_verification(:return_status)
+		end
+		
+		# Verify that the function is valid LLVM IR and abort the process if it isn't.
+		#
+		# @return [nil]
+		def verify!
+			do_verification(:abort_process)
+		end
+		
+		# Helper function for {#verify} and {#verify!}
+		def do_verification(action)
+			Bindings.verify_function(@ptr, action).to_bool
+		end
+		private :do_verification
+		
+		# This class is used to access a function's {BasicBlock BasicBlocks}
+		class BasicBlockCollection
+			include Enumerable
+			
+			# @param [Function] fun Function for which this is a proxy.
+			def initialize(fun)
+				@fun = fun
+			end
+			
+			# Add a {BasicBlock} to the end of this function.
+			#
+			# @param [String]		name			Name of the block in LLVM IR.
+			# @param [Context, nil]	context		Context in which to create the block.
+			# @param [Builder, nil]	builder		Builder to be used in evaluating *block*.
+			# @param [Array<Object>]	block_args	Arguments to be passed to *block*.
+			# @param [Proc]		block		Block to be evaluated using *builder* after positioning it at the end of the new block.
+			#
+			# @return [BasicBlock] New BasicBlock.
+			def append(name = '', context = nil, builder = nil, *block_args, &block)
+				BasicBlock.new(@fun, name, context, builder, *block_args, &block)
+			end
+			
+			# An iterator for each block inside this collection.
+			#
+			# @yieldparam block [BasicBlock]
+			#
+			# @return [Enumerator] Returns an Enumerator if no block is given.
+			def each
+				return to_enum :each unless block_given?
+				
+				ptr = Bindings.get_first_basic_block(@fun)
+				
+				self.size.times do |i|
+					yield BasicBlock.new(ptr)
+					ptr = Bindings.get_next_basic_block(ptr)
+				end
+			end
+			
+			# @return [BasicBlock, nil] The function's entry block if it has been added.
+			def entry
+				if (ptr = Bindings.get_entry_basic_block(@fun)) then BasicBlock.new(ptr) else nil end
+			end
+			
+			# @return [BasicBlock, nil] The function's first block if one has been added.
+			def first
+				if (ptr = Bindings.get_first_basic_block(@fun)) then BasicBlock.new(ptr) else nil end
+			end
+			
+			# @return [BasicBlock, nil] The function's last block if one has been added.
+			def last
+				if (ptr = Bindings.get_last_basic_block(@fun)) then BasicBlock.new(ptr) else nil end
+			end
+			
+			# @return [Integer] Number of basic blocks that comprise this function.
+			def size
+				Bindings.count_basic_blocks(@fun)
+			end
+		end
+		
+		# This class is used to access a function's attributes.
+		class FunctionAttrCollection < AttrCollection
+			@@add_method = :add_function_attr
+			@@del_method = :remove_function_attr
+		end
+		
+		
+		# This class is used to access a function's parameters.
+		class ParameterCollection
+			include Enumerable
+			
+			# @param [Function] fun Function for which this is a proxy.
+			def initialize(fun)
+				@fun = fun
+			end
+			
+			# Access the parameter at the given index.
+			#
+			# @param [Integer] index Index of the desired parameter.  May be negative.
+			#
+			# @return [Value] Value object representing the parameter.
+			def [](index)
+				index += self.size if index < 0
+				
+				if 0 <= index and index < self.size
+					Value.new(Bindings.get_param(@fun, index))
+				end
+			end
+			
+			# An iterator for each parameter inside this collection.
+			#
+			# @yieldparam val [Value]
+			#
+			# @return [Enumerator] Returns an Enumerator if no block is given.
+			def each
+				return to_enum :each unless block_given?
+				
+				self.size.times { |index| yield self[index] }
+				
+				self
+			end
+			
+			# @return [Integer] Number of function parameters.
+			def size
+				Bindings.count_params(@fun)
+			end
+			
+			# @return [Array<Value>] Array of Value objects representing the function parameters.
+			def to_a
+				self.size.times.to_a.inject([]) { |params, index| params << self[index] }
+			end
+		end
+	end
+end