Easier Shared-Memory Functions

Declared:

#include <DML_shmem.h>

Description

These five functions are designed to streamline the shared-memory creation process. They are used by the ShMem template class, and unlike that class can be used to create simple built-in type shared memory objects, i.e. a shared int variable or a shared double. The three basic functions provide a way to create a shared memory object (or connect to one that already exists), disconnect from a shared memory object, and completely destroy a shared memory object. The two other functions provide a way to split the creation process up into two parts, so as to get access to the file-descriptor. It is unlikely that you'll need to do this.

Function Prototypes

void * create_shm( const char *, size_t, int oflag )
void close_shm( const char * )
void destroy_shm( const char * )
int open_shm_fd( const char *, size_t, int oflag )
void * map_shm( int fd, size_t, int oflag )

See Also:

ShMem template class, shm_open, shm_close, shm_create in the QNX help files

 

Module Functions

create_shm

Synopsis:

#include <DML_shmem.h>


void * create_shm( const char * filename, size_t sz, int oflag )

Semantics:

This function streamlines the creation of shared memory objects. Sure, it leaves out a few obscure options, but hey, it does the filedescriptor opening, memory mapping, and protection stuff all in one line.

Code Dissection:

This function is just a cover for the open_shm_fd and map_shm functions.

Results:

Returns a void * pointer, which must be immediately cast to the correct type of pointer and assigned to a variable pointer of that type, otherwise you're going to lose access to the shared memory you just created.

See Also:

open_shm_fd, map_shm

 

close_shm

Synopsis:

#include <DML_shmem.h>


void close_shm( const char * )

Semantics:

This is a cover for the POSIX function shm_unlink, which is supposed to unlink the shared memory object from the current process, and then if this is the only process attached, destroy the shared memory in question. Alas, it doesn't do this: it always destroys the shared memory. So this function checks to see how many links exist to this shared memory object, and if there's only one, then it destroys the shared memory.

Code Dissection:

This function uses the 'stat' function, which gets information about a file. Included in that information is the number of open links to the file.

Results:

The shared memory object is destroyed only if there is only one reference to it.

See Also:

stat, shm_unlink

 

destroy_shm

Synopsis:

#include <DML_shmem.h>


void destroy_shm( const char * )

Semantics:

This function completely destroys the shared memory with the input name. If that shared memory object doesn't exist, no action is taken. This will break the link between processes sharing the shared memory, and they will likely crash as well, so this funciton is usually only used at process termination, in a clean-up type way, and only for the shared memory objects that the process itself created, or expects to be unused once termination occurs.

Code Dissection:

This is a cover for the shm_unlink function, which doesn't work the way it's supposed to. I could have used the remove() function instead. This function also checks to see if there's an error, and displays an appropriate message.

Results:

The shared memory is completely destroyed, if it exists.

See Also:

shm_unlink

 

open_shm_fd

Synopsis:

#include <DML_shmem.h>


int open_shm_fd( const char *, size_t, int oflag )

Semantics:

There are two steps to creating shared memory: opening up the file-system for the shared memory, which will keep track of it, and mapping the shared memory into local memory. This function takes care of the first of those two tasks. Specifically, it goes to the file system and requests a file descriptor for the new shared memory 'file'. It then checks to see if the 'file' already exists, and if it does, it opens up the existing 'file' (memory location). If not, it creates a new 'file'. The file descriptor is used in the mapping process.

Currently the only supported oflags are O_RDWR and O_RDONLY.

Code Dissection:

The function tries to create a new shared memory object. If creation fails, and the reason was that the file already existed, it tries to open up the existing file. It uses the functions shm_create, and shm_open, which are POSIX standard functions. The shared memory opened up is limited in granularity to memory page sizes, so the function must then truncate the memory opened up, so that it can be reclaimed.

Results:

The function returns the file descriptor of the shared memory object, which is then used by the map_shm function.

See Also:

ltrunc, shm_create, shm_open, map_shm

 

map_shm

Synopsis:

#include <DML_shmem.h>


void * map_shm( int fd, size_t, int oflag )

Semantics:

This function maps the shared memory from a file descriptor to a C address pointer. Be careful to cast the return value of this function correctly, according to the type of shared memory you're creating. The only oflags accepted are O_RDWR and O_RDONLY. If there is an error, a message is printed to stdout.

Code Dissection:

This function is just a cover for the mmap() function.

Results:

Returns a pointer to the shared memory object, or ((void * ) -1 ) if there was an error.

See Also:

mmap