rrd-ffi 0.2.0 → 0.2.1

data/.gitignore

@@ -2,3 +2,4 @@
 *.png
 pkg
 doc
+coverage

data/CHANGELOG.rdoc

@@ -1,15 +1,26 @@
 = Changelog
 
-== 2010-02-25
+== TODO: version 0.2.2
+
+* TODO: bang methods to base
+* TODO: Improve documentation
+* TODO: add more rrd functions (dump, tune, xport, resize)
+
+== 2010-03-01 version 0.2.1
+
+* Added bang methods to wrapper
+* Added error method to wrapper
+
+== 2010-02-25 version 0.2.0
 
 * Fixed error message to be cleared before every call to wrapper. It was causing problems when doing a valid call after an invalid one
 * Added advanced DSL for graphic building
 * Added DSL for creating RRD file
 * Added to RRD::Base methods create, update, fetch, info
+* Released
 
-== 2010-02-24
+== 2010-02-24 version 0.1.0
 
-* Released version 0.1.0
 * Basic DSL for graphic building
 * Added to RRD::Base methods first, last, restore
 * Added bindings to librrd through RRD::Wrapper - create, update, fetch, info, first, last, restore, graph

data/README.rdoc

@@ -4,7 +4,9 @@ rrd-ffi is a gem for using rrd actions in your ruby code.
 
 You may use it in the raw format, as many rrd libs in languages like perl or python, or you can use it through the dsl we provide.
 
-rrd-ffi uses ffi to wrap the librrd C bindings, not system calls
+rrd-ffi uses ffi to wrap the librrd C bindings, not system calls.
+
+IMPORTANT: You need librrd installed in your system for this gem to work
 
 = Basics 
 
@@ -12,11 +14,13 @@ Here's what you need to know before starting.
 
 == Installation 
 
+=== Notes
+
 To install rrd-ffi, you will need to have librrd in your system.
 
 Then, run <tt>sudo gem install rrd-ffi</tt>
 
-If you are using Mac Ports you will have problems, so add the following to your .profile/.bashrc/.bash_profile file:
+If you are using Mac Ports you will have problems, so add the following to your .profile|.bashrc|.bash_profile file:
 
   export RRD_LIB=/opt/local/lib/librrd.dylib
 
@@ -26,11 +30,19 @@ or
 
 If you are not using MAC OS and still have problems, export the RRD_PATH variable with the path to your librrd file.
 
+=== Installing librrd
+
+Debian/Ubuntu: <tt>apt-get install librrd-dev</tt>
+
+Fedora/Red Hat: <tt>yum install rrdtool-devel</tt>
+
+Mac: <tt>port install rrdtool</tt>
+
 == Example Usage
   require "rrd"
   rrd = RRD::Base.new("myrrd.rrd")
   # Restoring a rrd file from xml
-  rrd.restore("myrrd.xml")
+  rrd.restore("myrrd.xml", :overwrite => true)
 
   # Fetching data from rrd
   rrd.fetch(:average).each {|line| puts line.inspect}
@@ -45,6 +57,10 @@ If you are not using MAC OS and still have problems, export the RRD_PATH variabl
   puts rrd.starts_at
   puts rrd.ends_at
 
+  # Error handling
+  rrd.fetch(:unknown_function) # should return false
+  puts rrd.error
+
 === DSLs
 
   # Creating a new rrd
@@ -74,11 +90,31 @@ If you are not using MAC OS and still have problems, export the RRD_PATH variabl
 
 == Raw API Usage
 
+Normal methods return false on error, or the expected result otherwise.
+
+Bang methods raise exception on error.
+
+  # Restoring a rrd file from xml
+  RRD::Wrapper.restore "myrrd.xml", "myrrd.rrd"
+
   # Creating a rrd file
   RRD::Wrapper.create "myrrd.rrd", "--step", "300", "DS:ifOutOctets:COUNTER:1800:0:4294967295", "RRA:AVERAGE:0.5:1:2016"
   
   # Updating rrd with a new value
   RRD::Wrapper.update "myrrd.rrd", "N:500000000"
 
+	# Fetching average data
+  RRD::Wrapper.fetch "myrrd.rrd", "AVERAGE"
+
+	# Looking for the first and last entered dates 
+  RRD::Wrapper.first "myrrd.rrd"
+  RRD::Wrapper.last "myrrd.rrd"
+
   # Creating a graph
