win32-mmap 0.2.0

data/CHANGES

@@ -0,0 +1,23 @@
+== 0.2.0 - 13-Oct-2006
+* Completely scrapped the old interface and code.  It is now pure Ruby and
+  has a much different API, and some internal changes.
+* Added a gemspec and an install.rb file for manual installation.
+* Now requires the windows-pr package, 0.5.5 or higher.
+* Modified the example scripts.
+* Updated the docs, and replaced the .txt and .rd files with a single .rdoc
+  file.
+
+== 0.1.1 - 1-Mar-2005
+* Moved the 'examples' directory to the toplevel directory.
+* Made the CHANGES and README files rdoc friendly.
+
+== 0.1.0 - 12-Aug-2004
+* Modified to use the newer allocation framework.  That means that, as of
+  this release, this package requires Ruby 1.8.0 or later.
+* Moved sample programs under doc/examples.
+
+== 0.0.2 - 14-Mar-2004
+* Fixed sprintf() bug in new().
+
+== 0.0.1 - 13-Mar-2004
+* Initial (Beta) release

data/MANIFEST

@@ -0,0 +1,15 @@
+CHANGES
+MANIFEST
+README
+install.rb
+win32-mmap.gemspec
+
+doc/mmap.rdoc
+
+examples/mmap_test.rb
+examples/test_client.rb
+examples/test_server.rb
+
+lib/win32/mmap.rb
+
+test/tc_mmap.rb

data/README

@@ -0,0 +1,70 @@
+= Description
+   This package provides a Ruby interface for memory mapped I/O on MS Windows.
+   
+= Prerequisites
+   Ruby 1.8.0 or later.
+   windows-pr, 0.5.5 or later.
+
+= Installation
+== Standard Installation
+   ruby install.rb
+
+== Gem Installation
+   ruby win32-mmap.gemspec
+   gem install win32-mmap-x.y.z.gem
+   
+= Synopsis
+   require 'win32/mmap'
+   include Win32
+   
+   map1 = MMap.new(:file => "C:\\test.map", :size => 1024)
+   map1.foo = 'hello'
+   map1.bar = 77
+   map1.close
+   
+   map2 = MMap.new(:file => "C:\\test.map")
+   p map2.foo # 'hello'
+   p map2.bar # 77
+   map2.close
+
+= About Memory Mapped Files under Windows
+   Under Windows, code and data are both repesented by pages of memory backed
+   by files on disk - code by executable image an data by system pagefile
+   (swapfile). These are called memory mapped files. Memory mapped files can be
+   used to provide a mechanism for shared memory between processes. Different
+   processes are able to share data backed by the same swapfile, whether it's
+   the system pagefile or a user-defined swapfile.
+
+   Windows has a tight security system that prevents processes from directly
+   sharing information among each other, but mapped memory files provide a
+   mechanism that works with the Windows security system - by using a name that
+   all processes use to open the swapfile.
+
+   A shared section of the swapfile is translated into pages of memory that are
+   addressable by more than one process, Windows uses a system resource called a
+   prototype page table entry (PPTE) to enable more than one process to address
+   the same physical page of memory, thus multiple process can share the same
+   data without violating the Windows system security.
+
+   In short, MMF's provide shared memory under Windows.
+
+	(This explanation was largely borrowed from Roger Lee's Win32::MMF Perl
+	module.)
+
+= Future Plans
+   Suggestions welcome.
+
+= License
+   Ruby's
+    
+= Copyright
+   (C) 2003-2006 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.
+    
+= Authors
+   Daniel J. Berger
+   Park Heesob

data/install.rb

@@ -0,0 +1,11 @@
+# For those who don't like gems...
+require 'rbconfig'
+require 'ftools'
+include Config
+
+sitelibdir = CONFIG['sitelibdir']
+installdir = sitelibdir + '/win32'
+file = 'lib\win32\mmap.rb'
+
+Dir.mkdir(installdir) unless File.exists?(installdir)
+File.copy(file, installdir, true)

data/lib/win32/mmap.rb

