na_str 0.1.0

data/Makefile

@@ -0,0 +1,132 @@
+
+SHELL = /bin/sh
+
+#### Start of system configuration section. ####
+
+srcdir = .
+topdir = $(rubylibdir)/$(arch)
+hdrdir = $(rubylibdir)/$(arch)
+VPATH = $(srcdir)
+prefix = $(DESTDIR)/dmsp/reference/ruby-1.8.1/
+exec_prefix = $(prefix)
+sitedir = $(prefix)/lib/ruby/site_ruby
+rubylibdir = $(libdir)/ruby/$(ruby_version)
+builddir = $(ac_builddir)
+archdir = $(rubylibdir)/$(arch)
+sbindir = $(exec_prefix)/sbin
+compile_dir = $(DESTDIR)/dmsp/moby-1-1/reference/build/ruby-1.8.1
+datadir = $(prefix)/share
+includedir = $(prefix)/include
+infodir = $(prefix)/info
+top_builddir = $(ac_top_builddir)
+sysconfdir = $(prefix)/etc
+mandir = $(prefix)/man
+libdir = $(exec_prefix)/lib
+sharedstatedir = $(prefix)/com
+oldincludedir = $(DESTDIR)/usr/include
+sitearchdir = $(sitelibdir)/$(sitearch)
+bindir = $(exec_prefix)/bin
+localstatedir = $(prefix)/var
+sitelibdir = $(sitedir)/$(ruby_version)
+libexecdir = $(exec_prefix)/libexec
+
+CC = gcc
+LIBRUBY = $(LIBRUBY_A)
+LIBRUBY_A = lib$(RUBY_SO_NAME)-static.a
+LIBRUBYARG_SHARED = 
+LIBRUBYARG_STATIC = -l$(RUBY_SO_NAME)-static
+
+CFLAGS   =  -fPIC -g -O2 -I /dmsp/reference/ruby-1.8.1//lib/ruby/site_ruby/1.8/i686-linux  
+CPPFLAGS = -I. -I$(topdir) -I$(hdrdir) -I$(srcdir)  
+CXXFLAGS = $(CFLAGS) 
+DLDFLAGS =  /dmsp/reference/ruby-1.8.1//lib/ruby/site_ruby/1.8/i686-linux/narray.so   
+LDSHARED = gcc -shared
+AR = ar
+EXEEXT = 
+
+RUBY_INSTALL_NAME = ruby
+RUBY_SO_NAME = $(RUBY_INSTALL_NAME)
+arch = i686-linux
+sitearch = i686-linux
+ruby_version = 1.8
+RUBY = ruby
+RM = $(RUBY) -run -e rm -- -f
+MAKEDIRS = $(RUBY) -run -e mkdir -- -p
+INSTALL_PROG = $(RUBY) -run -e install -- -vpm 0755
+INSTALL_DATA = $(RUBY) -run -e install -- -vpm 0644
+
+#### End of system configuration section. ####
+
+
+LIBPATH =  -L"$(libdir)"
+DEFFILE = 
+
+CLEANFILES = 
+DISTCLEANFILES = 
+
+target_prefix = 
+LOCAL_LIBS = 
+LIBS =   -ldl -lcrypt -lm   -lc
+OBJS = na_str.o
+TARGET = na_str
+DLLIB = $(TARGET).so
+STATIC_LIB = $(TARGET).a
+
+RUBYCOMMONDIR = $(sitedir)$(target_prefix)
+RUBYLIBDIR    = $(sitelibdir)$(target_prefix)
+RUBYARCHDIR   = $(sitearchdir)$(target_prefix)
+
+CLEANLIBS     = "$(TARGET).{lib,exp,il?,tds,map}" $(DLLIB)
+CLEANOBJS     = "*.{o,a,s[ol],pdb,bak}"
+
+all:		$(DLLIB)
+static:		$(STATIC_LIB)
+
+clean:
+		@$(RM) $(CLEANLIBS) $(CLEANOBJS) $(CLEANFILES)
+
+distclean:	clean
+		@$(RM) Makefile extconf.h conftest.* mkmf.log
+		@$(RM) core ruby$(EXEEXT) *~ $(DISTCLEANFILES)
+
+realclean:	distclean
+install: $(RUBYARCHDIR)
+install: $(RUBYARCHDIR)/$(DLLIB)
+$(RUBYARCHDIR)/$(DLLIB): $(DLLIB) $(RUBYARCHDIR)
+	@$(INSTALL_PROG) $(DLLIB) $(RUBYARCHDIR)
+install: $(RUBYLIBDIR)
+install: $(RUBYLIBDIR)/nmap.rb
+$(RUBYLIBDIR)/nmap.rb: $(srcdir)/lib/nmap.rb $(RUBYLIBDIR)
+	@$(INSTALL_DATA) $(srcdir)/lib/nmap.rb $(RUBYLIBDIR)
+$(RUBYARCHDIR):
+	@$(MAKEDIRS) $(RUBYARCHDIR)
+$(RUBYLIBDIR):
+	@$(MAKEDIRS) $(RUBYLIBDIR)
+
+site-install: install
+
+.SUFFIXES: .c .cc .m .cxx .cpp .C .o
+
+.cc.o:
+	$(CXX) $(CXXFLAGS) $(CPPFLAGS) -c $<
+
+.cpp.o:
+	$(CXX) $(CXXFLAGS) $(CPPFLAGS) -c $<
+
+.cxx.o:
+	$(CXX) $(CXXFLAGS) $(CPPFLAGS) -c $<
+
+.C.o:
+	$(CXX) $(CXXFLAGS) $(CPPFLAGS) -c $<
+
+.c.o:
+	$(CC) $(CFLAGS) $(CPPFLAGS) -c $<
+
+$(DLLIB): $(OBJS)
+	@-$(RM) $@
+	$(LDSHARED) $(DLDFLAGS) $(LIBPATH) -o $(DLLIB) $(OBJS) $(LOCAL_LIBS) $(LIBS)
+
+$(STATIC_LIB): $(OBJS)
+	$(AR) cru $@ $(OBJS)
+	@-ranlib $(DLLIB) 2> /dev/null || true
+