-  RRD::Wrapper.graph("graph.png", "DEF:data=myrrd.rrd:ifOutOctets:AVERAGE", "LINE1:data#0000FF:Output bytes")
+  RRD::Wrapper.graph("graph.png", "DEF:data=myrrd.rrd:ifOutOctets:AVERAGE", "LINE1:data#0000FF:Output bytes")
+
+  # Getting the error happened
+  puts RRD::Wrapper.error
+
+  # Throwing the error if happens
+  RRD::Wrapper.fetch! "myrrd.rrd", "WRONG FUNCTION"

data/Rakefile

@@ -1,6 +1,8 @@
+$:.unshift(File.dirname(__FILE__) + "/lib")
+
 require "rake"
 require "spec/rake/spectask"
-require "lib/rrd/version"
+require "rrd/version"
 
 begin
   require "hanna/rdoctask"
@@ -32,6 +34,13 @@ Spec::Rake::SpecTask.new(:spec) do |t|
   t.spec_files = FileList['spec/**/*_spec.rb']
 end
 
+desc "Rspec : run all with RCov"
+Spec::Rake::SpecTask.new('spec:rcov') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'gems', '--exclude', 'spec']
+end
+
 Rake::RDocTask.new do |rdoc|
   rdoc.main = "README.rdoc"
   rdoc.rdoc_dir = "doc"

data/lib/rrd.rb

@@ -9,7 +9,7 @@ require "rrd/ext/fixnum"
 module RRD
   extend self
   
-  def graph(image_file, options, &block)
+  def graph(image_file, options = {}, &block)
     graph = Graph.new(image_file, options)
     graph.instance_eval(&block)
     graph.save

data/lib/rrd/base.rb

@@ -1,4 +1,5 @@
 module RRD
+  # TODO: add bang methods
   class Base
     attr_accessor :rrd_file
       
@@ -6,6 +7,10 @@ module RRD
       @rrd_file = rrd_file
     end
     
+    def error
+      Wrapper.error
+    end
+    
     def create(options = {}, &block)
       builder = RRD::Builder.new(rrd_file, options)
       builder.instance_eval(&block)
@@ -52,8 +57,10 @@ module RRD
     alias :last :ends_at
   
     # See RRD::Wrapper.restore
-    def restore(xml_file)
-      Wrapper.restore(xml_file, rrd_file)
+    def restore(xml_file, options = {})
+      line_params = []
+      line_params << "--force-overwrite" if options[:overwrite]
+      Wrapper.restore(xml_file, rrd_file, *line_params)
     end
     
   end

data/lib/rrd/graph.rb

@@ -8,7 +8,7 @@ module RRD
     def initialize(output, parameters = {})
       @output = output
       
-      @parameters = {:start => Time.now - 1.day, :end => Time.now, :title => ""}
+      @parameters = {:start => Time.now - 1.day, :end => Time.now, :title => ""}.merge parameters
       @parameters[:start] = @parameters[:start].to_i
       @parameters[:end] = @parameters[:end].to_i
       

data/lib/rrd/version.rb

@@ -2,7 +2,7 @@ module RRD
   module Version  #:nodoc: all
     MAJOR = 0
     MINOR = 2
-    PATCH = 0
+    PATCH = 1
     STRING = "#{MAJOR}.#{MINOR}.#{PATCH}"
   end
 end

data/lib/rrd/wrapper.rb

@@ -4,6 +4,19 @@ module RRD
   # See http://oss.oetiker.ch/rrdtool/doc/rrdtool.en.html for details on the parameters
   class Wrapper
     
+    INFO_TYPE = { 0 => :u_val, 1 => :u_cnt, 2 => :u_str, 3 => :u_int, 4 => :u_blob}
+    BANG_METHODS = [:info!, :fetch!, :first!, :last!, :restore!, :graph!, :create!, :update!]
+    
+    def self.detect_rrd_lib
+      if defined?(RRD_LIB)
+        RRD_LIB
+      elsif ENV["RRD_LIB"]
+        ENV["RRD_LIB"] 
+      else
+        "rrd"
+      end
+    end
+    
     class RRDBlob < FFI::Struct
       layout :size,  :ulong,
              :ptr, :pointer
@@ -26,20 +39,8 @@ module RRD
     
     class << self
       extend FFI::Library
