solaris-kstat 1.0.3 → 1.1.0

data/CHANGES

@@ -1,3 +1,10 @@
+== 1.1.0 - 13-Oct-2013
+* Converted code to use FFI.
+* The Kstat::Error subclass was removed. Any internal FFI
+  functions that fail raise a SystemCallError instead.
+* Refactored the test suite, and added some tests for FFI structs.
+* Added test-unit 2 and rake as development dependencies.
+
 == 1.0.3 - 30-Jul-2011
 * Added test-unit as a development dependency.
 * Fixed a switch statement bug (missing break).

data/MANIFEST

@@ -4,7 +4,8 @@
 * Rakefile
 * solaris-kstat.gemspec
 * examples/example_kstat.rb
-* ext/extconf.rb
-* ext/solaris/rkstat.c
-* ext/solaris/rkstat.h
+* lib/solaris/kstat.rb
+* lib/solaris/kstat/structs.rb
+* lib/solaris/kstat/functions.rb
 * test/test_solaris_kstat.rb
+* test/test_solaris_kstat_structs.b

data/README

@@ -1,31 +1,31 @@
 == Description
-   A Ruby interface for the Solaris kstat library.
+  A Ruby interface for the Solaris kstat library.
    
 == Prerequisites
-   Solaris 8 (SunOS 2.8) or later.
+  Solaris 8 (SunOS 2.8) or later.
 
 == Installation
-   gem install solaris-kstat
+  gem install solaris-kstat
 
 == Synopsis
-   require 'solaris/kstat'
-   require 'pp'
-   include Solaris
+  require 'solaris/kstat'
+  require 'pp'
+  include Solaris
 
-   k = Kstat.new('cpu_info', 0, 'cpu_info0')
-   pp k.record
+  k = Kstat.new('cpu_info', 0, 'cpu_info0')
+  pp k.record
 
-   {'cpu_info'=>
-      {0=>
-      {'cpu_info0'=>
-         {'chip_id'=>0,
-          'fpu_type'=>'sparcv9',
-          'device_ID'=>0,
-          'cpu_type'=>'sparcv9',
-          'implementation'=>'Unknown',
-          'clock_MHz'=>502,
-          'state_begin'=>1105974702,
-          'state'=>'on-line'}}}}
+  {'cpu_info'=>
+    {0=>
+    {'cpu_info0'=>
+      {'chip_id'=>0,
+       'fpu_type'=>'sparcv9',
+       'device_ID'=>0,
+       'cpu_type'=>'sparcv9',
+       'implementation'=>'Unknown',
+       'clock_MHz'=>502,
+       'state_begin'=>1105974702,
+       'state'=>'on-line'}}}}
    
 == Class Methods
 Kstat.new(module=nil, instance=-1, name=nil)
@@ -43,53 +43,48 @@ Kstat#record
    deeply that hash is nested depends on the values passed to the constructor.
    The more specific your criterion, the less data you will receive.
 
-== Error Classes
-Kstat::Error < StandardError
-   Raised if anything goes wrong. Typically this will only occur if you
-   pass bad arguments to the constructor e.g. a module name that doesn't
-   exist, etc.
-   
 == Unsupported names
-   The following names will not return any meaningful value:
+  The following names will not return any meaningful value:
 
-   * kstat_headers
-   * sfmmu_global_stat
-   * sfmmu_percpu_stat
+  * kstat_headers
+  * sfmmu_global_stat
+  * sfmmu_percpu_stat
    
-== Known Bugs
-   You may receive a couple warnings during the build process. You
-   can ignore these.
+== Known Issues
+  None at this time. Please report any issues on the project page at
+  https://github.com/djberg96/solaris-kstat
 
 == Designer's Notes
-   I have noticed that results from the cpu_stat module differ from the output
-   of the 'kstat' command line tool. I am convinced that my code is correct and
-   that there is a bug in the Solaris::Kstat Perl module. Unfortunately, the
-   source for the version of the Solaris::Kstat Perl module that works on
-   Solaris 8 and later is not available (the version on CPAN only works on
-   Solaris 6 and 7).
+  I have noticed that results from the cpu_stat module differ from the output
+  of the 'kstat' command line tool. I am convinced that my code is correct and
+  that there is a bug in the Solaris::Kstat Perl module. Unfortunately, the
+  source for the version of the Solaris::Kstat Perl module that works on
+  Solaris 8 and later is not available (the version on CPAN only works on
+  Solaris 6 and 7).
 
-   See http://tinyurl.com/karxw for more details.
+  See http://tinyurl.com/karxw for more details.
    
 == Acknowledgements