data/README

@@ -0,0 +1,103 @@
+NAME
+
+  na_str (c extension)
+
+  nmap (reference ruby class which combines narray and mmap)
+
+
+URIS
+
+  http://codeforpeople.com/lib/ruby/na_str/
+
+
+SYNOPSIS
+
+  na_str is designed to allow data sharing between narray object and other ruby
+  objects.  the shared data is that returned by the objects to_s or to_str method
+  and rb_string_new4.  using this technique memory mapped (using guy's mmap
+  extensions) data can be altered with no explicit io on the users part and
+  partial changed to numerical grids can occur very quickly and persistently.
+
+  the nmap.rb reference impl is a concrete example of this usage and is
+  included in the distribution
+
+
+EXAMPLE USAGE
+
+    jib:~/eg/ruby/na_str > cat a.rb
+    #
+    # the nmap extension is installed along with na_str
+    #
+      require 'nmap'
+    #
+    # the NMap ctor interface is similar to NArray's, but a backing file must also
+    # be specified
+    #
+      path, x, y = 'int.data', 3, 4
+      nmap = NMap.int path, x, y 
+    #
+    # copy the last row to the first
+    #
+      nmap.na[true, 0] = nmap.na[true, 3]
+    #
+    # set the last row to be the current time.  if you run this a few times you'll
+    # notice that changes to the narray are automatically written to the to
+    # backing file via the magic of mmap
+    #
+      nmap.na[true, 3] = Time.now.to_i
+    #
+    # show the narray
+    #
+      p nmap.na
+  
+
+  jib:~/eg/ruby/na_str > ruby a.rb
+  NArray(ref).int(3,4):
+  [ [ 0, 0, 0 ],
+    [ 0, 0, 0 ],
+    [ 0, 0, 0 ],
+    [ 1151439012, 1151439012, 1151439012 ] ]
+
+  jib:~/eg/ruby/na_str > ruby a.rb
+  NArray(ref).int(3,4):
+  [ [ 1151439012, 1151439012, 1151439012 ],
+    [ 0, 0, 0 ],
+    [ 0, 0, 0 ],
+    [ 1151439014, 1151439014, 1151439014 ] ]
+
+
+SPEED
+
+  jib:~/eg/ruby/na_str > cat a.rb
+  #
+  # reference impl installed with na_str
+  #
+    require 'nmap'
+  #
+  # setup a narray grid containing 1 gb of ints
+  #
+    gb = 2 ** 30
+    mb = 2 ** 20
+    sizeof_int = [42].pack('i').size
+    gig_of_ints = gb / sizeof_int
+    nmap = NMap.int '1GB',  gig_of_ints
+  #
+  # set about 1 million of the ints to 42
+  #
+    nmap.na[0 .. mb] = 42
+  #
+  # show that the data was written
+  #
+    p nmap.na[mb - 1]
+
+
+  jib:~/eg/ruby/na_str > time ruby a.rb
+  42
+  
+  real    0m0.078s
+  user    0m0.020s
+  sys     0m0.020s
+
+
+  jib:~/eg/ruby/na_str > ls -ltar 1GB
+  -rw-rw-r--    1 ahoward  ahoward  1073741824 Jun 27 14:28 1GB

