apr_shm.h revision 266735
1251875Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251875Speter * contributor license agreements. See the NOTICE file distributed with 3251875Speter * this work for additional information regarding copyright ownership. 4251875Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251875Speter * (the "License"); you may not use this file except in compliance with 6251875Speter * the License. You may obtain a copy of the License at 7251875Speter * 8251875Speter * http://www.apache.org/licenses/LICENSE-2.0 9251875Speter * 10251875Speter * Unless required by applicable law or agreed to in writing, software 11251875Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251875Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251875Speter * See the License for the specific language governing permissions and 14251875Speter * limitations under the License. 15251875Speter */ 16251875Speter 17251875Speter#ifndef APR_SHM_H 18251875Speter#define APR_SHM_H 19251875Speter 20251875Speter/** 21251875Speter * @file apr_shm.h 22251875Speter * @brief APR Shared Memory Routines 23251875Speter */ 24251875Speter 25251875Speter#include "apr.h" 26251875Speter#include "apr_pools.h" 27251875Speter#include "apr_errno.h" 28251875Speter 29251875Speter#ifdef __cplusplus 30251875Speterextern "C" { 31251875Speter#endif /* __cplusplus */ 32251875Speter 33251875Speter/** 34251875Speter * @defgroup apr_shm Shared Memory Routines 35251875Speter * @ingroup APR 36251875Speter * @{ 37251875Speter */ 38251875Speter 39251875Speter/** 40251875Speter * Private, platform-specific data struture representing a shared memory 41251875Speter * segment. 42251875Speter */ 43251875Spetertypedef struct apr_shm_t apr_shm_t; 44251875Speter 45251875Speter/** 46266735Speter * Create and make accessible a shared memory segment with default 47266735Speter * properties. 48251875Speter * @param m The shared memory structure to create. 49251875Speter * @param reqsize The desired size of the segment. 50251875Speter * @param filename The file to use for shared memory on platforms that 51251875Speter * require it. 52251875Speter * @param pool the pool from which to allocate the shared memory 53251875Speter * structure. 54251875Speter * @remark A note about Anonymous vs. Named shared memory segments: 55251875Speter * Not all plaforms support anonymous shared memory segments, but in 56251875Speter * some cases it is prefered over other types of shared memory 57251875Speter * implementations. Passing a NULL 'file' parameter to this function 58251875Speter * will cause the subsystem to use anonymous shared memory segments. 59251875Speter * If such a system is not available, APR_ENOTIMPL is returned. 60251875Speter * @remark A note about allocation sizes: 61251875Speter * On some platforms it is necessary to store some metainformation 62251875Speter * about the segment within the actual segment. In order to supply 63251875Speter * the caller with the requested size it may be necessary for the 64251875Speter * implementation to request a slightly greater segment length 65251875Speter * from the subsystem. In all cases, the apr_shm_baseaddr_get() 66251875Speter * function will return the first usable byte of memory. 67251875Speter * 68251875Speter */ 69251875SpeterAPR_DECLARE(apr_status_t) apr_shm_create(apr_shm_t **m, 70251875Speter apr_size_t reqsize, 71251875Speter const char *filename, 72251875Speter apr_pool_t *pool); 73251875Speter 74251875Speter/** 75266735Speter * Special processing flags for apr_shm_create_ex() and apr_shm_attach_ex(). 76266735Speter */ 77266735Speter#define APR_SHM_NS_LOCAL 1 /* Create or attach to named shared memory 78266735Speter * segment in the "Local" namespace on 79266735Speter * Windows. (Ignored on other platforms.) 80266735Speter * By default, the "Global" namespace is 81266735Speter * used for privileged processes and the 82266735Speter * "Local" namespace is used otherwise. 83266735Speter */ 84266735Speter#define APR_SHM_NS_GLOBAL 2 /* Create or attach to named shared memory 85266735Speter * segment in the "Global" namespace on 86266735Speter * Windows. (Ignored on other platforms.) 87266735Speter */ 88266735Speter 89266735Speter/** 90266735Speter * Create and make accessible a shared memory segment with platform- 91266735Speter * specific processing. 92266735Speter * @param m The shared memory structure to create. 93266735Speter * @param reqsize The desired size of the segment. 94266735Speter * @param filename The file to use for shared memory on platforms that 95266735Speter * require it. 96266735Speter * @param pool the pool from which to allocate the shared memory 97266735Speter * structure. 98266735Speter * @param flags mask of APR_SHM_* (defined above) 99266735Speter * @remark A note about Anonymous vs. Named shared memory segments: 100266735Speter * Not all plaforms support anonymous shared memory segments, but in 101266735Speter * some cases it is prefered over other types of shared memory 102266735Speter * implementations. Passing a NULL 'file' parameter to this function 103266735Speter * will cause the subsystem to use anonymous shared memory segments. 104266735Speter * If such a system is not available, APR_ENOTIMPL is returned. 105266735Speter * @remark A note about allocation sizes: 106266735Speter * On some platforms it is necessary to store some metainformation 107266735Speter * about the segment within the actual segment. In order to supply 108266735Speter * the caller with the requested size it may be necessary for the 109266735Speter * implementation to request a slightly greater segment length 110266735Speter * from the subsystem. In all cases, the apr_shm_baseaddr_get() 111266735Speter * function will return the first usable byte of memory. 112266735Speter * 113266735Speter */ 114266735SpeterAPR_DECLARE(apr_status_t) apr_shm_create_ex(apr_shm_t **m, 115266735Speter apr_size_t reqsize, 116266735Speter const char *filename, 117266735Speter apr_pool_t *pool, 118266735Speter apr_int32_t flags); 119266735Speter 120266735Speter/** 121251875Speter * Remove named resource associated with a shared memory segment, 122251875Speter * preventing attachments to the resource, but not destroying it. 123251875Speter * @param filename The filename associated with shared-memory segment which 124251875Speter * needs to be removed 125251875Speter * @param pool The pool used for file operations 126251875Speter * @remark This function is only supported on platforms which support 127251875Speter * name-based shared memory segments, and will return APR_ENOTIMPL on 128251875Speter * platforms without such support. Removing the file while the shm 129251875Speter * is in use is not entirely portable, caller may use this to enhance 130266735Speter * obscurity of the resource, but be prepared for the call to fail, 131251875Speter * and for concurrent attempts to create a resource of the same name 132251875Speter * to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) 133251875Speter * also removes the named resource. 134251875Speter */ 135251875SpeterAPR_DECLARE(apr_status_t) apr_shm_remove(const char *filename, 136251875Speter apr_pool_t *pool); 137251875Speter 138251875Speter/** 139251875Speter * Destroy a shared memory segment and associated memory. 140251875Speter * @param m The shared memory segment structure to destroy. 141251875Speter */ 142251875SpeterAPR_DECLARE(apr_status_t) apr_shm_destroy(apr_shm_t *m); 143251875Speter 144251875Speter/** 145251875Speter * Attach to a shared memory segment that was created 146251875Speter * by another process. 147251875Speter * @param m The shared memory structure to create. 148251875Speter * @param filename The file used to create the original segment. 149251875Speter * (This MUST match the original filename.) 150251875Speter * @param pool the pool from which to allocate the shared memory 151251875Speter * structure for this process. 152251875Speter */ 153251875SpeterAPR_DECLARE(apr_status_t) apr_shm_attach(apr_shm_t **m, 154251875Speter const char *filename, 155251875Speter apr_pool_t *pool); 156251875Speter 157251875Speter/** 158266735Speter * Attach to a shared memory segment that was created 159266735Speter * by another process, with platform-specific processing. 160266735Speter * @param m The shared memory structure to create. 161266735Speter * @param filename The file used to create the original segment. 162266735Speter * (This MUST match the original filename.) 163266735Speter * @param pool the pool from which to allocate the shared memory 164266735Speter * structure for this process. 165266735Speter * @param flags mask of APR_SHM_* (defined above) 166266735Speter */ 167266735SpeterAPR_DECLARE(apr_status_t) apr_shm_attach_ex(apr_shm_t **m, 168266735Speter const char *filename, 169266735Speter apr_pool_t *pool, 170266735Speter apr_int32_t flags); 171266735Speter 172266735Speter/** 173251875Speter * Detach from a shared memory segment without destroying it. 174251875Speter * @param m The shared memory structure representing the segment 175251875Speter * to detach from. 176251875Speter */ 177251875SpeterAPR_DECLARE(apr_status_t) apr_shm_detach(apr_shm_t *m); 178251875Speter 179251875Speter/** 180251875Speter * Retrieve the base address of the shared memory segment. 181251875Speter * NOTE: This address is only usable within the callers address 182251875Speter * space, since this API does not guarantee that other attaching 183251875Speter * processes will maintain the same address mapping. 184251875Speter * @param m The shared memory segment from which to retrieve 185251875Speter * the base address. 186251875Speter * @return address, aligned by APR_ALIGN_DEFAULT. 187251875Speter */ 188251875SpeterAPR_DECLARE(void *) apr_shm_baseaddr_get(const apr_shm_t *m); 189251875Speter 190251875Speter/** 191251875Speter * Retrieve the length of a shared memory segment in bytes. 192251875Speter * @param m The shared memory segment from which to retrieve 193251875Speter * the segment length. 194251875Speter */ 195251875SpeterAPR_DECLARE(apr_size_t) apr_shm_size_get(const apr_shm_t *m); 196251875Speter 197251875Speter/** 198251875Speter * Get the pool used by this shared memory segment. 199251875Speter */ 200251875SpeterAPR_POOL_DECLARE_ACCESSOR(shm); 201251875Speter 202251875Speter/** @} */ 203251875Speter 204251875Speter#ifdef __cplusplus 205251875Speter} 206251875Speter#endif 207251875Speter 208251875Speter#endif /* APR_SHM_T */ 209