Shared Memory Routines

Macros
#define	APR_SHM_NS_LOCAL
#define	APR_SHM_NS_GLOBAL

Typedefs
typedef struct apr_shm_t	apr_shm_t

Functions
apr_status_t	apr_shm_create (apr_shm_t **m, apr_size_t reqsize, const char *filename, apr_pool_t *pool)
apr_status_t	apr_shm_create_ex (apr_shm_t **m, apr_size_t reqsize, const char *filename, apr_pool_t *pool, apr_int32_t flags)
apr_status_t	apr_shm_remove (const char *filename, apr_pool_t *pool)
apr_status_t	apr_shm_delete (apr_shm_t *m)
apr_status_t	apr_shm_destroy (apr_shm_t *m)
apr_status_t	apr_shm_attach (apr_shm_t **m, const char *filename, apr_pool_t *pool)
apr_status_t	apr_shm_attach_ex (apr_shm_t **m, const char *filename, apr_pool_t *pool, apr_int32_t flags)
apr_status_t	apr_shm_detach (apr_shm_t *m)
void *	apr_shm_baseaddr_get (const apr_shm_t *m)
apr_size_t	apr_shm_size_get (const apr_shm_t *m)
	APR_PERMS_SET_IMPLEMENT (shm)
apr_pool_t *	apr_shm_pool_get (const apr_shm_t *theshm)

Detailed Description

Macro Definition Documentation

APR_SHM_NS_GLOBAL

#define APR_SHM_NS_GLOBAL

Value:

2 /* Create or attach to named shared memory
                               * segment in the "Global" namespace on
                               * Windows.  (Ignored on other platforms.)
                               */

APR_SHM_NS_LOCAL

#define APR_SHM_NS_LOCAL

Value:

1 /* Create or attach to named shared memory
                               * segment in the "Local" namespace on
                               * Windows.  (Ignored on other platforms.)
                               * By default, the "Global" namespace is
                               * used for privileged processes and the
                               * "Local" namespace is used otherwise.
                               */

Special processing flags for apr_shm_create_ex() and apr_shm_attach_ex().

Typedef Documentation

apr_shm_t

typedef struct apr_shm_t apr_shm_t

Private, platform-specific data struture representing a shared memory segment.

Function Documentation

APR_PERMS_SET_IMPLEMENT()

APR_PERMS_SET_IMPLEMENT

(

shm

)

Set shared memory permissions.

apr_shm_attach()

apr_status_t apr_shm_attach	(	apr_shm_t **	m,
		const char *	filename,
		apr_pool_t *	pool
	)

Attach to a shared memory segment that was created by another process.

Parameters

m	The shared memory structure to create.
filename	The file used to create the original segment. (This MUST match the original filename.)
pool	the pool from which to allocate the shared memory structure for this process.

apr_shm_attach_ex()

apr_status_t apr_shm_attach_ex	(	apr_shm_t **	m,
		const char *	filename,
		apr_pool_t *	pool,
		apr_int32_t	flags
	)

Attach to a shared memory segment that was created by another process, with platform-specific processing.

Parameters

m	The shared memory structure to create.
filename	The file used to create the original segment. (This MUST match the original filename.)
pool	the pool from which to allocate the shared memory structure for this process.
flags	mask of APR_SHM_* (defined above)

apr_shm_baseaddr_get()

void* apr_shm_baseaddr_get

(

const apr_shm_t *

m

)

Retrieve the base address of the shared memory segment. NOTE: This address is only usable within the callers address space, since this API does not guarantee that other attaching processes will maintain the same address mapping.

Parameters

m	The shared memory segment from which to retrieve the base address.

Returns

address, aligned by APR_ALIGN_DEFAULT.

apr_shm_create()

apr_status_t apr_shm_create	(	apr_shm_t **	m,
		apr_size_t	reqsize,
		const char *	filename,
		apr_pool_t *	pool
	)

Create and make accessible a shared memory segment with default properties.

Parameters