data/extconf.rb

@@ -0,0 +1,9 @@
+require "mkmf"
+require "rbconfig"
+
+sitearchdir = Config::CONFIG["sitearchdir"]
+
+$CFLAGS += " -I #{ sitearchdir } "
+$LDFLAGS += " #{ sitearchdir }/narray.so " # force a link so narray.so symbols will be resolved
+
+create_makefile "na_str"

data/gemspec.rb

@@ -0,0 +1,30 @@
+
+lib, version = File::basename(File::dirname(File::expand_path(__FILE__))).split %r/-/, 2
+
+require 'rubygems'
+
+Gem::Specification::new do |spec|
+  $VERBOSE = nil
+  spec.name = lib 
+  spec.version = version 
+  spec.platform = Gem::Platform::RUBY
+  spec.summary = lib 
+
+  spec.files = Dir::glob "**/**"
+  spec.executables = Dir::glob("bin/*").map{|exe| File::basename exe}
+  
+  spec.require_path = "lib" 
+  spec.autorequire = lib
+
+  spec.has_rdoc = File::exist? "doc" 
+  spec.test_suite_file = "test/#{ lib }.rb" if File::directory? "test"
+
+  spec.extensions << "extconf.rb" if File::exists? "extconf.rb"
+
+  spec.author = "Ara T. Howard"
+  spec.email = "ara.t.howard@noaa.gov"
+  spec.homepage = "http://codeforpeople.com/lib/ruby/#{ lib }/"
+
+  spec.requirements << "http://moulon.inra.fr/ruby/mmap.html"
+  spec.requirements << "http://narray.rubyforge.org/"
+end

data/install.rb