-   Thanks go to Charlie Mills for help with the 'volatile' issue.
+  Thanks go to Charlie Mills for help with the 'volatile' issue for the
+  original C code.
 
 == Future Plans
-   Add snaptime and crtime information to the statistics hash.
+  Add snaptime and crtime information to the statistics hash.
    
 == License
-   Artistic 2.0
+  Artistic 2.0
 
 == Copyright
-   (C) 2003-2011 Daniel J. Berger
-   All Rights Reserved
+  (C) 2003-2013 Daniel J. Berger
+  All Rights Reserved
     
 == Warranty
-   This package is provided "as is" and without any express or
-   implied warranties, including, without limitation, the implied
-   warranties of merchantability and fitness for a particular purpose.
+  This package is provided "as is" and without any express or
+  implied warranties, including, without limitation, the implied
+  warranties of merchantability and fitness for a particular purpose.
 	 
 == Author
-   Daniel J. Berger
+  Daniel J. Berger
     
 == See Also
-   kstat(1M)
+  kstat(1M)

data/Rakefile

@@ -2,36 +2,27 @@ require 'rake'
 require 'rake/clean'
 require 'rake/testtask'
 require 'rbconfig'
-include Config
 
 CLEAN.include(
-  '**/*.gem',               # Gem files
-  '**/*.rbc',               # Rubinius
-  '**/*.o',                 # C object file
-  '**/*.log',               # Ruby extension build log
-  '**/Makefile',            # C Makefile
-  '**/conftest.dSYM',       # OS X build directory
-  "**/*.#{CONFIG['DLEXT']}" # C shared object
+  '**/*.gem', # Gem files
+  '**/*.rbc', # Rubinius
+  '**/*.rbx'  # Rubinius
 )
 
-desc "Build the solaris-kstat source"
-task :build do
-  Dir.chdir('ext') do
-    ruby 'extconf.rb'
-    sh 'make'
-    cp 'kstat.so', 'solaris'
-  end
-end
-
 namespace :gem do
   desc "Create the solaris-kstat gem"
   task :create => [:clean] do
     spec = eval(IO.read('solaris-kstat.gemspec'))
-    Gem::Builder.new(spec).build
+    if Gem::VERSION < "2.0.0"
+      Gem::Builder.new(spec).build
+    else
+      require 'rubygems/package'
+      Gem::Package.build(spec)
+    end
   end
 
   desc "Install the solaris-kstat gem"
-  task :install => [:build] do
+  task :install => [:create] do
     ruby 'solaris-kstat.gemspec'
     file = Dir["*.gem"].first
     sh "gem install #{file}"
@@ -39,15 +30,30 @@ namespace :gem do
 end
 
 desc "Run the example program"
-task :example => [:build] do
-  ruby "-Iext examples/example_kstat.rb"
+task :example do
+  ruby "-Ilib examples/example_kstat.rb"
 end
 
-Rake::TestTask.new do |t|
-  task :test => [:build]
-  t.libs << 'ext'
-  t.verbose = true
-  t.warning = true
+namespace :test do
+  desc "Run base tests"
+  Rake::TestTask.new(:base) do |t|
+    t.test_files = FileList['test/test_solaris_kstat.rb']
+    t.verbose = true
+    t.warning = true
+  end
+
+  desc "Run FFI struct tests"
+  Rake::TestTask.new(:structs) do |t|
+    t.test_files = FileList['test/test_solaris_kstat_structs.rb']
+    t.verbose = true
+    t.warning = true
+  end
+
+  desc "Run all tests"
+  Rake::TestTask.new(:all) do |t|
+    t.verbose = true
+    t.warning = true
+  end
 end
 
-task :default => :test
+task :default => "test:all"

data/lib/solaris/kstat.rb