m	The shared memory structure to create.
reqsize	The desired size of the segment.
filename	The file to use for shared memory on platforms that require it.
pool	the pool from which to allocate the shared memory structure.

Remarks

A note about Anonymous vs. Named shared memory segments: Not all plaforms support anonymous shared memory segments, but in some cases it is prefered over other types of shared memory implementations. Passing a NULL 'file' parameter to this function will cause the subsystem to use anonymous shared memory segments. If such a system is not available, APR_ENOTIMPL is returned.

A note about allocation sizes: On some platforms it is necessary to store some metainformation about the segment within the actual segment. In order to supply the caller with the requested size it may be necessary for the implementation to request a slightly greater segment length from the subsystem. In all cases, the apr_shm_baseaddr_get() function will return the first usable byte of memory.

apr_shm_create_ex()

apr_status_t apr_shm_create_ex	(	apr_shm_t **	m,
		apr_size_t	reqsize,
		const char *	filename,
		apr_pool_t *	pool,
		apr_int32_t	flags
	)

Create and make accessible a shared memory segment with platform- specific processing.

Parameters

m	The shared memory structure to create.
reqsize	The desired size of the segment.
filename	The file to use for shared memory on platforms that require it.
pool	the pool from which to allocate the shared memory structure.
flags	mask of APR_SHM_* (defined above)

Remarks

A note about Anonymous vs. Named shared memory segments: Not all plaforms support anonymous shared memory segments, but in some cases it is prefered over other types of shared memory implementations. Passing a NULL 'file' parameter to this function will cause the subsystem to use anonymous shared memory segments. If such a system is not available, APR_ENOTIMPL is returned.

A note about allocation sizes: On some platforms it is necessary to store some metainformation about the segment within the actual segment. In order to supply the caller with the requested size it may be necessary for the implementation to request a slightly greater segment length from the subsystem. In all cases, the apr_shm_baseaddr_get() function will return the first usable byte of memory.

apr_shm_delete()

apr_status_t apr_shm_delete

(

apr_shm_t *

m

)

Delete named resource associated with a shared memory segment, preventing attachments to the resource.

Parameters

m	The shared memory segment structure to delete.

Remarks

This function is only supported on platforms which support name-based shared memory segments, and will return APR_ENOTIMPL on platforms without such support. Removing the file while the shm is in use is not entirely portable, caller may use this to enhance obscurity of the resource, but be prepared for the call to fail, and for concurrent attempts to create a resource of the same name to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) also removes the named resource.

apr_shm_destroy()

apr_status_t apr_shm_destroy

(

apr_shm_t *

m

)

Destroy a shared memory segment and associated memory.

Parameters

m	The shared memory segment structure to destroy.

apr_shm_detach()

apr_status_t apr_shm_detach

(

apr_shm_t *

m

)

Detach from a shared memory segment without destroying it.

Parameters

m	The shared memory structure representing the segment to detach from.

apr_shm_pool_get()

apr_pool_t* apr_shm_pool_get

(

const apr_shm_t *

theshm

)

Get the pool used by this shared memory segment.

apr_shm_remove()

apr_status_t apr_shm_remove	(	const char *	filename,
		apr_pool_t *	pool
	)

Remove named resource associated with a shared memory segment, preventing attachments to the resource, but not destroying it.

Parameters

filename	The filename associated with shared-memory segment which needs to be removed
pool	The pool used for file operations

Remarks

This function is only supported on platforms which support name-based shared memory segments, and will return APR_ENOTIMPL on platforms without such support. Removing the file while the shm is in use is not entirely portable, caller may use this to enhance obscurity of the resource, but be prepared for the call to fail, and for concurrent attempts to create a resource of the same name to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) also removes the named resource.

apr_shm_size_get()

apr_size_t apr_shm_size_get

(

const apr_shm_t *

m

)

Retrieve the length of a shared memory segment in bytes.

Parameters

m	The shared memory segment from which to retrieve the segment length.