@@ -0,0 +1,210 @@
+#!/usr/bin/env ruby
+require 'rbconfig'
+require 'find'
+require 'ftools'
+require 'tempfile'
+include Config
+
+LIBDIR      = "lib"
+LIBDIR_MODE = 0644
+
+BINDIR      = "bin"
+BINDIR_MODE = 0755
+
+
+$srcdir            = CONFIG["srcdir"]
+$version           = CONFIG["MAJOR"]+"."+CONFIG["MINOR"]
+$libdir            = File.join(CONFIG["libdir"], "ruby", $version)
+$archdir           = File.join($libdir, CONFIG["arch"])
+$site_libdir       = $:.find {|x| x =~ /site_ruby$/}
+$bindir            = CONFIG["bindir"] || CONFIG['BINDIR']
+$ruby_install_name = CONFIG['ruby_install_name'] || CONFIG['RUBY_INSTALL_NAME'] || 'ruby'
+$ruby_ext          = CONFIG['EXEEXT'] || ''
+$ruby              = File.join($bindir, ($ruby_install_name + $ruby_ext))
+
+if !$site_libdir
+  $site_libdir = File.join($libdir, "site_ruby")
+elsif $site_libdir !~ %r/#{Regexp.quote($version)}/
+  $site_libdir = File.join($site_libdir, $version)
+end
+
+def install_rb(srcdir=nil, destdir=nil, mode=nil, bin=nil)
+#{{{
+  path   = []
+  dir    = []
+  Find.find(srcdir) do |f|
+    next unless FileTest.file?(f)
+    next if (f = f[srcdir.length+1..-1]) == nil
+    next if (/CVS$/ =~ File.dirname(f))
+    next if f =~ %r/\.lnk/
+    path.push f
+    dir |= [File.dirname(f)]
+  end
+  for f in dir
+    next if f == "."
+    next if f == "CVS"
+    File::makedirs(File.join(destdir, f))
+  end
+  for f in path
+    next if (/\~$/ =~ f)
+    next if (/^\./ =~ File.basename(f))
+    unless bin
+      File::install(File.join(srcdir, f), File.join(destdir, f), mode, true)
+    else
+      from = File.join(srcdir, f)
+      to = File.join(destdir, f)
+      shebangify(from) do |sf|
+        $deferr.print from, " -> ", File::catname(from, to), "\n"
+        $deferr.printf "chmod %04o %s\n", mode, to 
+        File::install(sf, to, mode, false)
+      end
+    end
+  end
+#}}}
+end
+def shebangify f
+#{{{
+  open(f) do |fd|
+    buf = fd.read 42 
+    if buf =~ %r/^\s*#\s*!.*ruby/o
+      ftmp = Tempfile::new("#{ $$ }_#{ File::basename(f) }")
+      begin
+        fd.rewind
+        ftmp.puts "#!#{ $ruby  }"
+        while((buf = fd.read(8192)))
+          ftmp.write buf
+        end
+        ftmp.close
+        yield ftmp.path
+      ensure
+        ftmp.close!
+      end
+    else
+      yield f
+    end
+  end
+#}}}
+end
+def ARGV.switch
+#{{{
+  return nil if self.empty?
+  arg = self.shift
+  return nil if arg == '--'
+  if arg =~ /^-(.)(.*)/
+    return arg if $1 == '-'
+    raise 'unknown switch "-"' if $2.index('-')
+    self.unshift "-#{$2}" if $2.size > 0
+    "-#{$1}"
+  else
+    self.unshift arg
+    nil
+  end
+#}}}
+end
+def ARGV.req_arg
+#{{{
+  self.shift || raise('missing argument')
+#}}}
+end
+def linkify d, linked = []
+#--{{{
+  if test ?d, d
+    versioned = Dir[ File::join(d, "*-[0-9].[0-9].[0-9].rb") ]
+    versioned.each do |v| 
+      src, dst = v, v.gsub(%r/\-[\d\.]+\.rb$/, '.rb')
+      lnk = nil
+      begin
+        if test ?l, dst
+          lnk = "#{ dst }.lnk"
+          puts "#{ dst } -> #{ lnk }"
+          File::rename dst, lnk
+        end
+        unless test ?e, dst
+          puts "#{ src } -> #{ dst }"
+          File::copy src, dst 
+          linked << dst
+        end
+      ensure
+        if lnk
+          at_exit do
+            puts "#{ lnk } -> #{ dst }"
+            File::rename lnk, dst
+          end
+        end
+      end
+    end
+  end
+  linked
+#--}}}
+end
+
+
+#
+# main program
+#
+
+libdir = $site_libdir
+bindir = $bindir
+no_linkify = false
+linked = nil
+help = false
+
+usage = <<-usage
+  #{ File::basename $0 }
+    -d, --destdir    <destdir>
+    -l, --libdir     <libdir>
+    -b, --bindir     <bindir>
+    -r, --ruby       <ruby>
+    -n, --no_linkify
+    -s, --sudo
+    -h, --help
+usage
+
+begin
+  while switch = ARGV.switch
+    case switch
+    when '-d', '--destdir'
+      libdir = ARGV.req_arg
+    when '-l', '--libdir'
+      libdir = ARGV.req_arg
+    when '-b', '--bindir'
+      bindir = ARGV.req_arg
+    when '-r', '--ruby'
+      $ruby = ARGV.req_arg
+    when '-n', '--no_linkify'
+      no_linkify = true
+    when '-s', '--sudo'
+      sudo = 'sudo' 
+    when '-h', '--help'
+      help = true
+    else
+      raise "unknown switch #{switch.dump}"
+    end
+  end
+rescue
+  STDERR.puts $!.to_s
+  STDERR.puts usage
+  exit 1
+end    
+
+if help
+  STDOUT.puts usage
+  exit
+end
+
+system "#{ sudo } #{ $ruby } pre-install.rb" if test(?s, 'pre-install.rb')
+
+unless no_linkify
+  linked = linkify('lib') + linkify('bin')
+end
+
+system "#{ $ruby } extconf.rb && make && #{ sudo } make install" if test(?s, 'extconf.rb')
+
+install_rb(LIBDIR, libdir, LIBDIR_MODE)
+install_rb(BINDIR, bindir, BINDIR_MODE, bin=true)
+
+if linked
+  linked.each{|path| File::rm_f path}
+end
+
+system "#{ sudo } #{ $ruby } post-install.rb" if test(?s, 'post-install.rb')

