Support for shared memory buffers

Support for shared memory buffers. More...

Files
file	hqnshm.h
	Header file defining Support for shared memory buffers.

Macros
#define	LONGESTSHMNAME   1024
	Longest unreduced shared memory buffer name. More...

Functions
void *	shm_create_buffer (const char *name, size_t size, HqnResult *perr)
	Create a shared memory buffer with the size specified. More...
void *	shm_open_buffer (const char *name, HqnResult *perr)
	Try to open an existing shared memory buffer with the size specified. More...
const char *	shm_buffer_name (void *addr)
	Return the name of a shared memory object. More...
void	shm_close_buffer (void *addr)
	Remove a view of a shared memory buffer from this process. More...

Detailed Description

Support for shared memory buffers.

This interface provides support for creating, opening, and closing fixed-size shared memory buffers. The shared memory support follows the same semantics as Windows:

• Shared memory buffers have their size fixed on creation;
• Shared memory buffers may be opened by multiple processes simultaneously. After a full memory barrier, any data written to a shared memory buffer will be visible by all processes with an open mapping.
• The memory address of the shared memory buffers is expected to be different in different processes, and even in multiple views of the same object in the same process (if supported). Do not store pointers to data structures in shared memory buffers.
• Shared memory buffers exist so long as any process has an open handle to the buffer. When the last process with an open handle to an buffer calls shm_close_buffer(), the shared memory buffer is deleted.
• The operating system may impose restrictions on which processes may open a shared memory buffer. On Windows, only processes in the same Terminal Session may open shared memory buffers created by shm_create_buffer().

The shm_create_buffer() function is used to create a shared memory buffer, returning the address of the buffer in that process. Any eligible process may then call shm_open_buffer() to return an address mapping the shared memory buffer. The shm_close_buffer() function must be used to unmap a view of the shared memory buffer returned by shm_create_buffer() or shm_open_buffer().

It is the client's responsibility to ensure that processes wishing to share a memory buffer call shm_create_buffer() and shm_open_buffer() in the correct order, and that the process creating the buffer does not close the buffer before a process needing to share the buffer has opened it.

The name passed to the shm_create_buffer() and shm_open_buffer() may be modified to conform with operating system restrictions, so clients should not assume they can access the shared memory buffer using platform native API functions. Always use shm_close_buffer() to close handles to shared memory buffers this interface created or opened.

Shared memory buffers may be created before the RIP is started, and may be closed after the RIP is terminated.

The shm_buffer_name() function may be used to get a name that may be sent to another process and used with shm_open_buffer() to get a view of the same shared memory object.

Macro Definition Documentation

LONGESTSHMNAME

#define LONGESTSHMNAME   1024

Longest unreduced shared memory buffer name.

Shared memory buffer names may be modified by the shared memory support to comply with platform conventions or other limitations. All shared memory buffers should be opened using the shm_create_buffer() or shm_open_buffer() functions, and closed using shm_close_buffer().

Function Documentation

shm_buffer_name()

const char* shm_buffer_name

(

void *

addr

)

Return the name of a shared memory object.

Parameters

[in]

addr

The pointer to shared memory buffer to get the name of. This pointer must have been returned by shm_create_buffer() or shm_open_buffer().

Returns

A zero-terminated name of the shared memory object, or NULL if the shared memory object is not known. This pointer will remain valid until the view of the shared memory object is removed from this process using shm_close_buffer(). This name may be sent to another process and used by shm_open_buffer() to open another handle on a shared memory object.

shm_close_buffer()

void shm_close_buffer

(

void *

addr

)

Remove a view of a shared memory buffer from this process.

Parameters

[in]

addr

The pointer to shared memory that is no longer required. This pointer must have been returned by shm_create_buffer() or shm_open_buffer().

If this is the last reference to the shared memory buffer in any process, the shared memory buffer will be deleted.

Shared memory buffers may be created, opened, and closed at any time, including periods when the RIP is not running.

shm_create_buffer()

void* shm_create_buffer	(	const char *	name,
		size_t	size,
		HqnResult *	perr
	)

Create a shared memory buffer with the size specified.

Parameters

[in]	name	A zero-terminated string containing the name of the shared memory buffer.
[in]	size	The size of the shared memory buffer.
[out]	perr	A location in which an error code is stored, if the shared memory buffer could not be created. The value in this location is not changed if the shared memory buffer was created.

Returns

A pointer to the shared memory buffer, or NULL if it could not be created. If a non-NULL pointer is returned, the shared memory buffer must be closed by calling shm_close_buffer().

Shared memory buffers may be created any time, including periods when the RIP is not running.

If this function fails, *perr will be set to:

• MON_INVALIDFILEACCESS_SHM_CREATE if the shared memory object could not be created.
• MON_INVALIDACCESS_SHM_CREATE if a view of the shared memory object could not be mapped into memory.
• MON_LIMITCHECK_SHM_HANDLEMAP if the shared memory address could not be stored in the internal handle map.
• MON_VMERROR if an internal memory allocation error occurred.

shm_open_buffer()

void* shm_open_buffer	(	const char *	name,
		HqnResult *	perr
	)

Try to open an existing shared memory buffer with the size specified.

Parameters

[in]	name	A zero-terminated string containing the name of the shared memory buffer.
[out]	perr	A location in which an error code is stored, if the shared memory buffer could not be opened. The value in this location is not changed if the shared memory buffer was opened.

Returns

A pointer to the shared memory buffer, or NULL if it did not exist, or there was an error mapping the buffer. If a non-NULL pointer is returned, the shared memory buffer must be closed by calling shm_close_buffer().

Shared memory buffers may be opened any time, including periods when the RIP is not running.

If this function fails, *perr will be set to:

• MON_UNDEFINEDFILENAME_SHM_OPEN if the shared memory object does not exist.
• MON_INVALIDFILEACCESS_SHM_OPEN if the shared memory object existed but could not be opened.
• MON_INVALIDACCESS_SHM_OPEN if a view of the shared memory object could not be mapped into memory.
• MON_LIMITCHECK_SHM_HANDLEMAP if the shared memory address could not be stored in the internal handle map.
• MON_VMERROR if an internal memory allocation error occurred.