-      
-      INFO_TYPE = { 0 => :u_val, 1 => :u_cnt, 2 => :u_str, 3 => :u_int, 4 => :u_blob}
-      
-      def self.rrd_lib
-        if defined?(RRD_LIB)
-          RRD_LIB
-        elsif ENV["RRD_LIB"]
-          ENV["RRD_LIB"] 
-        else
-          "rrd"
-        end
-      end
 
-      ffi_lib rrd_lib
+      ffi_lib RRD::Wrapper.detect_rrd_lib
       attach_function :rrd_create, [:int, :pointer], :int
       attach_function :rrd_update, [:int, :pointer], :int
       attach_function :rrd_info, [:int, :pointer], :pointer
@@ -54,20 +55,24 @@ module RRD
       # Set up a new Round Robin Database (RRD).
       def create(*args)
         argv = to_pointer(["create"] + args)
-        raise rrd_get_error unless rrd_create(args.size+1, argv) == 0
+        rrd_create(args.size+1, argv) == 0
         true
       end
 
       # Store new data values into an RRD.
       def update(*args)
         argv = to_pointer(["update"] + args)
-        raise rrd_get_error unless rrd_update(args.size+1, argv) == 0
-        true
+        rrd_update(args.size+1, argv) == 0
       end
 
       # Get data for a certain time period from a RRD.
       # 
-      # Returns an array of arrays (which contains the date and values for all datasources)
+      # Returns an array of arrays (which contains the date and values for all datasources):
+      #
+      #   [["time"    , "cpu", "memory"],
+      #    [1266933600, "0.5", "511"   ],
+      #    [1266933900, "0.9", "253"   ]]
+      #
       def fetch(*args)
         #FIXME: Refactor this
         start_time_ptr = empty_pointer
@@ -76,9 +81,9 @@ module RRD
         ds_count_ptr = empty_pointer
         ds_names_ptr = empty_pointer
         
-        values = FFI::MemoryPointer.new(:pointer)
+        values_ptr = FFI::MemoryPointer.new(:pointer)
         argv = to_pointer(["fetch"] + args)
-        raise rrd_get_error unless rrd_fetch(args.size+1, argv, start_time_ptr, end_time_ptr, step_ptr, ds_count_ptr, ds_names_ptr, values) == 0
+        return false unless rrd_fetch(args.size+1, argv, start_time_ptr, end_time_ptr, step_ptr, ds_count_ptr, ds_names_ptr, values_ptr) == 0
         
         ds_count = ds_count_ptr.get_int(0)
         start_time = start_time_ptr.get_int(0)
@@ -86,14 +91,17 @@ module RRD
         step = step_ptr.get_int(0)
         
         result_lines = (end_time-start_time)/step
+        
+        ds_names = ds_names_ptr.get_pointer(0).get_array_of_string(0, ds_count)
+        values = values_ptr.get_pointer(0).get_array_of_double(0, result_lines * ds_count)
+        
         result = []
-        (0..result_lines-1).each do |i|
-          data = []
-          data << start_time + i*step
-          (0..ds_count-1).each do |j|
-            data << values.get_pointer(0)[8*(ds_count*i+j)].get_double(0)
-          end
-          result << data
+        result << ["time"] + ds_names
+        (0..result_lines-1).each do |line|
+          date = start_time + line*step
+          first = ds_count*line
+          last = ds_count*line + ds_count - 1
+          result << [date] + values[first..last]
         end
         
         result
@@ -113,6 +121,7 @@ module RRD
           result = item[:next]
         end
         
+        return false if info.empty?
         info
       end
       
@@ -122,7 +131,7 @@ module RRD
       def first(*args)
         argv = to_pointer(["first"] + args)
         date = rrd_first(args.size+1, argv)
-        raise rrd_get_error if date == -1
+        return false if date == -1
         date
       end
       
@@ -132,31 +141,61 @@ module RRD
       def last(*args)
         argv = to_pointer(["last"] + args)
         date = rrd_last(args.size+1, argv)
-        raise rrd_get_error if date == -1
+        return false if date == -1
         date
       end
       
       # Restore an RRD in XML format to a binary RRD.
       def restore(*args)
         argv = to_pointer(["restore"] + args)
-        raise rrd_get_error unless rrd_restore(args.size+1, argv) == 0
-        true
+        rrd_restore(args.size+1, argv) == 0
       end
       
       # Create a graph from data stored in one or several RRDs.
       def graph(*args)
         argv = to_pointer(["graph"] + args)