data/lib/nmap.rb

@@ -0,0 +1,198 @@
+#
+# built-in
+#
+  require "yaml"
+#
+# rubyforge.org/raa.ruby-lang.org
+#
+  require "mmap"
+  require "narray"
+#
+# homegrown 
+#
+  require "na_str"
+#
+# here we creates a little convenience class for working with memory mapped
+# numerical grids
+#
+  class NMap
+    module Util
+      def string_of obj
+        obj.to_str
+      rescue
+        raise ArgumentError, "cannot convert <#{ obj.inspect }> to string"
+      end
+
+      def int_of obj
+        Integer obj
+      rescue
+        raise ArgumentError, "cannot convert <#{ obj.inspect }> to int"
+      end
+
+      def int_list_of obj
+        [*obj].flatten.map{|elem| int_of elem}
+      rescue
+        raise ArgumentError, "cannot convert <#{ obj.inspect }> to int list"
+      end
+    end
+
+    class Header < ::Hash
+      include Util
+
+      def initialize path, *argv
+        @path = string_of path
+
+        self.na_type = argv.shift
+        self.shape = argv
+
+        self.na_type = int_of na_type if na_type 
+        self.shape = int_list_of shape if shape
+
+        init! if na_type and shape
+
+        load!
+      end
+
+      def init!
+        open(@path, "w"){|f| ::YAML::dump(({}.update self), f)}
+      end
+
+      def load!
+        self.update(open(@path){|f| ::YAML::load f})
+      end
+
+      def na_type
+        self["na_type"]
+      end
+
+      def na_type= val
+        self["na_type"] = val
+      end
+
+      def shape
+        self["shape"]
+      end
+
+      def shape= val
+        self["shape"] = val
+      end
+
+      def self.init(*a, &b) new(*a, &b) end
+    end
+
+    include Util
+
+    attr "path"
+    attr "na_type"
+    attr "shape"
+    attr "lockfile"
+    attr "header"
+    attr "na"
+    attr "closed"
+
+    def initialize path, *argv 
+      @path = string_of path
+
+      @na_type = argv.shift
+      @shape = argv
+
+      @na_type = int_of @na_type if @na_type 
+      @shape = int_list_of @shape if @shape
+
+      @lockfile = @path + '.lock'
+      
+      locked do
+        init! unless test ?s, @path
+        load_header!
+        load!
+      end
+
+      @closed = false
+
+      if block_given?
+        begin
+          yield self
+        ensure
+          close
+        end
+      end
+    end
+
+    def init!
+      raise ArgumentError, "no na_type" unless @na_type
+      raise ArgumentError, "no shape" unless @shape
+      sizeof_type = NArray::new(@na_type, 1).to_s.size
+      size = @shape.inject(1){|product, dim| product *= dim}
+      pos = sizeof_type * size
+      File.unlink @path rescue nil
+      open(@path, File::CREAT|File::EXCL|File::RDWR){|f| f.truncate pos}
+      Header::init @path + '.nmap', @na_type, @shape
+    end
+
+    def load_header!
+      @header = Header::new @path + '.nmap' 
+      @na_type = @header.na_type
+      @shape = @header.shape
+    end
+
+    def load!
+      @mmap = ::Mmap::new @path, "rw", Mmap::MAP_SHARED
+      @na = ::NArray::str @mmap, @na_type, *@shape
+    end
+
+    def locked
+      f = open @lockfile, 'a+'
+      f.flock File::LOCK_EX
+      yield
+    ensure
+      if f
+        f.flock File::LOCK_UN rescue nil
+        f.close rescue nil
+      end
+    end
+
+    def sync
+      @mmap.msync
+    end
+
+    def close
+      return if @closed
+      sync
+      @mmap.munmap
+      @mmap = nil
+      @na = nil
+      @closed = true
+    end
+
+    class << self
+      def init(*a, &b) new(*a, &b) end
+      ctors = ::NArray.constants.select{|c| ::NArray.respond_to? c.downcase}
+      ctors.each do |m|
+        module_eval <<-code
+          def #{ m.downcase }(path, *argv)
+            new path, NArray::#{ m }, *argv
+          end
+        code
+      end
+    end
+  end
+
+#
+# sample usage - be sure to run more than once!!
+#
+  if $0 == __FILE__
+    require 'tmpdir'
+    require 'yaml'
+
+    ipath = File.join Dir.tmpdir, 'i.na'
+
+    t, f = true, false
+
+    nmap = NMap.int ipath, 3,4 
+    na = nmap.na
+    p na
+    na[t,0] = 42
+    na[0,t] = Time.now.to_i
+    p na
+
+  end