@@ -0,0 +1,392 @@
+require 'windows/file'
+require 'windows/file_mapping'
+require 'windows/error'
+require 'windows/handle'
+require 'windows/msvcrt/buffer'
+require 'windows/synchronize'
+require 'windows/memory'
+
+module Win32
+
+   # Memory mapped files for MS Windows.
+   #
+   class MMap
+      VERSION = '0.2.0'
+
+      # This is a slightly different version of memcpy than what's provided
+      # in the Windows::MSVCRT::Buffer module.  The difference is that the
+      # first argument is an address, not a char buffer.
+      MEMCPY = Win32API.new('msvcrt', 'memcpy', 'LPL', 'P')
+
+      # All errors generated by Win32::MMap are of type MMap::Error.
+      #
+      class Error < StandardError; end
+
+      include Windows::Error
+      include Windows::File
+      include Windows::FileMapping
+      include Windows::Handle
+      include Windows::MSVCRT::Buffer
+      include Windows::Synchronize
+      include Windows::Memory
+
+      # The name of the file from which to create a mapping object.  This
+      # value may be nil.
+      #
+      attr_accessor :file
+
+      # The protection for the file view.  This may be any of the following
+      # values:
+      #
+      # * PAGE_READONLY
+      # * PAGE_READWRITE
+      # * PAGE_WRITECOPY
+      # * PAGE_WRITECOPY
+      # * PAGE_EXECUTE_READ
+      # * PAGE_EXECUTE_READWRITE
+      #
+      # You can OR the protection value with any of these section attributes:
+      #
+      # * SEC_COMMIT
+      # * SEC_IMAGE
+      # * SEC_LARGE_PAGES
+      # * SEC_NOCACHE
+      # * SEC_RESERVE
+      #
+      # The default protection is PAGE_READWRITE.
+      #
+      attr_accessor :protection
+
+      # A string that determines the name of the mapping object.
+      # By default this value is nil, i.e. anonymous.  If you specify a +name+
+      # that already exists then an attempt is made to access that object.
+      #
+      attr_accessor :name
+
+      # The maximum size for the file mapping object.  If a +file+ is
+      # specified, this value defaults to the size of +file+. Otherwise
+      # it defaults to zero (though you should set it manually).
+      #
+      attr_accessor :size
+
+      # Access desired to the file mapping object.  This may be
+      # any of the following values:
+      #
+      # * FILE_MAP_WRITE
+      # * FILE_MAP_READ
+      # * FILE_MAP_COPY
+      # * FILE_MAP_ALL_ACCESS
+      #
+      # The default access is FILE_MAP_WRITE.
+      #
+      attr_accessor :access
+
+      # The address of the file view mapping.
+      #
+      attr_reader :address
+      
+      # Suggested starting address of mapped view.  If this value is not
+      # specified, the system will choose the base mapping address.  If you do
+      # specify a value, it must be a multiple of the system's allocation
+      # granularity.
+      # 
+      # Note: The MSDN documentation recommends that, in most case cases, you
+      # should not set this value.
+      #--
+      # A system's allocation granularity can be found via GetSystemInfo()
+      # and the dwAllocationGranularity member of the SYSTEM_INFO struct. 
+      #
+      attr_accessor :base_address
+      
+      # Sets whether or not a semaphore lock is automatically placed on the
+      # mapped view for read and write operations.  This is true by default.
+      # 
+      attr_writer :autolock
+      
+      # The value, in milliseconds, used to wait on the semaphore lock.  Only
+      # used if the +autolock+ option is true. The default is 10 milliseconds.
+      # 
+      attr_accessor :timeout
+
+      # :call-seq:
+      #     MMap.new(opts = {})
+      #     MMap.new(opts = {}){ |address| block }
+      #
+      # Creates and returns a new Win32::MMap object.  If +file+ is set, then
+      # that file is used to create the mapping.  If a block is provided the
+      # address is yielded and the mapping object is automatically closed at the
+      # end of the block.
+      # 
+      # Accepts any one of the following hash attributes:
+      #
+      # * protection
+      # * size
+      # * access
+      # * inherit
+      # * name
+      # * base_address
+      # * autolock
+      # * timeout
+      # * file
+      #
+      # Please see the documentation for the individual attributes for
+      # further details.  Note that, although these are accessors, they
+      # *must* be set in the constructor (if set at all).  Setting them
+      # after the call to MMap.new will not have any effect.
+      #
+      # == Example
+      #    require 'win32/mmap'
+      #    require 'windows/msvcrt/string'
+      #    include Windows::MSVCRT::String
+      #    include Win32
+      #
+      #    # Reverse the contents of a file.
+      #    mmap = MMap.new(:file => 'test.txt') do |addr|
+      #       strrev(addr)
+      #    end
+      #
+      def initialize(opts = {})
+         valid = %w/
+            file name protection access inherit size
+            base_address open autolock timeout
+         /
+
+         opts.each{ |key, value|
+            key = key.to_s.downcase
+            unless valid.include?(key)
+               raise ArgumentError, "Invalid key '#{key}'"
+            end
+            if key == 'inherit'
+               self.inherit = value # To force inherit= method call
+            else
+               instance_variable_set("@#{key}", value)
+            end
+         }
+      
+         @protection   ||= PAGE_READWRITE
+         @access       ||= FILE_MAP_WRITE
+         @size         ||= 0
+         @inherit      ||= 0
+         @base_address ||= 0
+         @timeout      ||= 10 # Milliseconds
+         
+         @hash = {}
+
+         # Anything except an explicit false means the autolock is on.
+         @autolock = true unless @autolock == false
+         
+         @lock_flag = 0 # Internal use only
+
+         if @file
+            if File.exists?(@file)
+               fsize = File.size(@file)
+               raise Error, 'cannot open 0 byte file' if fsize.zero?
+               @size = fsize if @size < fsize
+            end
+
+            rights = GENERIC_READ|GENERIC_WRITE
+
+            @fh = CreateFile(@file, rights, 0, 0, OPEN_ALWAYS, 0, 0)
+
+            if @fh == INVALID_HANDLE_VALUE
+               raise Error, get_last_error
+            end
+         else
+            @fh = INVALID_HANDLE_VALUE
+         end
+
+         if @open
+            @mh = OpenFileMapping.call(@access, @inherit, @name)
+         else
+            @mh = CreateFileMapping(@fh, @inherit, @protection, 0, @size, @name)
+         end
+
+         if @mh == 0
+            raise Error, get_last_error
+         end
+
+         if @open 
+            @address = MapViewOfFileEx(@mh, @access, 0, 0, 0, @base_address) 
+            @size    = get_view_size()
+         else
+            @address = MapViewOfFileEx(@mh, @access, 0, 0, 0, @base_address)
+         end
+
+         if @address == 0
+            raise Error, get_last_error
+         end
+         
+         if @autolock
+            @semaphore = CreateSemaphore(nil, 1, 1, "#{@name}.ruby_lock")
+            if @semaphore == 0
+               raise Error, get_last_error
+            end
+         end
+
+         if block_given?
+            begin
+               yield @address
+            ensure
+               close
+            end
+         end
+         
+         @address
+      end
+
+      # Opens an existing file mapping using +name+.  You may pass a hash
+      # of +opts+ as you would to MMap.new.  If you don't specify a size
+      # as part of the +opts+, it will be dynamically determined for you
+      # (in blocks equal to your system's page size, typically 4k).
+      # 
+      # This method is otherwise identical to MMap.new.
+      #--
+      # This forces MMap.new to use OpenFileMapping() behind the scenes.
+      #
+      def self.open(name, opts={})
+         opts[:name] = name
+         opts[:open] = true        
+         self.new(opts)
+      end
+      
+      # Sets whether or not the mapping handle can be inherited
+      # by child processes.
+      #--
+      # If true, we have to create a SECURITY_ATTRIBUTES struct and set
+      # its nLength member to 12 and its bInheritHandle member to TRUE.
+      #
+      def inherit=(bool)
+         if bool
+            buf = 0.chr * 12 # sizeof(SECURITY_ATTRIBUTES)
+            buf[0,4] = [12].pack('L')
+            buf[8,4] = [1].pack('L')  # 1 == TRUE
+            @inherit = buf
+         else
+            @inherit = 0
+         end
+      end
+
+      # Returns whether or not the mapping handle can be
+      # inherited by child processes.  The default is false.
+      #
+      def inherit?
+         @inherit != 0
+      end
+
+      # Writes +num_bytes+ to the disk within a mapped view of a file, or to
+      # the end of the mapping if +num_bytes+ is not specified.
+      #
+      def flush(num_bytes = 0)
+         unless FlushViewOfFile(@address, num_bytes)
+            raise Error, get_last_error
+         end
+      end
+
+      # Unmaps the file view and closes all open file handles.  You should
+      # always call this when you are finished with the object (when using
+      # the non-block form).
+      #
+      def close
+         UnmapViewOfFile(@address) if @address
+         CloseHandle(@fh) if @fh
+         CloseHandle(@mh) if @mh
+         ReleaseSemaphore(@semaphore, 1, nil) if @semaphore
+      end
+      
+      # Returns whether or not a semaphore lock is automatically placed on the
+      # mapped view for read and write operations.  This is true by default.
+      # 
+      def autolock?
+         @autolock
+      end
+
+      private
+
+      # This is used to allow dynamic getters and setters between memory
+      # mapped objects.
+      #--
+      # This replaces the getvar/setvar API from 0.1.0.
+      # 
+      def method_missing(method_id, *args)
+         method = method_id.id2name
+         args = args.first if args.length == 1
+
+         if method[-1,1] == '=' # Setter
+            method.chop!           
+            @hash["#{method}"] = args
+            
+            if @autolock
+               if mmap_lock
+                  instance_variable_set("@#{method}", args)
+                  marshal = Marshal.dump(@hash)
+                  MEMCPY.call(@address, marshal, marshal.length)
+                  mmap_unlock
+               end
+            else
+               instance_variable_set("@#{method}", args)
+               marshal = Marshal.dump(@hash)
+               MEMCPY.call(@address, marshal, marshal.length)
+            end
+         else                   # Getter
+            buf = 0.chr * @size           
+            if @autolock
+               if mmap_lock
+                  marshal = memcpy(buf, @address, @size)
+                  hash = Marshal.load(marshal)
+                  val  = hash["#{method}"]
+                  instance_variable_set("@#{method}", val)  
+                  mmap_unlock 
+               end             
+            else
+               marshal = memcpy(buf, @address, @size)
+               hash = Marshal.load(marshal)
+               val  = hash["#{method}"]
+               instance_variable_set("@#{method}", val)
+            end
+            return instance_variable_get("@#{method}") 
+         end
+      end
+      
+      # Adds a semaphore lock the mapping.  Only used if +autolock+ is set
+      # to true in the constructor.
+      # 
+      def mmap_lock
+         bool = false
+         
+         if(@lock_flag == 0)
+            if WaitForSingleObject(@semaphore, @timeout) == WAIT_OBJECT_0
+               bool = true
+            end
+         end
+
+         @lock_flag += 1
+         bool
+      end
+      
+      # Releases a semaphore lock on the view.  Only used if +autolock+ is
+      # set to true in the constructor.
+      # 
+      def mmap_unlock
+         @lock_flag -= 1
+         
+         if @lock_flag != 0
+            return false
+         end
+         
+         if ReleaseSemaphore(@semaphore, 1, nil) == 0
+            raise Error, get_last_error
+         end
+         
+         true
+      end
+      
+      # Gets the size of an existing mapping based on the address.  Used by
+      # the MMap.open method when a size isn't specified.
+      # 
+      def get_view_size
+         mbi = [0,0,0,0,0,0,0].pack('LLLLLLL') # MEMORY_BASIC_INFORMATION
+         VirtualQuery(@address, mbi, mbi.size)
+         mbi[12,4].unpack('L').first # RegionSize
+      end
+   end
+end

