Class Win32::MMap
In: mmap.rb
Parent: Object

Memory mapped files for MS Windows.

Methods

autolock?   close   flush   inherit=   inherit?   new   open  

Included Modules

Windows::Error Windows::File Windows::FileMapping Windows::Handle Windows::MSVCRT::Buffer Windows::Synchronize Windows::Memory

Classes and Modules

Class Win32::MMap::Error

Constants

VERSION = '0.2.2'

Attributes

access  [RW]  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.

address  [R]  The address of the file view mapping.
autolock  [W]  Sets whether or not a semaphore lock is automatically placed on the mapped view for read and write operations. This is true by default.
base_address  [RW]  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.

file  [RW]  The name of the file from which to create a mapping object. This value may be nil.
name  [RW]  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.
protection  [RW]  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.

size  [RW]  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).
timeout  [RW]  The value, in milliseconds, used to wait on the semaphore lock. Only used if the autolock option is true. The default is 10 milliseconds.

Public Class methods

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 on 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

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.

Public Instance methods

Returns whether or not a semaphore lock is automatically placed on the mapped view for read and write operations. This is true by default.

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).

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.

Sets whether or not the mapping handle can be inherited by child processes.

Returns whether or not the mapping handle can be inherited by child processes. The default is false.

[Validate]