data/na_str.c

@@ -0,0 +1,67 @@
+#include <ruby.h>
+#include <version.h>
+#include "narray.h"
+#include "narray_config.h"
+
+static VALUE
+str_new4 (VALUE str)
+{
+  StringValue (str);
+  if (FL_TEST (str, ELTS_SHARED))
+    {
+      rb_str_buf_cat2 (str, "");	/* unanchor literal string */
+    }
+  return rb_str_new4 (str);
+}
+
+static VALUE
+na_s_str (int argc, VALUE * argv, VALUE klass)
+{
+  struct NARRAY *ary;
+  VALUE v;
+  VALUE str;
+  int i, type, len = 1, str_len, *shape, rank = argc - 2;
+
+  if (argc < 1)
+    rb_raise (rb_eArgError, "String Argument required");
+
+  if (argc < 2)
+    rb_raise (rb_eArgError, "Type and Size Arguments required");
+
+  type = na_get_typecode (argv[1]);
+  str = str_new4 (argv[0]);
+  str_len = RSTRING (str)->len;
+
+  if (argc == 2)
+    {
+      rank = 1;
+      shape = ALLOCA_N (int, rank);
+      if (str_len % na_sizeof[type] != 0)
+	rb_raise (rb_eArgError, "string size mismatch");
+      shape[0] = str_len / na_sizeof[type];
+    }
+  else
+    {
+      shape = ALLOCA_N (int, rank);
+      for (i = 0; i < rank; i++)
+	len *= shape[i] = NUM2INT (argv[i + 2]);
+      len *= na_sizeof[type];
+      if (len != str_len)
+	rb_raise (rb_eArgError, "size mismatch");
+    }
+
+  v = na_make_object (type, rank, shape, cNArray);
+  GetNArray (v, ary);
+  ary->ptr = RSTRING (str)->ptr;
+  ary->ref = str;
+
+  return v;
+}
+
+void
+Init_na_str ()
+{
+  rb_require ("narray");
+  rb_define_singleton_method (cNArray, "str", na_s_str, -1);
+  rb_define_singleton_method (cNArray, "from_string", na_s_str, -1);
+}

data/nmap.rb

