apr_shm.h
Go to the documentation of this file.00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_SHM_H 00018 #define APR_SHM_H 00019 00020 /** 00021 * @file apr_shm.h 00022 * @brief APR Shared Memory Routines 00023 */ 00024 00025 #include "apr.h" 00026 #include "apr_pools.h" 00027 #include "apr_errno.h" 00028 00029 #ifdef __cplusplus 00030 extern "C" { 00031 #endif /* __cplusplus */ 00032 00033 /** 00034 * @defgroup apr_shm Shared Memory Routines 00035 * @ingroup APR 00036 * @{ 00037 */ 00038 00039 /** 00040 * Private, platform-specific data struture representing a shared memory 00041 * segment. 00042 */ 00043 typedef struct apr_shm_t apr_shm_t; 00044 00045 /** 00046 * Create and make accessible a shared memory segment with default 00047 * properties. 00048 * @param m The shared memory structure to create. 00049 * @param reqsize The desired size of the segment. 00050 * @param filename The file to use for shared memory on platforms that 00051 * require it. 00052 * @param pool the pool from which to allocate the shared memory 00053 * structure. 00054 * @remark A note about Anonymous vs. Named shared memory segments: 00055 * Not all plaforms support anonymous shared memory segments, but in 00056 * some cases it is prefered over other types of shared memory 00057 * implementations. Passing a NULL 'file' parameter to this function 00058 * will cause the subsystem to use anonymous shared memory segments. 00059 * If such a system is not available, APR_ENOTIMPL is returned. 00060 * @remark A note about allocation sizes: 00061 * On some platforms it is necessary to store some metainformation 00062 * about the segment within the actual segment. In order to supply 00063 * the caller with the requested size it may be necessary for the 00064 * implementation to request a slightly greater segment length 00065 * from the subsystem. In all cases, the apr_shm_baseaddr_get() 00066 * function will return the first usable byte of memory. 00067 * 00068 */ 00069 APR_DECLARE(apr_status_t) apr_shm_create(apr_shm_t **m, 00070 apr_size_t reqsize, 00071 const char *filename, 00072 apr_pool_t *pool); 00073 00074 /** 00075 * Special processing flags for apr_shm_create_ex() and apr_shm_attach_ex(). 00076 */ 00077 #define APR_SHM_NS_LOCAL 1 /* Create or attach to named shared memory 00078 * segment in the "Local" namespace on 00079 * Windows. (Ignored on other platforms.) 00080 * By default, the "Global" namespace is 00081 * used for privileged processes and the 00082 * "Local" namespace is used otherwise. 00083 */ 00084 #define APR_SHM_NS_GLOBAL 2 /* Create or attach to named shared memory 00085 * segment in the "Global" namespace on 00086 * Windows. (Ignored on other platforms.) 00087 */ 00088 00089 /** 00090 * Create and make accessible a shared memory segment with platform- 00091 * specific processing. 00092 * @param m The shared memory structure to create. 00093 * @param reqsize The desired size of the segment. 00094 * @param filename The file to use for shared memory on platforms that 00095 * require it. 00096 * @param pool the pool from which to allocate the shared memory 00097 * structure. 00098 * @param flags mask of APR_SHM_* (defined above) 00099 * @remark A note about Anonymous vs. Named shared memory segments: 00100 * Not all plaforms support anonymous shared memory segments, but in 00101 * some cases it is prefered over other types of shared memory 00102 * implementations. Passing a NULL 'file' parameter to this function 00103 * will cause the subsystem to use anonymous shared memory segments. 00104 * If such a system is not available, APR_ENOTIMPL is returned. 00105 * @remark A note about allocation sizes: 00106 * On some platforms it is necessary to store some metainformation 00107 * about the segment within the actual segment. In order to supply 00108 * the caller with the requested size it may be necessary for the 00109 * implementation to request a slightly greater segment length 00110 * from the subsystem. In all cases, the apr_shm_baseaddr_get() 00111 * function will return the first usable byte of memory. 00112 * 00113 */ 00114 APR_DECLARE(apr_status_t) apr_shm_create_ex(apr_shm_t **m, 00115 apr_size_t reqsize, 00116 const char *filename, 00117 apr_pool_t *pool, 00118 apr_int32_t flags); 00119 00120 /** 00121 * Remove named resource associated with a shared memory segment, 00122 * preventing attachments to the resource, but not destroying it. 00123 * @param filename The filename associated with shared-memory segment which 00124 * needs to be removed 00125 * @param pool The pool used for file operations 00126 * @remark This function is only supported on platforms which support 00127 * name-based shared memory segments, and will return APR_ENOTIMPL on 00128 * platforms without such support. Removing the file while the shm 00129 * is in use is not entirely portable, caller may use this to enhance 00130 * obscurity of the resource, but be prepared for the call to fail, 00131 * and for concurrent attempts to create a resource of the same name 00132 * to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) 00133 * also removes the named resource. 00134 */ 00135 APR_DECLARE(apr_status_t) apr_shm_remove(const char *filename, 00136 apr_pool_t *pool); 00137 00138 /** 00139 * Destroy a shared memory segment and associated memory. 00140 * @param m The shared memory segment structure to destroy. 00141 */ 00142 APR_DECLARE(apr_status_t) apr_shm_destroy(apr_shm_t *m); 00143 00144 /** 00145 * Attach to a shared memory segment that was created 00146 * by another process. 00147 * @param m The shared memory structure to create. 00148 * @param filename The file used to create the original segment. 00149 * (This MUST match the original filename.) 00150 * @param pool the pool from which to allocate the shared memory 00151 * structure for this process. 00152 */ 00153 APR_DECLARE(apr_status_t) apr_shm_attach(apr_shm_t **m, 00154 const char *filename, 00155 apr_pool_t *pool); 00156 00157 /** 00158 * Attach to a shared memory segment that was created 00159 * by another process, with platform-specific processing. 00160 * @param m The shared memory structure to create. 00161 * @param filename The file used to create the original segment. 00162 * (This MUST match the original filename.) 00163 * @param pool the pool from which to allocate the shared memory 00164 * structure for this process. 00165 * @param flags mask of APR_SHM_* (defined above) 00166 */ 00167 APR_DECLARE(apr_status_t) apr_shm_attach_ex(apr_shm_t **m, 00168 const char *filename, 00169 apr_pool_t *pool, 00170 apr_int32_t flags); 00171 00172 /** 00173 * Detach from a shared memory segment without destroying it. 00174 * @param m The shared memory structure representing the segment 00175 * to detach from. 00176 */ 00177 APR_DECLARE(apr_status_t) apr_shm_detach(apr_shm_t *m); 00178 00179 /** 00180 * Retrieve the base address of the shared memory segment. 00181 * NOTE: This address is only usable within the callers address 00182 * space, since this API does not guarantee that other attaching 00183 * processes will maintain the same address mapping. 00184 * @param m The shared memory segment from which to retrieve 00185 * the base address. 00186 * @return address, aligned by APR_ALIGN_DEFAULT. 00187 */ 00188 APR_DECLARE(void *) apr_shm_baseaddr_get(const apr_shm_t *m); 00189 00190 /** 00191 * Retrieve the length of a shared memory segment in bytes. 00192 * @param m The shared memory segment from which to retrieve 00193 * the segment length. 00194 */ 00195 APR_DECLARE(apr_size_t) apr_shm_size_get(const apr_shm_t *m); 00196 00197 /** 00198 * Get the pool used by this shared memory segment. 00199 */ 00200 APR_POOL_DECLARE_ACCESSOR(shm); 00201 00202 /** @} */ 00203 00204 #ifdef __cplusplus 00205 } 00206 #endif 00207 00208 #endif /* APR_SHM_T */
