1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements. See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
20 /* Memory handler for a shared memory divided in slot.
24 * @brief Memory Slot Extension Storage Module for Apache
27 * @ingroup APACHE_MODS
32 #include "http_config.h"
34 #include "ap_provider.h"
37 #include "apr_strings.h"
38 #include "apr_pools.h"
40 #include "apr_global_mutex.h"
41 #include "apr_file_io.h"
43 #ifdef AP_NEED_SET_MUTEX_PERMS
48 #include <unistd.h> /* for getpid() */
51 #define AP_SLOTMEM_STORAGE "slotmem"
53 typedef struct ap_slotmem_t ap_slotmem_t;
56 * callback function used for slotmem.
57 * @param mem is the memory associated with a worker.
58 * @param data is what is passed to slotmem.
59 * @param pool is pool used to create scoreboard
60 * @return APR_SUCCESS if all went well
62 typedef apr_status_t ap_slotmem_callback_fn_t(void* mem, void *data, apr_pool_t *pool);
64 struct ap_slotmem_storage_method {
66 * Name of the provider method
70 * call the callback on all worker slots
71 * @param s ap_slotmem_t to use.
72 * @param funct callback function to call for each element.
73 * @param data parameter for the callback function.
74 * @param pool is pool used to create scoreboard
75 * @return APR_SUCCESS if all went well
77 apr_status_t (* slotmem_do)(ap_slotmem_t *s, ap_slotmem_callback_fn_t *func, void *data, apr_pool_t *pool);
79 * create a new slotmem with each item size is item_size.
80 * This would create shared memory, basically.
81 * @param pointer to store the address of the scoreboard.
82 * @param name is a key used for debugging and in mod_status output or allow another process to share this space.
83 * @param item_size size of each item
84 * @param item_num number of item to create.
85 * @param pool is pool used to create scoreboard
86 * @return APR_SUCCESS if all went well
88 apr_status_t (* slotmem_create)(ap_slotmem_t **new, const char *name, apr_size_t item_size, int item_num, apr_pool_t *pool);
90 * attach to an existing slotmem.
91 * This would attach to shared memory, basically.
92 * @param pointer to store the address of the scoreboard.
93 * @param name is a key used for debugging and in mod_status output or allow another process to share this space.
94 * @param item_size size of each item
95 * @param item_num max number of item.
96 * @param pool is pool to memory allocate.
97 * @return APR_SUCCESS if all went well
99 apr_status_t (* slotmem_attach)(ap_slotmem_t **new, const char *name, apr_size_t *item_size, int *item_num, apr_pool_t *pool);
101 * get the memory associated with this worker slot.
102 * @param s ap_slotmem_t to use.
103 * @param item_id item to return for 0 to item_num
104 * @param mem address to store the pointer to the slot
105 * @return APR_SUCCESS if all went well
107 apr_status_t (* slotmem_mem)(ap_slotmem_t *s, int item_id, void**mem);
109 * lock the memory segment
110 * NOTE: All slots share the same mutex
111 * @param s ap_slotmem_t to use
112 * @return APR_SUCCESS if all went well
114 apr_status_t (* slotmem_lock)(ap_slotmem_t *s);
116 * unlock the memory segment
117 * NOTE: All slots share the same mutex
118 * @param s ap_slotmem_t to use.
119 * @return APR_SUCCESS if all went well
121 apr_status_t (* slotmem_unlock)(ap_slotmem_t *s);
124 typedef struct ap_slotmem_storage_method ap_slotmem_storage_method;
127 * mod_slotmem externals exposed to the outside world.
128 * Thus the provider nature of mod_slotmem is somewhat insulated
129 * from the end user but can still be used directed if need
130 * be. The rationale is to make it easier for additional
131 * memory providers to be provided and having a single
132 * simple interface for all
135 * obtain the array of provider methods desired
136 * @param pool is the pool to use
137 * @return pointer to array of provider names available
139 AP_DECLARE(apr_array_header_t *) ap_slotmem_methods(apr_pool_t *pool);
141 * obtain the provider method desired
142 * @param provider is name of the provider to use
143 * @return pointer to provider or NULL
145 AP_DECLARE(ap_slotmem_storage_method *) ap_slotmem_method(const char *provider);
147 * call the callback on all worker slots
148 * @param sm ap_slotmem_storage_method provider obtained
149 * @param s ap_slotmem_t to use.
150 * @param funct callback function to call for each element.
151 * @param data parameter for the callback function.
152 * @param pool is pool used to create scoreboard
153 * @return APR_SUCCESS if all went well
155 AP_DECLARE(apr_status_t) ap_slotmem_do(ap_slotmem_storage_method *sm, ap_slotmem_t *s, ap_slotmem_callback_fn_t *func, void *data, apr_pool_t *pool);
158 * create a new slotmem with each item size is item_size.
159 * This would create shared memory, basically.
160 * @param pointer to store the address of the scoreboard.
161 * @param name is a key used for debugging and in mod_status output or allow another process to share this space.
162 * @param item_size size of each item
163 * @param item_num number of item to create.
164 * @param pool is pool used to create scoreboard
165 * @return APR_SUCCESS if all went well
167 AP_DECLARE(apr_status_t) ap_slotmem_create(ap_slotmem_storage_method *sm, ap_slotmem_t **new, const char *name, apr_size_t item_size, int item_num, apr_pool_t *pool);
170 * attach to an existing slotmem.
171 * This would attach to shared memory, basically.
172 * @param pointer to store the address of the scoreboard.
173 * @param name is a key used for debugging and in mod_status output or allow another process to share this space.
174 * @param item_size size of each item
175 * @param item_num max number of item.
176 * @param pool is pool to memory allocate.
177 * @return APR_SUCCESS if all went well
179 AP_DECLARE(apr_status_t) ap_slotmem_attach(ap_slotmem_storage_method *sm, ap_slotmem_t **new, const char *name, apr_size_t *item_size, int *item_num, apr_pool_t *pool);
181 * get the memory associated with this worker slot.
182 * @param s ap_slotmem_t to use.
183 * @param item_id item to return for 0 to item_num
184 * @param mem address to store the pointer to the slot
185 * @return APR_SUCCESS if all went well
187 AP_DECLARE(apr_status_t) ap_slotmem_mem(ap_slotmem_storage_method *sm, ap_slotmem_t *s, int item_id, void**mem);
189 * lock the memory segment
190 * NOTE: All slots share the same mutex
191 * @param s ap_slotmem_t to use
192 * @return APR_SUCCESS if all went well
194 AP_DECLARE(apr_status_t) ap_slotmem_lock(ap_slotmem_storage_method *sm, ap_slotmem_t *s);
196 * unlock the memory segment
197 * NOTE: All slots share the same mutex
198 * @param s ap_slotmem_t to use.
199 * @return APR_SUCCESS if all went well
201 AP_DECLARE(apr_status_t) ap_slotmem_unlock(ap_slotmem_storage_method *sm, ap_slotmem_t *s);