@@ -0,0 +1,198 @@
+#
+# built-in
+#
+  require "yaml"
+#
+# rubyforge.org/raa.ruby-lang.org
+#
+  require "mmap"
+  require "narray"
+#
+# homegrown 
+#
+  require "na_str"
+#
+# here we creates a little convenience class for working with memory mapped
+# numerical grids
+#
+  class NMap
+    module Util
+      def string_of obj
+        obj.to_str
+      rescue
+        raise ArgumentError, "cannot convert <#{ obj.inspect }> to string"
+      end
+
+      def int_of obj
+        Integer obj
+      rescue
+        raise ArgumentError, "cannot convert <#{ obj.inspect }> to int"
+      end
+
+      def int_list_of obj
+        [*obj].flatten.map{|elem| int_of elem}
+      rescue
+        raise ArgumentError, "cannot convert <#{ obj.inspect }> to int list"
+      end
+    end
+
+    class Header < ::Hash
+      include Util
+
+      def initialize path, *argv
+        @path = string_of path
+
+        self.na_type = argv.shift
+        self.shape = argv
+
+        self.na_type = int_of na_type if na_type 
+        self.shape = int_list_of shape if shape
+
+        init! if na_type and shape
+
+        load!
+      end
+
+      def init!
+        open(@path, "w"){|f| ::YAML::dump(({}.update self), f)}
+      end
+
+      def load!
+        self.update(open(@path){|f| ::YAML::load f})
+      end
+
+      def na_type
+        self["na_type"]
+      end
+
+      def na_type= val
+        self["na_type"] = val
+      end
+
+      def shape
+        self["shape"]
+      end
+
+      def shape= val
+        self["shape"] = val
+      end
+
+      def self.init(*a, &b) new(*a, &b) end
+    end
+
+    include Util
+
+    attr "path"
+    attr "na_type"
+    attr "shape"
+    attr "lockfile"
+    attr "header"
+    attr "na"
+    attr "closed"
+
+    def initialize path, *argv 
+      @path = string_of path
+
+      @na_type = argv.shift
+      @shape = argv
+
+      @na_type = int_of @na_type if @na_type 
+      @shape = int_list_of @shape if @shape
+
+      @lockfile = @path + '.lock'
+      
+      locked do
+        init! unless test ?s, @path
+        load_header!
+        load!
+      end
+
+      @closed = false
+
+      if block_given?
+        begin
+          yield self
+        ensure
+          close
+        end
+      end
+    end
+
+    def init!
+      raise ArgumentError, "no na_type" unless @na_type
+      raise ArgumentError, "no shape" unless @shape
+      sizeof_type = NArray::new(@na_type, 1).to_s.size
+      size = @shape.inject(1){|product, dim| product *= dim}
+      pos = sizeof_type * size
+      File.unlink @path rescue nil
+      open(@path, File::CREAT|File::EXCL|File::RDWR){|f| f.truncate pos}
+      Header::init @path + '.yml', @na_type, @shape
+    end
+
+    def load_header!
+      @header = Header::new @path + '.yml' 
+      @na_type = @header.na_type
+      @shape = @header.shape
+    end
+
+    def load!
+      @mmap = ::Mmap::new @path, "rw", Mmap::MAP_SHARED
+      @na = ::NArray::str @mmap, @na_type, *@shape
+    end
+
+    def locked
+      f = open @lockfile, 'a+'
+      f.flock File::LOCK_EX
+      yield
+    ensure
+      if f
+        f.flock File::LOCK_UN rescue nil
+        f.close rescue nil
+      end
+    end
+
+    def sync
+      @mmap.msync
+    end
+
+    def close
+      return if @closed
+      sync
+      @mmap.munmap
+      @mmap = nil
+      @na = nil
+      @closed = true
+    end
+
+    class << self
+      def init(*a, &b) new(*a, &b) end
+      ctors = ::NArray.constants.select{|c| ::NArray.respond_to? c.downcase}
+      ctors.each do |m|
+        module_eval <<-code
+          def #{ m.downcase }(path, *argv)
+            new path, NArray::#{ m }, *argv
+          end
+        code
+      end
+    end
+  end
+
+#
+# sample usage - be sure to run more than once!!
+#
+  if $0 == __FILE__
+    require 'tmpdir'
+    require 'yaml'
+
+    ipath = File.join Dir.tmpdir, 'i.na'
+
+    t, f = true, false
+
+    nmap = NMap.int ipath, 3,4 
+    na = nmap.na
+    p na
+    na[t,0] = 42
+    na[0,t] = Time.now.to_i
+    p na
+
+  end