@@ -0,0 +1,321 @@
+require File.join(File.dirname(__FILE__), 'kstat', 'structs')
+require File.join(File.dirname(__FILE__), 'kstat', 'functions')
+
+module Solaris
+  class Kstat
+    extend FFI::Library
+    include Solaris::Structs
+    include Solaris::Functions
+
+    # The version of the solaris-kstat library
+    VERSION = '1.1.0'
+
+    # The kstat module
+    attr_accessor :module
+
+    # The kstat instance number
+    attr_accessor :instance
+
+    # The kstat name
+    attr_accessor :name
+
+    # Creates and returns a Kstat object. This does NOT traverse the kstat
+    # chain. The Kstat#record method uses the values passed to actually
+    # retrieve data.
+    #
+    # You may specify a module, an instance and a name.  The module defaults to
+    # nil (all modules), the instance defaults to -1 (all instances) and the
+    # name defaults to nil (all names).
+    #
+    # Examples:
+    #
+    #   require 'solaris/kstat'
+    #   include Kstat
+    #
+    #   k1 = Kstat.new                    # Everything
+    #   k2 = Kstat.new('cpu')             # Just CPU info
+    #   k3 = Kstat.new('cpu', 0)          # Just CPU info for instance 0
+    #   k4 = Kstat.new('cpu', 0, 'sys')   # CPU info for instance 0 named 'sys'
+    #
+    def initialize(mod=nil, instance=-1, name=nil)
+      # Type checking added since invalid values could cause a segfault later on.
+      raise TypeError unless mod.is_a?(String) if mod
+      raise TypeError unless instance.is_a?(Fixnum)
+      raise TypeError unless name.is_a?(String) if name
+
+      @module   = mod
+      @instance = instance
+      @name     = name
+    end
+
+    # Returns a nested hash based on the values passed to the constructor.  How
+    # deeply that hash is nested depends on the values passed to the constructor.
+    # The more specific your criterion, the less data you will receive.
+    #
+    def record
+      kptr = kstat_open()
+
+      if kptr.null?
+        raise SystemCallError.new('kstat_open', FFI.errno)
+      end
+
+      kstat = kstat_lookup(kptr, @module, @instance, @name)
+
+      if kstat.null?
+        kstat_close(kptr)
+        raise SystemCallError.new('kstat_lookup', FFI.errno)
+      end
+
+      mhash = {} # Holds modules
+      ihash = {} # Holds instances
+      nhash = {} # Holds names
+      shash = {} # Subhash for names
+
+      # Sync the chain with the kernel
+      if kstat_chain_update(kptr) < 0
+        raise SystemCallError.new('kstat_chain_update', FFI.errno)
+      end
+
+      begin
+        while !kstat.null?
+          break if kstat[:ks_next].null?
+
+          if @module && @module != kstat[:ks_module].to_s
+            kstat = KstatStruct.new(kstat[:ks_next])
+            next
+          end
+
+          if @instance != -1 && @instance != kstat[:ks_instance]
+            kstat = KstatStruct.new(kstat[:ks_next])
+            next
+          end
+
+          if @name && @name != kstat[:ks_name].to_s
+            kstat = KstatStruct.new(kstat[:ks_next])
+            next
+          end
+
+          if kstat_read(kptr, kstat, nil) < 0
+            raise SystemCallError.new('kstat_read', FFI.errno)
+          end
+
+          case kstat[:ks_type]
+            when 0 # KSTAT_TYPE_RAW
+              shash = map_raw_data_type(kstat)
+            when 1 # KS_TYPE_NAMED
+              shash = map_named_data_type(kstat)
+            when 2 # KS_TYPE_INTR
+              shash = map_intr_data_type(kstat)
+            when 3 # KS_TYPE_IO
+              shash = map_io_data_type(kstat)
+            when 4 # KS_TYPE_TIMER
+              shash = map_timer_data_type(kstat)
+            else
+              raise ArgumentError, 'unknown data record type'
+          end
+
+          # The various calls to .to_s here and elsewhere are necessary
+          # to convert FFI's CharArray to Ruby strings.
+
+          shash['class'] = kstat[:ks_class].to_s
+
+          ks_name = kstat[:ks_name].to_s
+          ks_instance = kstat[:ks_instance]
+          ks_module = kstat[:ks_module].to_s
+
+          nhash[ks_name]     = shash
+          ihash[ks_instance] = nhash
+          mhash[ks_module]   = ihash
+
+          kstat = KstatStruct.new(kstat[:ks_next])
+        end
+      ensure
+        kstat_close(kptr)
+      end
+
+      mhash
+    end # record
+
+    private
+
+    def map_timer_data_type(kstat)
+      hash = {}
+
+      ktimer = KstatTimer.new(kstat[:ks_data])
+
+      ktime.members.each{ |m|
+        if m == :name
+          hash['name'] = ktimer[:name].to_s
+        else
+          hash[m.to_s] = ktimer[m]
+        end
+      }
+
+      hash
+    end
+
+    def map_io_data_type(kstat)
+      hash = {}
+
+      kio = KstatIo.new(kstat[:ks_data])
+      kio.members.each{ |m| hash[m.to_s] = kio[m] }
+
+      hash
+    end
+
+    def map_intr_data_type(kstat)
+      hash  = {}
+      names = %w[hard soft watchdog spurious multiple_service]
+
+      0.upto(4){ |i|
+        ksi = KstatIntr.new(kstat[:ks_data] + (i * KstatIntr.size))
+        hash[names[i]] = ksi[:intrs][i]
+      }
+
+      hash
+    end
+
+    def map_raw_data_type(kstat)
+      hash = {}
+
+      if kstat[:ks_module].to_s == 'unix'
+        case kstat[:ks_name].to_s
+          when 'vminfo'
+            hash = map_raw_vminfo(kstat)
+          when 'flushmeter'
+            hash = map_raw_flushmeter(kstat)
+          when 'ncstats'
+            hash = map_raw_ncstats(kstat)
+          when 'sysinfo'
+            hash = map_raw_sysinfo(kstat)
+          when 'var'
+            hash = map_raw_var(kstat)
+        end
+      end
+
+      if kstat[:ks_module].to_s == 'cpu_stat'
+        hash = map_raw_cpu_sysinfo(kstat)
+      end
+
+      if kstat[:ks_module].to_s == 'nfs'
+        if kstat[:ks_name].to_s == 'mntinfo'
+          hash = map_raw_mnt_info(kstat)
+        end
+      end
+
+      hash
+    end
+
+    def map_raw_mnt_info(kstat)
+      hash = {}
+
+      mntinfo = Mntinfo.new(kstat[:ks_data])
+
+      mntinfo.members.each{ |m|
+        next if m == :mik_timers # TODO: Add this information
+        if [:mik_proto, :mik_curserver].include?(m)
+          hash[m.to_s] = mntinfo[m].to_s
+        else
+          hash[m.to_s] = mntinfo[m]
+        end
+      }
+
+      hash
+    end
+
+    def map_raw_cpu_sysinfo(kstat)
+      hash = {}
+
+      info = CpuSysinfo.new(kstat[:ks_data])
+
+      info.members.each{ |m|
+        if m == :cpu
+          hash['cpu_idle']   = info[:cpu][0]
+          hash['cpu_user']   = info[:cpu][1]
+          hash['cpu_kernel'] = info[:cpu][2]
+          hash['cpu_wait']   = info[:cpu][3]
+        elsif m == :wait
+          hash['wait_io']   = info[:wait][0]
+          hash['wait_swap'] = info[:wait][1]
+          hash['wait_pio']  = info[:wait][2]
+        else
+          hash[m.to_s] = info[m]
+        end
+      }
+
+      hash
+    end
+
+    def map_raw_vminfo(kstat)
+      hash = {}
+
+      vmi = Vminfo.new(kstat[:ks_data])
+      vmi.members.each{ |m| hash[m.to_s] = vmi[m] }
+
+      hash
+    end
+
+    def map_raw_flushmeter(kstat)
+      hash = {}
+
+      fm = Flushmeter.new(kstat[:ks_data])
+      fm.members.each{ |m| hash[m.to_s] = fm[m] }
+
+      hash
+    end
+
+    def map_raw_ncstats(kstat)
+      hash = {}
+
+      ncs = NcStats.new(kstat[:ks_data])
+      ncs.members.each{ |m| hash[m.to_s] = ncs[m] }
+
+      hash
+    end
+
+    def map_raw_sysinfo(kstat)
+      hash = {}
+
+      sys = Sysinfo.new(kstat[:ks_data])
+      sys.members.each{ |m| hash[m.to_s] = sys[m] }
+
+      hash
+    end
+
+    def map_raw_var(kstat)
+      hash = {}
+
+      var = Var.new(kstat[:ks_data])
+      var.members.each{ |m| hash[m.to_s] = var[m] }
+
+      hash
+    end
+
+    def map_named_data_type(kstat)
+      num = kstat[:ks_ndata]
+      hash = {}
+
+      0.upto(num-1){ |i|
+        knp = KstatNamed.new(kstat[:ks_data] + (i * KstatNamed.size))
+        name = knp[:name].to_s
+
+        case knp[:data_type]
+          when 0 # KSTAT_DATA_CHAR
+            hash[name] = knp[:value][:c].to_s
+          when 1 # KSTAT_DATA_INT32
+            hash[name] = knp[:value][:i32]
+          when 2 # KSTAT_DATA_UINT32
+            hash[name] = knp[:value][:ui32]
+          when 3 # KSTAT_DATA_INT64
+            hash[name] = knp[:value][:i64]
+          when 4 # KSTAT_DATA_UINT64
+            hash[name] = knp[:value][:ui64]
+          else
+            hash[name] = "unknown"
+        end
+      }
+
+      hash
+    end
+  end # Kstat
+end # Solaris