data/test/tc_mmap.rb

@@ -0,0 +1,88 @@
+#################################################
+# tc_mmap.rb
+#
+# Test suite for the win32-mmap package.
+#################################################
+Dir.chdir '..' if File.basename(Dir.pwd) == 'test'
+$LOAD_PATH.unshift Dir.pwd
+$LOAD_PATH.unshift Dir.pwd + '/lib'
+
+require 'test/unit'
+require 'win32/mmap'
+include Win32
+
+# The order of the tests matters (for now)
+class TC_Mmap < Test::Unit::TestCase
+   def setup
+      @mmap = MMap.new(:name => 'test', :size => 100)
+   end
+
+   def test_version
+      assert_equal('0.2.0', MMap::VERSION)
+   end
+   
+   def test_dynamic_value
+      assert_nothing_raised{ @mmap.foo = 'test' }
+      assert_equal('test', @mmap.foo)
+   end
+   
+   def test_valid_options
+      assert_raises(ArgumentError){ MMap.new(:foo => 1) }
+   end
+
+   def test_address
+      assert_respond_to(@mmap, :address)
+      assert_kind_of(Fixnum, @mmap.address)
+   end
+   
+   def test_base_address
+      assert_respond_to(@mmap, :base_address)
+      assert_respond_to(@mmap, :base_address=)
+      assert_kind_of(Fixnum, @mmap.base_address)
+   end
+   
+   def test_name
+      assert_respond_to(@mmap, :name)
+      assert_respond_to(@mmap, :name=)
+      assert_equal('test', @mmap.name)
+   end
+   
+   def test_inherit
+      assert_respond_to(@mmap, :inherit?)
+      assert_respond_to(@mmap, :inherit=)
+      assert_equal(false, @mmap.inherit?)
+   end
+   
+   def test_size
+      assert_respond_to(@mmap, :size)
+      assert_respond_to(@mmap, :size=)
+      assert_equal(100, @mmap.size)
+   end
+   
+   def test_file
+      assert_respond_to(@mmap, :file)
+      assert_respond_to(@mmap, :file=)
+      assert_nil(@mmap.file)
+   end
+   
+   def test_access
+      assert_respond_to(@mmap, :access)
+      assert_respond_to(@mmap, :access=)
+   end
+   
+   def test_autolock
+      assert_respond_to(@mmap, :autolock?)
+      assert_respond_to(@mmap, :autolock=)
+      assert_equal(true, @mmap.autolock?)
+   end
+   
+   def test_protection
+      assert_respond_to(@mmap, :protection)
+      assert_respond_to(@mmap, :protection=)
+      assert_equal(4, @mmap.protection)
+   end
+   
+   def teardown
+      @mmap.close
+   end
+end