-        raise rrd_get_error unless rrd_graph(args.size+1, argv, *Array.new(6, empty_pointer)) == 0
-        true
+        xsize_ptr = empty_pointer
+        ysize_ptr = empty_pointer
+        ymin_ptr = empty_pointer
+        ymax_ptr = empty_pointer
+        rrd_graph(args.size+1, argv, empty_pointer, xsize_ptr, ysize_ptr, empty_pointer, ymin_ptr, ymax_ptr) == 0
+      end
+
+      def error
+        rrd_get_error
+      end
+      
+      def clear_error
+        rrd_clear_error
+      end
+      
+      def methods
+        super + BANG_METHODS
+      end
+
+      def respond_to?(method, include_private = false)
+        super || BANG_METHODS.include?(method.to_sym)
+      end   
+        
+      def method_missing(method, *args)
+        return bang($1, *args) if method.to_s =~ /^(.+)!$/ && BANG_METHODS.include?(method.to_sym)
+        super
       end
       
+      def bang(method, *args)
+        result = send(method, *args)
+        raise error unless result
+        result
+      end
+   
       private
       def empty_pointer
         FFI::MemoryPointer.new(:pointer)
       end
 
+      # FIXME: remove clear_error from here
       def to_pointer(array_of_strings)
-        rrd_clear_error
+        clear_error
         strptrs = []
         array_of_strings.each {|item| strptrs << FFI::MemoryPointer.from_string(item)}
 

