CDAQShm

Name

CDAQShm -- class description

Synopsis


#include <daqshm.h>
        
class CDAQShm
{        
    
  static bool create(std::string name, size_t size, unsigned int flags);
      static void* attach(std::string name);
      static bool detach(void* pSharedMemory, std::string name, size_t size);
      static bool remove(std::string name);
      static ssize_t size(std::string name);
      static int lastError();
      static std::string errorMessage(int errorCode);

     static const int Success;
     static const int Exists;
     static const int NonExistent;
     static const int NoAccess;
     static const int NotAttached;
     static const int CheckOSError;
   
     static const int GroupRead;
     static const int GroupWrite;
     static const int OtherRead;
     static const int OtherWrite;
};
            

DESCRIPTION

Provides operating system independent access to underlying shared memory racilities. The life cycle of a shared memory region is that it is created (which makes is persistent). Once created, processes can attach to the thread, and subsequently detach from the region. At some point shared memory regions can be deleted.

Shared memories are not gauranteed to survive across operating system reboots.

METHODS

static bool create(std::string name, size_t size, unsigned int flags);

Creates a new shared memory section. name is the name of the new region. size is the minimum number of bytes of shared memory that will be created. It is possible the shared memory will be larger than size due to page alignment requirements. flagsis a bitwised or list of flags that determine the access granted to other users.

See PUBLIC VARIABLES, TYPES and CONSTANTS for information about the bits in the flag parameter.

false is returned on success and true on failure allowing for the normal C style idiom of if (CDAQShm::create(....)) { handle errors}

static void* attach(std::string name);

Attaches the process to an existing shared memory region. The memory region is mapped into the process virtual address space and a pointer to the first byte of that virtual address space is returned.

name is the name of the shared memory segment created via create.

On error, this method returns null.

static bool detach(void* pSharedMemory, std::string name, size_t size);

Detaches from a shared memory region. pSharedMemory is the pointer that was returned from attach while name was the name of the shared memory passed in to attach. The size of the shared memory region is size

true is returned on error.

static bool remove(std::string name);

Marks the shared memory region name for deletion by the operating system. In most operating systems, the underlying system call will not actually delete the shared memory until all processes currently attached either exit or detach.

The method returns true if a failure is detected.

static ssize_t size(std::string name);

Returns the number of bytes in a shared memory region.

static int lastError();

Returns the status of the most recent call. The set of values that might be returned is documented below in PUBLIC VARIABLES, TYPES and CONSTANTS.

static std::string errorMessage(int errorCode);

Returns a textual error message that corresponds to the errorCode gotten from a call to lastError

PUBLIC VARIABLES, TYPES and CONSTANTS

This class exports two setsof constants. The first set has to do with reporting detailed status information (failure causes actuall). The second set describs the protections that are to be applied to a shared memory section at creation time.

Status Codes:

static const int Success;

Successful completion of the operation.

static const int Exists;

Shared memory region already exists but is being createed.

static const int NonExistent;

Shared memory region does not exist for attach or remove

static const int NoAccess;

The desired access was not allowe by the shared memory protections

static const int NotAttached;

Shared memory section is not attached.

static const int CheckOSError;

Check the underlying operating system's error code.

Permissions bits. These bits provide unix like permissions.

static const int GroupRead;

Allows members of the user's group to read the shared memory section. Such users can attach but no write dereferencdes to the shared memory will work.

static const int GroupWrite;

Allows members of the user's group to write the shared memory. Note that this does not imply read access unless or-ed with GroupRead.

static const int OtherRead;

Allows people that are not in the user's group to read the segment.

static const int OtherWrite;

Allows people that are not in the user's group to write to the segment.