data/samples/a.rb

@@ -0,0 +1,18 @@
+%w( ./lib ../lib . ..).each{|d| $:.unshift d}
+require 'na_str'
+
+#
+# na_str allows you to share memory with any object that responds to to_s or
+# to_str.  the object whose memory is shared is frozen and cannot be modified
+# and a reference to the object is kept so it is not gc'd.  the object's
+# memory can be modified using this 'view' of the data.
+#
+
+buf = [0,0,0,0].pack 'i*'
+
+na = NArray::str buf, NArray::INT, 4
+na[0] = 42
+na[-1] = 42
+
+p buf.unpack('i*')
+p buf

data/samples/b.rb

@@ -0,0 +1,47 @@
+%w( ./lib ../lib . ..).each{|d| $:.unshift d}
+require "na_str"
+require "mmap"
+require "yaml"
+
+#
+# setup
+#
+  sizeof_int = [42].pack("i").size
+
+#
+# setup an empty data file big enough to hold four ints if one doesn"t already
+# exist
+#
+  data = __FILE__ + ".data"
+  open(data, File::CREAT|File::EXCL|File::RDWR){|f| f.write(0.chr * 4 * sizeof_int)} rescue nil
+
+#
+# show the orginal data - run the script more than once to see that the data
+# persists between invocations
+#
+  y "before" => IO::read(data).unpack("i*")
+
+#
+# mmap data in
+#
+  m = Mmap::new data, "rw", Mmap::MAP_SHARED
+
+#
+# overlay an narray over the memory map and manipulate it.  note that any
+# changes to the narray changes the memory map, which in turn changes the
+# file!
+#
+  na = NArray::str m, NArray::INT, 4
+  na[0] = 42 
+  na[-1] = Time.now.to_i.abs
+
+#
+# sync, and unmap the data
+#
+  m.msync
+  m.munmap
+
+#
+# show that the underlying data has been transparently changed!
+#
+  y "after" => IO::read(data).unpack("i*")

data/samples/c.rb

@@ -0,0 +1,18 @@
+%w( ./lib ../lib . ..).each{|d| $:.unshift d}
+#
+# be sure to run this a few times in a row - wait a second or two between runs
+# - notice that the data will automagically persist between calls!
+#
+require 'tmpdir'
+require 'nmap'
+
+ipath = File.join Dir.tmpdir, 'i.na'
+
+nmap = NMap.int ipath, 3,4 
+na = nmap.na
+p na
+
+na[0,true] = Time.now.to_i
+na[2,true] = 1 
+na[1,1..2] = 42
+p na

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: na_str
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2007-02-28 00:00:00.000000 -07:00
+summary: na_str
+require_paths: 
+  - lib
+email: ara.t.howard@noaa.gov
+homepage: http://codeforpeople.com/lib/ruby/na_str/
+rubyforge_project: 
+description: 
+autorequire: na_str
+default_executable: 
+bindir: bin
+has_rdoc: false
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+  - Ara T. Howard
+files: 
+  - depends
+  - extconf.rb
+  - install.rb
+  - lib
+  - Makefile
+  - na_str.c
+  - nmap.rb
+  - README
+  - samples
+  - gemspec.rb
+  - na_str-0.1.0.gem
+  - depends/mmap.tar.gz
+  - depends/narray-0.5.7p2.tar.gz
+  - lib/nmap.rb
+  - samples/b.rb.data
+  - samples/b.rb
+  - samples/a.rb
+  - samples/c.rb
+test_files: []
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: 
+  - extconf.rb
+requirements: 
+  - http://moulon.inra.fr/ruby/mmap.html
+  - http://narray.rubyforge.org/
+dependencies: []