00001 /* Copyright 2000-2004 The Apache Software Foundation 00002 * 00003 * Licensed under the Apache License, Version 2.0 (the "License"); 00004 * you may not use this file except in compliance with the License. 00005 * You may obtain a copy of the License at 00006 * 00007 * http://www.apache.org/licenses/LICENSE-2.0 00008 * 00009 * Unless required by applicable law or agreed to in writing, software 00010 * distributed under the License is distributed on an "AS IS" BASIS, 00011 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00012 * See the License for the specific language governing permissions and 00013 * limitations under the License. 00014 */ 00015 00016 #ifndef APR_SHM_H 00017 #define APR_SHM_H 00018 00019 /** 00020 * @file apr_shm.h 00021 * @brief APR Shared Memory Routines 00022 */ 00023 00024 #include "apr.h" 00025 #include "apr_pools.h" 00026 #include "apr_errno.h" 00027 00028 #ifdef __cplusplus 00029 extern "C" { 00030 #endif /* __cplusplus */ 00031 00032 /** 00033 * @defgroup apr_shm Shared Memory Routines 00034 * @ingroup APR 00035 * @{ 00036 */ 00037 00038 /** 00039 * Private, platform-specific data struture representing a shared memory 00040 * segment. 00041 */ 00042 typedef struct apr_shm_t apr_shm_t; 00043 00044 /** 00045 * Create and make accessable a shared memory segment. 00046 * @param m The shared memory structure to create. 00047 * @param reqsize The desired size of the segment. 00048 * @param filename The file to use for shared memory on platforms that 00049 * require it. 00050 * @param pool the pool from which to allocate the shared memory 00051 * structure. 00052 * @remark A note about Anonymous vs. Named shared memory segments: 00053 * Not all plaforms support anonymous shared memory segments, but in 00054 * some cases it is prefered over other types of shared memory 00055 * implementations. Passing a NULL 'file' parameter to this function 00056 * will cause the subsystem to use anonymous shared memory segments. 00057 * If such a system is not available, APR_ENOTIMPL is returned. 00058 * @remark A note about allocation sizes: 00059 * On some platforms it is necessary to store some metainformation 00060 * about the segment within the actual segment. In order to supply 00061 * the caller with the requested size it may be necessary for the 00062 * implementation to request a slightly greater segment length 00063 * from the subsystem. In all cases, the apr_shm_baseaddr_get() 00064 * function will return the first usable byte of memory. 00065 * 00066 */ 00067 APR_DECLARE(apr_status_t) apr_shm_create(apr_shm_t **m, 00068 apr_size_t reqsize, 00069 const char *filename, 00070 apr_pool_t *pool); 00071 00072 /** 00073 * Remove shared memory segment associated with a filename. 00074 * @param filename The filename associated with shared-memory segment which 00075 * needs to be removed 00076 * @param pool The pool used for file operations 00077 * @remark This function is only supported on platforms which support 00078 * name-based shared memory segments, and will return APR_ENOTIMPL on 00079 * platforms without such support. 00080 */ 00081 APR_DECLARE(apr_status_t) apr_shm_remove(const char *filename, 00082 apr_pool_t *pool); 00083 00084 /** 00085 * Destroy a shared memory segment and associated memory. 00086 * @param m The shared memory segment structure to destroy. 00087 */ 00088 APR_DECLARE(apr_status_t) apr_shm_destroy(apr_shm_t *m); 00089 00090 /** 00091 * Attach to a shared memory segment that was created 00092 * by another process. 00093 * @param m The shared memory structure to create. 00094 * @param filename The file used to create the original segment. 00095 * (This MUST match the original filename.) 00096 * @param pool the pool from which to allocate the shared memory 00097 * structure for this process. 00098 */ 00099 APR_DECLARE(apr_status_t) apr_shm_attach(apr_shm_t **m, 00100 const char *filename, 00101 apr_pool_t *pool); 00102 00103 /** 00104 * Detach from a shared memory segment without destroying it. 00105 * @param m The shared memory structure representing the segment 00106 * to detach from. 00107 */ 00108 APR_DECLARE(apr_status_t) apr_shm_detach(apr_shm_t *m); 00109 00110 /** 00111 * Retrieve the base address of the shared memory segment. 00112 * NOTE: This address is only usable within the callers address 00113 * space, since this API does not guarantee that other attaching 00114 * processes will maintain the same address mapping. 00115 * @param m The shared memory segment from which to retrieve 00116 * the base address. 00117 */ 00118 APR_DECLARE(void *) apr_shm_baseaddr_get(const apr_shm_t *m); 00119 00120 /** 00121 * Retrieve the length of a shared memory segment in bytes. 00122 * @param m The shared memory segment from which to retrieve 00123 * the segment length. 00124 */ 00125 APR_DECLARE(apr_size_t) apr_shm_size_get(const apr_shm_t *m); 00126 00127 /** 00128 * Get the pool used by this shared memory segment. 00129 */ 00130 APR_POOL_DECLARE_ACCESSOR(shm); 00131 00132 /** @} */ 00133 00134 #ifdef __cplusplus 00135 } 00136 #endif 00137 00138 #endif /* APR_SHM_T */