data/rrd-ffi.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rrd-ffi}
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["morellon", "fnando", "rafaelrosafu", "dalcico"]
-  s.date = %q{2010-02-25}
+  s.date = %q{2010-03-01}
   s.description = %q{Provides bindings for many RRD functions (using ffi gem and librrd), as well as DSLs for graphic and rrd building. You must have librrd in your system!}
   s.email = %q{morellon@gmail.com}
   s.extra_rdoc_files = [

data/spec/rrd/base_spec.rb

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + "/../spec_helper"
+require "spec_helper"
 
 describe RRD::Base do
   
@@ -41,8 +41,8 @@ describe RRD::Base do
   end
   
   it "should restore a rrd from xml" do
-    RRD::Wrapper.should_receive(:restore).with(XML_FILE, RRD_FILE).and_return(true)
-    @rrd.restore(XML_FILE).should be_true
+    RRD::Wrapper.should_receive(:restore).with(XML_FILE, RRD_FILE, "--force-overwrite").and_return(true)
+    @rrd.restore(XML_FILE, :overwrite => true).should be_true
   end
   
   it "should return the starting date" do
@@ -55,6 +55,12 @@ describe RRD::Base do
     @rrd.ends_at.should be_a(Time)
   end
   
+  it "should return the error" do
+    @rrd.error.should be_empty
+    @rrd.restore("unknown file").should be_false
+    @rrd.error.should_not be_empty
+  end
+  
   it "should respond to first"
   it "should respond to last"
 end

data/spec/rrd/builder_spec.rb

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + "/../spec_helper"
+require "spec_helper"
 
 describe RRD::Builder do
   

data/spec/rrd/graph_spec.rb

@@ -1,10 +1,10 @@
-require File.dirname(__FILE__) + "/../spec_helper"
+require "spec_helper"
 
 describe RRD::Graph do
     
   before do
     RRD::Base.new(RRD_FILE).restore(XML_FILE)
-    @graph = RRD::Graph.new IMG_FILE
+    @graph = RRD::Graph.new IMG_FILE, :title => "Title", :width => 800, :height => 200
   end
   
   it "should store definition for rrd data" do
@@ -58,8 +58,10 @@ describe RRD::Graph do
     @graph.line RRD_FILE, :memory => :average, :color => "#0000FF", :label => "Memory Avg"
     RRD::Wrapper.should_receive(:graph).with(IMG_FILE,
                                             "--end", anything(),
+                                            "--height", "200",
                                             "--start", anything(),
-                                            "--title", "",
+                                            "--title", "Title",
+                                            "--width", "800",
                                             "DEF:memory_average=#{RRD_FILE}:memory:AVERAGE",
                                             "LINE1:memory_average#0000FF:Memory Avg").and_return true
     @graph.save

data/spec/rrd/wrapper_spec.rb

@@ -1,8 +1,31 @@
-require File.dirname(__FILE__) + "/../spec_helper"
+require "spec_helper"
 
 describe RRD::Wrapper do
   
+  context "when looking for librrd path" do
+    before :each do
+      Object.send(:remove_const, :RRD_LIB) if defined?(::RRD_LIB) 
+      ENV["RRD_LIB"] = nil
+    end
+      
+    it "should look on RRD_LIB constant first" do
+      ::RRD_LIB = "first"
+      ENV["RRD_LIB"] = "second"
+      RRD::Wrapper.detect_rrd_lib.should == "first"
+    end
+    
+    it "should look on ENV if RRD_LIB is not defined" do
+      ENV["RRD_LIB"] = "second"
+      RRD::Wrapper.detect_rrd_lib.should == "second"
+    end
+    
+    it "should return 'rrd' for FFI to look up if can't use RRD_LIB or ENV" do
+      RRD::Wrapper.detect_rrd_lib.should == "rrd"
+    end
+  end
+  
   context "when no rrd file exists" do
+    
     it "should restore a rrd from xml" do
       RRD::Wrapper.restore(XML_FILE, RRD_FILE).should be_true
     end
@@ -27,9 +50,11 @@ describe RRD::Wrapper do
     
     it "should fetch values" do
       values = RRD::Wrapper.fetch(RRD_FILE, "AVERAGE", "--start", "1266933600", "--end", "1267020000")
-      values.should have(25).lines
-      values[0][0].should == 1266933600
-      values[0][1].should == 0.0008
+      values.should have(26).lines
+      values[0][0].should == "time"
+      values[1][0].should == 1266933600
+      values[1][1].should == 0.0008
+      values.last[0].should == 1267020000
     end
     
     it "should return info data about this file" do
@@ -46,9 +71,43 @@ describe RRD::Wrapper do
     end
     
     it "should create a graph correctly" do
-      RRD::Wrapper.graph(IMG_FILE, "DEF:data=#{RRD_FILE}:memory:AVERAGE", "LINE1:data#0000FF:Memory Avg")
+      RRD::Wrapper.graph(IMG_FILE, "--width", "1000", "--height", "300", "DEF:data=#{RRD_FILE}:memory:AVERAGE", "LINE1:data#0000FF:Memory Avg")
       File.should be_file(IMG_FILE)
     end
+    
+    it "should return the error correctly, cleaning the error var" do
+      RRD::Wrapper.error.should be_empty
+      RRD::Wrapper.fetch("error").should be_false
+      RRD::Wrapper.error.should_not be_empty
+    end
+  end
+  
+  context "when using bang methods" do
+    
+    it "should respond to them" do
+      RRD::Wrapper::BANG_METHODS.each do |method|
+        RRD::Wrapper.respond_to?(method).should be_true
+      end
+    end
+    
+    it "should list them" do
+      (RRD::Wrapper.methods & RRD::Wrapper::BANG_METHODS).should == RRD::Wrapper::BANG_METHODS
+    end
+    
+    it "should return the normal method result" do
+      RRD::Wrapper.restore!(XML_FILE, RRD_FILE).should be_true
+    end
+    
+    it "should raise error if the normal method is not bangable" do
+      RRD::Wrapper.should_not_receive(:bang)
+      lambda{RRD::Wrapper.not_bangable}.should raise_error(NoMethodError)
+    end
+    
+    it "should raise error if the normal method result is false" do
+      RRD::Wrapper.should_receive(:info).and_return(false)
+      RRD::Wrapper.should_receive(:error).and_return("error message")
+      lambda{RRD::Wrapper.bang(:info)}.should raise_error("error message")
+    end
   end
   
 end

data/spec/rrd_spec.rb

@@ -1,4 +1,4 @@
-require File.dirname(__FILE__) + "/spec_helper"
+require "spec_helper"
 
 describe RRD do
   

data/spec/spec_helper.rb

@@ -3,9 +3,11 @@ require "spec"
 $LOAD_PATH.unshift File.dirname(__FILE__) + "/../lib"
 require "rrd"
 
+$VERBOSE = nil
 RRD_FILE = File.expand_path(File.dirname(__FILE__) + "/vm.rrd")
 IMG_FILE = File.expand_path(File.dirname(__FILE__) + "/vm.png")
 XML_FILE = File.expand_path(File.dirname(__FILE__) + "/vm.xml")
+$VERBOSE = false
 
 Spec::Runner.configure do |config|
   config.append_before :each do    

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rrd-ffi
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - morellon
@@ -12,7 +12,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-25 00:00:00 -03:00
+date: 2010-03-01 00:00:00 -03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency