NSCL DAQ Software Documentation
PrevNext

Chapter 52. Shared memory

The shared memory library, libshm provides operating system independent access to shared memory objects.

This library is available for general use, however it's primary use is to improve portability of the RingBuffer software within the NSCL DAQ system.

To use the software, you must

Reference information is available in the reference section

52.1. Overview of the API, and using it from within your C++ software

The API is implemented as a C++ class named CDaqSHM with the following static methods:

Note that the class is not threadsafe in that the error status information is static and therefore shared between all threads without any interlocking.

The sample program below creates a new shared memory region (if the region does not yet exist), obtains a pointer to it, then some time later detaches from it. The create and attach calls also illustrate error management.

Example 52-1. Shared memory library example


#include <daqshm.h>                            (1)
#include <string>
...

// Create the shared memory region.. report any error except
// that the region already exists:

bool status = CDAQShm::create("mymemory", 0x10000,    (2)
                            CDAQShm::GroupRead | CDAQShm::GroupWrite |
                            CDAQShm::OtherRead | CDAQShm::OtherWrite);
if (status && (CDAQShm::lastError() != CDAQShm::Exists)) { (3)
    std::string exception = "Failed to create new shared memory mymemory: ";
    exception += CDAQShm::errorMessage(CDAQShm::lastError());
    throw exception;
}

// Attach to the region:

void* pMemory = CDAQShm::attach("mymemory");     (4)
if (!pMemory) {
    std::string exception = "Failed to attach to shared memory mymemory: ";
    exception            += CDAQShm::errorMesszage(CDAQShm::lastError());
    throw exception;
}

// At this  time pMemory can be used to read/write the shared memory region.

....

if (CDAQShm::detach(pMemory, "mymemory", 0x10000)) {   (5)
    std::string exception = "Failed to detach mymemory: ";
    exception += CDAQShm::errorMessage(CDAQShm::lastError());
}
(1)
Includes the header for the NSCLDAQ shared memory API. See Compiling/Linking your software with the shared memory API for information that describes how to ensure this header will be found by the compiler.
(2)
Attempts to crate the shared memory. The return value of this method will be true on error. The first parameter is the name of the shared memory regiuon. The second its size in bytes. The last an or of masks that describe how users other than the creator can access the region. The owner will always have read/write access.
(3)
If the creation failed for any other reason than the region already existing (CDAQShm::Exists), an exception of type std::string is thrown. The contents of the string provide context for the exception as well as the reason the creation failed.
(4)
Attaches to the shared memory region. The return value a pointer to the shared memory if successful or a null pointer if not. In this example, once more a string exception describing the failure is constructed and thrown if the attach failed.

Once the attach has been done, the shared memory can be accessed through the pointer.

(5)
Detaches from the memory. After the detach, no gaurantees are made about the pointer returned from the attach call and it therefore should not be dereferences

true is returned on error and once more the example code throws a descriptive string exception.

PrevHomeNext
Parsing and URIsUpCompiling/Linking your software with the shared memory API