00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as 00002 * applicable. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * 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 accessable a shared memory segment. 00047 * @param m The shared memory structure to create. 00048 * @param reqsize The desired size of the segment. 00049 * @param filename The file to use for shared memory on platforms that 00050 * require it. 00051 * @param pool the pool from which to allocate the shared memory 00052 * structure. 00053 * @remark A note about Anonymous vs. Named shared memory segments: 00054 * Not all plaforms support anonymous shared memory segments, but in 00055 * some cases it is prefered over other types of shared memory 00056 * implementations. Passing a NULL 'file' parameter to this function 00057 * will cause the subsystem to use anonymous shared memory segments. 00058 * If such a system is not available, APR_ENOTIMPL is returned. 00059 * @remark A note about allocation sizes: 00060 * On some platforms it is necessary to store some metainformation 00061 * about the segment within the actual segment. In order to supply 00062 * the caller with the requested size it may be necessary for the 00063 * implementation to request a slightly greater segment length 00064 * from the subsystem. In all cases, the apr_shm_baseaddr_get() 00065 * function will return the first usable byte of memory. 00066 * 00067 */ 00068 APR_DECLARE(apr_status_t) apr_shm_create(apr_shm_t **m, 00069 apr_size_t reqsize, 00070 const char *filename, 00071 apr_pool_t *pool); 00072 00073 /** 00074 * Remove shared memory segment associated with a filename. 00075 * @param filename The filename associated with shared-memory segment which 00076 * needs to be removed 00077 * @param pool The pool used for file operations 00078 * @remark This function is only supported on platforms which support 00079 * name-based shared memory segments, and will return APR_ENOTIMPL on 00080 * platforms without such support. 00081 */ 00082 APR_DECLARE(apr_status_t) apr_shm_remove(const char *filename, 00083 apr_pool_t *pool); 00084 00085 /** 00086 * Destroy a shared memory segment and associated memory. 00087 * @param m The shared memory segment structure to destroy. 00088 */ 00089 APR_DECLARE(apr_status_t) apr_shm_destroy(apr_shm_t *m); 00090 00091 /** 00092 * Attach to a shared memory segment that was created 00093 * by another process. 00094 * @param m The shared memory structure to create. 00095 * @param filename The file used to create the original segment. 00096 * (This MUST match the original filename.) 00097 * @param pool the pool from which to allocate the shared memory 00098 * structure for this process. 00099 */ 00100 APR_DECLARE(apr_status_t) apr_shm_attach(apr_shm_t **m, 00101 const char *filename, 00102 apr_pool_t *pool); 00103 00104 /** 00105 * Detach from a shared memory segment without destroying it. 00106 * @param m The shared memory structure representing the segment 00107 * to detach from. 00108 */ 00109 APR_DECLARE(apr_status_t) apr_shm_detach(apr_shm_t *m); 00110 00111 /** 00112 * Retrieve the base address of the shared memory segment. 00113 * NOTE: This address is only usable within the callers address 00114 * space, since this API does not guarantee that other attaching 00115 * processes will maintain the same address mapping. 00116 * @param m The shared memory segment from which to retrieve 00117 * the base address. 00118 * @return address, aligned by APR_ALIGN_DEFAULT. 00119 */ 00120 APR_DECLARE(void *) apr_shm_baseaddr_get(const apr_shm_t *m); 00121 00122 /** 00123 * Retrieve the length of a shared memory segment in bytes. 00124 * @param m The shared memory segment from which to retrieve 00125 * the segment length. 00126 */ 00127 APR_DECLARE(apr_size_t) apr_shm_size_get(const apr_shm_t *m); 00128 00129 /** 00130 * Get the pool used by this shared memory segment. 00131 */ 00132 APR_POOL_DECLARE_ACCESSOR(shm); 00133 00134 /** @} */ 00135 00136 #ifdef __cplusplus 00137 } 00138 #endif 00139 00140 #endif /* APR_SHM_T */