The MappedMemory data structure implements shared/mapped memory that can be accessed between threads/processes. It can be used in a similar manner to the Packet class. More...

#include <mappedmemory.h>

Public Types
typedef unsigned long long int	ID
	ID value for shared memory.
Public Member Functions
	MappedMemory ()
	Constructor.
virtual	~MappedMemory ()
	Destructor.
int	OpenMappedMemory (const ID id, const unsigned int access=ReadWriteAccess, const unsigned int expectedSize=0)
	Opens an exisiting shared/mapped memory location.
int	OpenMappedMemory (const std::string &name, const unsigned int access=ReadWriteAccess, const unsigned int expectedSize=0)
	Opens an exisiting shared/mapped memory location.
int	CreateMappedMemory (const ID id, const unsigned int size)
	Creates a shared/mapped memory location.
int	CreateMappedMemory (const std::string &name, const unsigned int size)
	Creates a shared/mapped memory location.
int	CloseMappedMemory ()
	Closes any open view of mapped memory. If this is the last process to close the view of the memory location, it is deleted.
int	Lock (unsigned long wait=INFINITE) const
	Locks the mutex for the shared memory.
int	Unlock () const
	Unlocks the mutex for the shared memory.
Packet *	operator-> ()
	Method to get a pointer to the wrapper packet for read/write operations.
const Packet *	operator-> () const
	Method to get a pointer to the wrapper packet for read/write operations.
Packet *	GetData ()
	Method to get a pointer to the wrapper packet for read/write operations.
const Packet *	GetData () const
	Method to get a pointer to the wrapper packet for read/write operations.
int	Copy (const unsigned int p1, const unsigned int p2)
	Copies the data starting from the memory index location of p1 to the memory index location of p2.
bool	IsOpen () const
unsigned char *	GetMemory ()
	This method returns a pointer to the begining of the mapped memory. Make sure you have Locked shared memory before reading/writing.
const unsigned char *	GetMemory () const
	This method returns a pointer to the begining of the mapped memory. Make sure you have Locked shared memory before reading/writing.
const std::string	GetMappedName () const
unsigned int	Length () const
Static Public Member Functions
static int	DeleteMappedMemory (const std::string &name)
	This method can be used to forcefully delete a shared memory segment based on it's name. This method is only useful in Linux.
static bool	IsMemOpen (const std::string &name)
	Use this function to determine if there is a mapped memory resource already created/open.
Static Public Attributes
static const unsigned	ReadAccess = 1
static const unsigned int	ReadWriteAccess = 2
static const unsigned int	MemoryNameSize = 128

Detailed Description

The MappedMemory data structure implements shared/mapped memory that can be accessed between threads/processes. It can be used in a similar manner to the Packet class.

This piece of software is used for sharing messages between threads and other processes. It allocates a mapped memory buffer which includes a shared/global mutex and size information by default.

Definition at line 66 of file mappedmemory.h.

Member Typedef Documentation

typedef unsigned long long int CxUtils::MappedMemory::ID

ID value for shared memory.

Definition at line 72 of file mappedmemory.h.

Constructor & Destructor Documentation

MappedMemory::MappedMemory ( )

Constructor.

Definition at line 95 of file mappedmemory.cpp.

MappedMemory::~MappedMemory ( ) [virtual]

Destructor.

Definition at line 118 of file mappedmemory.cpp.

Member Function Documentation

int MappedMemory::CloseMappedMemory ( )

Closes any open view of mapped memory. If this is the last process to close the view of the memory location, it is deleted.

Returns:: 1 if closed, otherwise 0.

Definition at line 510 of file mappedmemory.cpp.

int MappedMemory::Copy	(	const unsigned int	p1,
		const unsigned int	p2
	)

Copies the data starting from the memory index location of p1 to the memory index location of p2.

This essentially does a memcpy of all the data starting at p1 to the location of p2. memcpy(&mem[p2], &mem[p1], CX_BYTE_SIZE*(length - p1)).

Parameters:

p1	The starting position in the mapped memory to move.
p2	The destination position to move the memory starting from p1 to.

Returns:: 1 if moved, otherwise 0.

Definition at line 770 of file mappedmemory.cpp.

int MappedMemory::CreateMappedMemory	(	const ID	id,
		const unsigned int	size
	)

Creates a shared/mapped memory location.

Parameters:

id	The ID to use for the shared memory. This is a unique number for other processes to use for lookup.
size	The size in bytes to allocate.

Returns:: 0 if the memory couldn't be created, 1 if created successfully.

Definition at line 319 of file mappedmemory.cpp.

int MappedMemory::CreateMappedMemory	(	const std::string &	name,
		const unsigned int	size
	)

Creates a shared/mapped memory location.

Parameters:

name	The name of the shared/mapped memory to open. To maximize portability between windows and linux, this should be an integer number.
size	The size in bytes to allocate.

Returns:: 0 if the memory couldn't be created, 1 if created successfully.

Definition at line 340 of file mappedmemory.cpp.

int MappedMemory::DeleteMappedMemory ( const std::string & name ) [static]

This method can be used to forcefully delete a shared memory segment based on it's name. This method is only useful in Linux.

In Windows, shared memory gets deleted as soon as the last viewing process ends, but not in Linux systems. Therefore, sometimes it is necessary to manually delete this data if a program does not exit properly and release the shared memory.

Returns:: 1 on success, 0 on error.

Definition at line 601 of file mappedmemory.cpp.

Packet * MappedMemory::GetData ( )

Method to get a pointer to the wrapper packet for read/write operations.

Returns:: Pointer to a packet structure that wrapps the shared memory buffer to simply read/write operations.

Definition at line 750 of file mappedmemory.cpp.

const Packet * MappedMemory::GetData ( ) const

Method to get a pointer to the wrapper packet for read/write operations.

Returns:: Pointer to a packet structure that wrapps the shared memory buffer to simply read/write operations.

Definition at line 735 of file mappedmemory.cpp.

const std::string CxUtils::MappedMemory::GetMappedName ( ) const [inline]

Definition at line 98 of file mappedmemory.h.

const unsigned char * MappedMemory::GetMemory ( ) const

This method returns a pointer to the begining of the mapped memory. Make sure you have Locked shared memory before reading/writing.

Returns:: Returns a pointer to the start of shared memory.

Definition at line 827 of file mappedmemory.cpp.

unsigned char * MappedMemory::GetMemory ( )

This method returns a pointer to the begining of the mapped memory. Make sure you have Locked shared memory before reading/writing.

Returns:: Returns a pointer to the start of shared memory.

Definition at line 809 of file mappedmemory.cpp.

bool MappedMemory::IsMemOpen ( const std::string & name ) [static]

Use this function to determine if there is a mapped memory resource already created/open.

Parameters:

name	Name of mapped memory resource to check for.

Returns:: True if there is a shared/mapped memory resource with the name provided already created.

Definition at line 863 of file mappedmemory.cpp.

bool MappedMemory::IsOpen ( ) const

Returns:: True if memory is open, otherwise false.

Definition at line 796 of file mappedmemory.cpp.

unsigned int MappedMemory::Length ( ) const

Returns:: Returns the size of the mapped memory file in bytes.

Definition at line 842 of file mappedmemory.cpp.

int MappedMemory::Lock ( unsigned long wait = INFINITE ) const

Locks the mutex for the shared memory.

By calling this function, you are enabling a global mutex. It is important to use this function if a shared memory location is being used for I/O by multiple processes.

Parameters:

[in] wait How long to wait in milliseconds for mutex to lock. Default is INFINITE.

Returns:: 1 if locked, otherwise 0.

Definition at line 664 of file mappedmemory.cpp.

int MappedMemory::OpenMappedMemory	(	const ID	id,
		const unsigned int	access = `ReadWriteAccess`,
		const unsigned int	expectedSize = `0`
	)

Opens an exisiting shared/mapped memory location.

If memory was opened, but the length is 0, you can set it using the SetLength method.

Parameters:

id	The ID Number of the shared memory resource to open.
access	How to access the memory (ReadAccess, or CX_MAPPED_MEMORY_WRITE_ONLY).
expectedSize	The size of shared memory if known. If not known, set to 0. If you are opening a mapped memory created by another program using CxUtils or Linux, then the size will be discovered automatically. If not, then the size will be unknown and the Size and Length functions will return 0, even though the memory map is valid.

Returns:: 0 if the memory doesn't exist, otherwise 1.

Definition at line 145 of file mappedmemory.cpp.

int MappedMemory::OpenMappedMemory	(	const std::string &	name,
		const unsigned int	access = `ReadWriteAccess`,
		const unsigned int	expectedSize = `0`
	)

Opens an exisiting shared/mapped memory location.

If memory was opened, but the length is 0, you can set it using the SetLength method.

Parameters:

name	The name of the shared/mapped memory to open.To maximize portability between windows and linux, this should be an integer number.
access	How to access the memory (ReadAccess, or CX_MAPPED_MEMORY_WRITE_ONLY).
expectedSize	The size of shared memory if known. If not known, set to 0. If you are opening a mapped memory created by another program using CxUtils or Linux, then the size will be discovered automatically. If not, then the size will be unknown and the Size and Length functions will return 0, even though the memory map is valid.

Returns:: 0 if the memory doesn't exist, otherwise 1.

Definition at line 178 of file mappedmemory.cpp.

Packet * MappedMemory::operator-> ( )

Method to get a pointer to the wrapper packet for read/write operations.

Returns:: Pointer to a packet structure that wrapps the shared memory buffer to simply read/write operations.

Definition at line 720 of file mappedmemory.cpp.

const Packet * MappedMemory::operator-> ( ) const

Method to get a pointer to the wrapper packet for read/write operations.

Returns:: Pointer to a packet structure that wrapps the shared memory buffer to simply read/write operations.

Definition at line 705 of file mappedmemory.cpp.

int MappedMemory::Unlock ( ) const

Unlocks the mutex for the shared memory.

By calling this function, you are leaving a global mutex. If you use the Lock function, you must call this when done if you do not want to deadlock your program.