C++ interface OS memory mapping system call. More...

#include <Mem_Map.h>

Inheritance diagram for ACE_Mem_Map:

Collaboration diagram for ACE_Mem_Map:

Public Member Functions
	ACE_Mem_Map (void)
	Default constructor.
	ACE_Mem_Map (ACE_HANDLE handle, size_t length=static_cast< size_t >(-1), int prot=PROT_RDWR, int share=ACE_MAP_PRIVATE, void *addr=0, ACE_OFF_T offset=0, LPSECURITY_ATTRIBUTES sa=0)
	ACE_Mem_Map (const ACE_TCHAR filename, size_t length=static_cast< size_t >(-1), int flags=O_RDWR\|O_CREAT, mode_t mode=ACE_DEFAULT_FILE_PERMS, int prot=PROT_RDWR, int share=ACE_MAP_PRIVATE, void addr=0, ACE_OFF_T offset=0, LPSECURITY_ATTRIBUTES sa=0)
	Map a file specified by file_name.
int	map (ACE_HANDLE handle, size_t length=static_cast< size_t >(-1), int prot=PROT_RDWR, int share=ACE_MAP_PRIVATE, void *addr=0, ACE_OFF_T offset=0, LPSECURITY_ATTRIBUTES sa=0)
int	map (size_t length=static_cast< size_t >(-1), int prot=PROT_RDWR, int share=ACE_MAP_PRIVATE, void *addr=0, ACE_OFF_T offset=0, LPSECURITY_ATTRIBUTES sa=0)
	Remap the file associated with <handle_>.
int	map (const ACE_TCHAR filename, size_t length=static_cast< size_t >(-1), int flags=O_RDWR\|O_CREAT, mode_t mode=ACE_DEFAULT_FILE_PERMS, int prot=PROT_RDWR, int share=ACE_MAP_PRIVATE, void addr=0, ACE_OFF_T offset=0, LPSECURITY_ATTRIBUTES sa=0)
	Map a file specified by filename.
	~ACE_Mem_Map (void)
	Destructor.
int	open (const ACE_TCHAR *filename, int flags=O_RDWR\|O_CREAT, mode_t perms=ACE_DEFAULT_FILE_PERMS, LPSECURITY_ATTRIBUTES sa=0)
	Open the file without mapping it.
int	close (void)
	Close down the <handle_> if necessary and unmap the mapping.
int	close_handle (void)
	Close down the <handle_> if necessary.
int	close_filemapping_handle (void)
int	operator() (void *&addr)
void *	addr (void) const
	Return the base address.
size_t	size (void) const
int	unmap (ssize_t len=-1)
	Unmap the region starting at base_addr_.
int	unmap (void *addr, ssize_t len)
	Unmap the region starting at addr_.
int	sync (size_t len, int flags=MS_SYNC)
int	sync (int flags=MS_SYNC)
int	sync (void *addr, size_t len, int flags=MS_SYNC)
int	protect (size_t len, int prot=PROT_RDWR)
int	protect (int prot=PROT_RDWR)
int	protect (void *addr, size_t len, int prot=PROT_RDWR)
int	remove (void)
	Close and remove the file from the file system.
int	advise (int behavior, int len=-1)
	Hook into the underlying VM system.
ACE_HANDLE	handle (void) const
	Return the underlying <handle_>.
const ACE_TCHAR *	filename (void) const
	Return the name of file that is mapped (if any).
void	dump (void) const
	Dump the state of an object.
Public Attributes
	ACE_ALLOC_HOOK_DECLARE
	Declare the dynamic allocation hooks.
Private Member Functions
int	map_it (ACE_HANDLE handle, size_t len=static_cast< size_t >(-1), int prot=PROT_RDWR, int share=MAP_SHARED, void *addr=0, ACE_OFF_T offset=0, LPSECURITY_ATTRIBUTES sa=0)
Private Attributes
void *	base_addr_
	Base address of the memory-mapped file.
ACE_TCHAR	filename_ [MAXPATHLEN+1]
	Name of the file that is mapped.
size_t	length_
	Length of the mapping.
ACE_HANDLE	handle_
	HANDLE for the open file.
ACE_HANDLE	file_mapping_
	HANDLE for the open mapping.
bool	close_handle_

Detailed Description

C++ interface OS memory mapping system call.

This class works with both the mmap(2) UNIX system and the Win32 family of memory mapping system calls.

Definition at line 41 of file Mem_Map.h.

Constructor & Destructor Documentation

ACE_Mem_Map::ACE_Mem_Map ( void )

Default constructor.

Definition at line 213 of file Mem_Map.cpp.

  : base_addr_ (MAP_FAILED),
    length_ (0),
    handle_ (ACE_INVALID_HANDLE),
    file_mapping_ (ACE_INVALID_HANDLE),
    close_handle_ (false)
{
  ACE_TRACE ("ACE_Mem_Map::ACE_Mem_Map");
  ACE_OS::memset (this->filename_, 0, sizeof this->filename_);
}

ACE_Mem_Map::ACE_Mem_Map	(	ACE_HANDLE	handle,
		size_t	length = `static_cast<size_t> (-1)`,
		int	prot = `PROT_RDWR`,
		int	share = `ACE_MAP_PRIVATE`,
		void *	addr = `0`,
		ACE_OFF_T	offset = `0`,
		LPSECURITY_ATTRIBUTES	sa = `0`
	)

Map a file from an open file descriptor handle. This function will lookup the length of the file if it is not given.

Definition at line 259 of file Mem_Map.cpp.

  : base_addr_ (MAP_FAILED),
    length_ (0),
    handle_ (ACE_INVALID_HANDLE),
    file_mapping_ (ACE_INVALID_HANDLE),
    close_handle_ (false)
{
  ACE_TRACE ("ACE_Mem_Map::ACE_Mem_Map");

  ACE_OS::memset (this->filename_,
                  0,
                  sizeof this->filename_);
  if (this->map (handle,
                 len,
                 prot,
                 share,
                 addr,
                 offset,
                 sa) < 0)
    ACE_ERROR ((LM_ERROR,
                ACE_TEXT ("%p\n"),
                ACE_TEXT ("ACE_Mem_Map::ACE_Mem_Map")));
}

ACE_Mem_Map::ACE_Mem_Map	(	const ACE_TCHAR *	filename,
		size_t	length = `static_cast<size_t> (-1)`,
		int	flags = `O_RDWR \| O_CREAT`,
		mode_t	mode = `ACE_DEFAULT_FILE_PERMS`,
		int	prot = `PROT_RDWR`,
		int	share = `ACE_MAP_PRIVATE`,
		void *	addr = `0`,
		ACE_OFF_T	offset = `0`,
		LPSECURITY_ATTRIBUTES	sa = `0`
	)

Map a file specified by file_name.

Definition at line 226 of file Mem_Map.cpp.

  : base_addr_ (MAP_FAILED),
    length_ (0),
    handle_ (ACE_INVALID_HANDLE),
    file_mapping_ (ACE_INVALID_HANDLE),
    close_handle_ (false)
{
  ACE_TRACE ("ACE_Mem_Map::ACE_Mem_Map");
  if (this->map (file_name,
                 len,
                 flags,
                 mode,
                 prot,
                 share,
                 addr,
                 offset,
                 sa) < 0)
    ACE_ERROR ((LM_ERROR,
                ACE_TEXT ("%p\n"),
                ACE_TEXT ("ACE_Mem_Map::ACE_Mem_Map")));
}

ACE_Mem_Map::~ACE_Mem_Map ( void )

Destructor.

Definition at line 50 of file Mem_Map.cpp.

{
  ACE_TRACE ("ACE_Mem_Map::~ACE_Mem_Map");

  this->close ();
}

Member Function Documentation

void * ACE_Mem_Map::addr ( void ) const [inline]

Return the base address.

Definition at line 81 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::addr");

  return this->base_addr_;
}

int ACE_Mem_Map::advise	(	int	behavior,
		int	len = `-1`
	)			`[inline]`

Hook into the underlying VM system.

Definition at line 212 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::advise");
  const size_t advise_len =
    len < 0 ? this->length_ : static_cast<size_t> (len);

  return ACE_OS::madvise ((caddr_t) this->base_addr_,
                          advise_len,
                          behavior);
}

int ACE_Mem_Map::close ( void )

Close down the <handle_> if necessary and unmap the mapping.

Definition at line 41 of file Mem_Map.cpp.

{
  ACE_TRACE ("ACE_Mem_Map::close");

  this->unmap ();

  return this->close_handle ();
}

int ACE_Mem_Map::close_filemapping_handle ( void ) [inline]

Close down the internal <file_mapping_> if necessary. This is mostly necessary on Win32, which has a different handle for file-mapping kernel object.

Definition at line 99 of file Mem_Map.inl.

{
  int result = 0;

  if (this->file_mapping_ != this->handle_
      && this->file_mapping_ != ACE_INVALID_HANDLE)
    {
      result = ACE_OS::close (this->file_mapping_);
      this->file_mapping_ = ACE_INVALID_HANDLE;
    }

  return result;
}

int ACE_Mem_Map::close_handle ( void ) [inline]

Close down the <handle_> if necessary.

Definition at line 224 of file Mem_Map.inl.

{
  int result = 0;

  if (this->close_handle_)
    {
      this->close_handle_ = false;
      result = ACE_OS::close (this->handle_);
      this->handle_ = ACE_INVALID_HANDLE;
    }

  return result;
}

void ACE_Mem_Map::dump ( void ) const

Dump the state of an object.

Definition at line 24 of file Mem_Map.cpp.

{
#if defined (ACE_HAS_DUMP)
  ACE_TRACE ("ACE_Mem_Map::dump");

  ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
  ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("base_addr_ = %x"), this->base_addr_));
  ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("\nfilename_ = %s"), this->filename_));
  ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("\nlength_ = %d"), this->length_));
  ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("\nhandle_ = %d"), this->handle_));
  ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("\nfile_mapping_ = %d"), this->file_mapping_));
  ACE_DEBUG ((LM_DEBUG,  ACE_TEXT ("\nclose_handle_ = %d"), this->close_handle_));
  ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
#endif /* ACE_HAS_DUMP */
}

const ACE_TCHAR * ACE_Mem_Map::filename ( void ) const [inline]

Return the name of file that is mapped (if any).

Definition at line 21 of file Mem_Map.inl.

{
  return this->filename_;
}

ACE_HANDLE ACE_Mem_Map::handle ( void ) const [inline]

Return the underlying <handle_>.

Definition at line 12 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::handle");
  return this->handle_;
}

int ACE_Mem_Map::map	(	ACE_HANDLE	handle,
		size_t	length = `static_cast<size_t> (-1)`,
		int	prot = `PROT_RDWR`,
		int	share = `ACE_MAP_PRIVATE`,
		void *	addr = `0`,
		ACE_OFF_T	offset = `0`,
		LPSECURITY_ATTRIBUTES	sa = `0`
	)			`[inline]`

Map a file from an open file descriptor handle. This function will lookup the length of the file if it is not given.

Definition at line 27 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::map");
  return this->map_it (handle, length, prot, share, addr, offset, sa);
}

int ACE_Mem_Map::map	(	size_t	length = `static_cast<size_t> (-1)`,
		int	prot = `PROT_RDWR`,
		int	share = `ACE_MAP_PRIVATE`,
		void *	addr = `0`,
		ACE_OFF_T	offset = `0`,
		LPSECURITY_ATTRIBUTES	sa = `0`
	)			`[inline]`

Remap the file associated with <handle_>.

Definition at line 42 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::map");
  // If we're already mapped at a particular location then try to
  // remap the file using the same base address.
  if (addr == 0 && this->base_addr_ != 0 && this->base_addr_ != MAP_FAILED)
    {
      share |= MAP_FIXED;
      addr = this->base_addr_;
    }

  return this->map_it (this->handle (), length, prot,
                       share, addr, offset, sa);
}

int ACE_Mem_Map::map	(	const ACE_TCHAR *	filename,
		size_t	length = `static_cast<size_t> (-1)`,
		int	flags = `O_RDWR \| O_CREAT`,
		mode_t	mode = `ACE_DEFAULT_FILE_PERMS`,
		int	prot = `PROT_RDWR`,
		int	share = `ACE_MAP_PRIVATE`,
		void *	addr = `0`,
		ACE_OFF_T	offset = `0`,
		LPSECURITY_ATTRIBUTES	sa = `0`
	)

Map a file specified by filename.

Definition at line 185 of file Mem_Map.cpp.

{
  ACE_TRACE ("ACE_Mem_Map::map");
  this->length_ = 0;

  if (this->open (file_name,
                  flags,
                  mode,
                  sa) == -1)
    return -1;
  else
    return this->map_it (this->handle (),
                         len,
                         prot,
                         share,
                         addr,
                         offset,
                         sa);
}

int ACE_Mem_Map::map_it	(	ACE_HANDLE	handle,
		size_t	len = `static_cast<size_t> (-1)`,
		int	prot = `PROT_RDWR`,
		int	share = `MAP_SHARED`,
		void *	addr = `0`,
		ACE_OFF_T	offset = `0`,
		LPSECURITY_ATTRIBUTES	sa = `0`
	)			`[private]`

This method does the dirty work of actually calling mmap to map the file into memory.

Definition at line 61 of file Mem_Map.cpp.

{
  ACE_TRACE ("ACE_Mem_Map::map_it");

#if defined (ACE_LACKS_AUTO_MMAP_REPLACEMENT)
  // If the system does not replace any previous mappings, then
  // unmap() before (potentially) mapping to the same location.
  int const unmap_result = this->unmap ();
  if (unmap_result != 0)
    return unmap_result;
#endif /* ACE_LACKS_AUTO_MMAP_REPLACEMENT */

  this->base_addr_ = addr;
  this->handle_ = handle;

  // Get the current filesize
  ACE_OFF_T const current_file_length = ACE_OS::filesize (this->handle_);

  // Flag to indicate if we need to extend the back store
  bool extend_backing_store = false;

  // File length requested by user
  ACE_OFF_T requested_file_length = 0;

  // Check <length_request>
  if (length_request == static_cast<size_t> (-1))
    {
      // Set length to file_request or size_t max.
      this->length_ = ACE_Utils::truncate_cast<size_t> (current_file_length - offset);
    }
  else
    {
      // Make sure that we have not been asked to do the impossible.
      if (static_cast<ACE_UINT64> (length_request)
          + static_cast<ACE_UINT64> (offset)
          > static_cast<ACE_UINT64> (ACE_Numeric_Limits<ACE_OFF_T>::max ()))
        return -1;

      // File length implicitly requested by user
      requested_file_length = static_cast<ACE_OFF_T> (length_request) + offset;

      // Check to see if we need to extend the backing store
      if (requested_file_length > current_file_length)
        {
          // If the length of the mapped region is less than the
          // length of the file then we force a complete new remapping
          // by setting the descriptor to ACE_INVALID_HANDLE (closing
          // down the descriptor if necessary).
          this->close_filemapping_handle ();

          // Remember to extend the backing store
          extend_backing_store = true;
        }

      // Set length to length_request
      this->length_ = length_request;
    }

  // Check if we need to extend the backing store.
  if (extend_backing_store)
    {
      // Remember than write increases the size by one.
      ACE_OFF_T null_byte_position = 0;
      if (requested_file_length > 0)
        {
          // This will make the file size <requested_file_length>
          null_byte_position = requested_file_length - 1;
        }

      if (ACE_OS::pwrite (this->handle_,
                          "",
                          1,
                          null_byte_position) == -1)
        return -1;
    }

    this->base_addr_ = ACE_OS::mmap (this->base_addr_,
                                     this->length_,
                                     prot,
                                     share,
                                     this->handle_,
                                     offset,
                                     &this->file_mapping_,
                                     sa);

  return this->base_addr_ == MAP_FAILED ? -1 : 0;
}

int ACE_Mem_Map::open	(	const ACE_TCHAR *	filename,
		int	flags = `O_RDWR \| O_CREAT`,
		mode_t	perms = `ACE_DEFAULT_FILE_PERMS`,
		LPSECURITY_ATTRIBUTES	sa = `0`
	)

Open the file without mapping it.

Definition at line 156 of file Mem_Map.cpp.

{
  ACE_TRACE ("ACE_Mem_Map::open");

#if defined (INTEGRITY)  || defined (__QNXNTO__) || defined (ACE_VXWORKS)
  this->handle_ = ACE_OS::shm_open (file_name, flags, perms, sa);
#elif defined (ACE_OPENVMS)
  ACE_OSCALL (::open (file_name, flags, perms, "shr=get,put,upd"), ACE_HANDLE, -1, this->handle_);
#else
  this->handle_ = ACE_OS::open (file_name, flags, perms, sa);
#endif /* INTEGRITY */

  if (this->handle_ == ACE_INVALID_HANDLE)
    return -1;
  else
    {
      ACE_OS::strsncpy (this->filename_,
                        file_name,
                        MAXPATHLEN);

      this->close_handle_ = true;
      return 0;
    }
}

int ACE_Mem_Map::operator() ( void *& addr ) [inline]

This operator passes back the starting address of the mapped file.

Definition at line 65 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::operator");

  if (this->base_addr_ == MAP_FAILED)
    return -1;
  else
    {
      addr = this->base_addr_;
      return 0;
    }
}

int ACE_Mem_Map::protect ( int prot = PROT_RDWR ) [inline]

Change the protection of all the pages of the mapped region to prot starting at base_addr_.

Definition at line 193 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::protect");
  return ACE_OS::mprotect (this->base_addr_, this->length_, prot);
}

int ACE_Mem_Map::protect	(	void *	addr,
		size_t	len,
		int	prot = `PROT_RDWR`
	)			`[inline]`

Change the protection of the pages of the mapped region to prot starting at addr up to len bytes.

Definition at line 203 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::protect");
  return ACE_OS::mprotect (addr, len, prot);
}

int ACE_Mem_Map::protect	(	size_t	len,
		int	prot = `PROT_RDWR`
	)			`[inline]`

Change the protection of the pages of the mapped region to prot starting at base_addr_ up to len bytes.

Definition at line 182 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::protect");
  return ACE_OS::mprotect (this->base_addr_, len, prot);
}

int ACE_Mem_Map::remove ( void )

Close and remove the file from the file system.

Definition at line 292 of file Mem_Map.cpp.

{
  ACE_TRACE ("ACE_Mem_Map::remove");

  ACE_OS::ftruncate (this->handle_, 0);
  this->close ();

  if (this->filename_[0] != '\0')
#if defined (INTEGRITY) || defined (__QNXNTO__) || defined (ACE_VXWORKS)
  return ACE_OS::shm_unlink (this->filename_);
#else
  return ACE_OS::unlink (this->filename_);
#endif /* __QNXNTO__ */

  else
    return 0;
}

size_t ACE_Mem_Map::size ( void ) const [inline]

This function returns the number of bytes currently mapped in the file.

Definition at line 92 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::size");
  return this->length_;
}

int ACE_Mem_Map::sync ( int flags = MS_SYNC ) [inline]

Sync the whole memory region to the backing store starting at base_addr_.

Definition at line 160 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::sync");
  return ACE_OS::msync (this->base_addr_,
                        this->length_,
                        flags);
}

int ACE_Mem_Map::sync	(	size_t	len,
		int	flags = `MS_SYNC`
	)			`[inline]`

Sync len bytes of the memory region to the backing store starting at base_addr_. If len == -1 then sync the whole region.

Definition at line 150 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::sync");
  return ACE_OS::msync (this->base_addr_,
                        len,
                        flags);
}

int ACE_Mem_Map::sync	(	void *	addr,
		size_t	len,
		int	flags = `MS_SYNC`
	)			`[inline]`

Sync len bytes of the memory region to the backing store starting at addr_.

Definition at line 172 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::sync");
  return ACE_OS::msync (addr, len, flags);
}

int ACE_Mem_Map::unmap ( ssize_t len = -1 ) [inline]

Unmap the region starting at base_addr_.

Definition at line 116 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::unmap");

  this->close_filemapping_handle ();

  if (this->base_addr_ != MAP_FAILED)
    {
      int const result = ACE_OS::munmap (this->base_addr_,
                                         len < 0 ? this->length_ : len);
      this->base_addr_ = MAP_FAILED;
      return result;
    }
  else
    return 0;
}

int ACE_Mem_Map::unmap	(	void *	addr,
		ssize_t	len
	)			`[inline]`

Unmap the region starting at addr_.

Definition at line 136 of file Mem_Map.inl.

{
  ACE_TRACE ("ACE_Mem_Map::unmap");

  this->close_filemapping_handle ();

  return ACE_OS::munmap (addr,
                         len < 0 ? this->length_ : len);
}