data/win32-mmap.gemspec

@@ -0,0 +1,24 @@
+require "rubygems"
+
+spec = Gem::Specification.new do |gem|
+   gem.name        = "win32-mmap"
+   gem.version     = "0.2.0"
+   gem.author      = "Daniel J. Berger"
+   gem.email       = "djberg96@gmail.com"
+   gem.homepage    = "http://www.rubyforge.org/projects/win32utils"
+   gem.platform    = Gem::Platform::RUBY
+   gem.summary     = "Memory mapped IO for Windows."
+   gem.description = "Memory mapped IO for Windows."
+   gem.test_file   = "test/tc_mmap.rb"
+   gem.has_rdoc    = true
+   gem.files       = Dir["lib/win32/*.rb"] + Dir["test/*"] + Dir["[A-Z]*"]
+   gem.files.reject! { |fn| fn.include? "CVS" }
+   gem.require_path = "lib"
+   gem.extra_rdoc_files = ["README", "CHANGES"]
+   gem.add_dependency("windows-pr", ">= 0.5.5")
+end
+
+if $0 == __FILE__
+   Gem.manage_gems
+   Gem::Builder.new(spec).build
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: win32-mmap
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+date: 2006-10-13 00:00:00 -06:00
+summary: Memory mapped IO for Windows.
+require_paths: 
+- lib
+email: djberg96@gmail.com
+homepage: http://www.rubyforge.org/projects/win32utils
+rubyforge_project: 
+description: Memory mapped IO for Windows.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Daniel J. Berger
+files: 
+- lib/win32/mmap.rb
+- test/tc_mmap.rb
+- CHANGES
+- doc
+- examples
+- install.rb
+- lib
+- MANIFEST
+- README
+- test
+- win32-mmap.gemspec
+test_files: 
+- test/tc_mmap.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- README
+- CHANGES
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: windows-pr
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.5.5
+    version: