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"
45 #include <unistd.h> /* for getpid() */
52 #define AP_SLOTMEM_PROVIDER_GROUP "slotmem"
53 #define AP_SLOTMEM_PROVIDER_VERSION "0"
55 typedef unsigned int ap_slotmem_type_t;
58 * Values for ap_slotmem_type_t::
60 * AP_SLOTMEM_TYPE_PERSIST: For transitory providers, persist
61 * the data on the file-system
63 * AP_SLOTMEM_TYPE_NOTMPSAFE:
65 * AP_SLOTMEM_TYPE_PREALLOC: Access to slots require they be grabbed 1st
67 * AP_SLOTMEM_TYPE_CLEARINUSE: If persisting, clear 'inuse' array before
70 #define AP_SLOTMEM_TYPE_PERSIST (1 << 0)
71 #define AP_SLOTMEM_TYPE_NOTMPSAFE (1 << 1)
72 #define AP_SLOTMEM_TYPE_PREGRAB (1 << 2)
73 #define AP_SLOTMEM_TYPE_CLEARINUSE (1 << 3)
75 typedef struct ap_slotmem_instance_t ap_slotmem_instance_t;
78 * callback function used for slotmem doall.
79 * @param mem is the memory associated with a worker.
80 * @param data is what is passed to slotmem.
81 * @param pool is pool used
82 * @return APR_SUCCESS if all went well
84 typedef apr_status_t ap_slotmem_callback_fn_t(void* mem, void *data, apr_pool_t *pool);
86 struct ap_slotmem_provider_t {
88 * Name of the provider method
92 * call the callback on all worker slots
93 * @param s ap_slotmem_instance_t to use.
94 * @param funct callback function to call for each element.
95 * @param data parameter for the callback function.
96 * @param pool is pool used
97 * @return APR_SUCCESS if all went well
99 apr_status_t (* doall)(ap_slotmem_instance_t *s, ap_slotmem_callback_fn_t *func, void *data, apr_pool_t *pool);
101 * create a new slotmem with each item size is item_size.
102 * This would create shared memory, basically.
103 * @param inst where to store pointer to slotmem
104 * @param name a key used for debugging and in mod_status output or allow another process to share this space.
105 * @param item_size size of each item
106 * @param item_num number of item to create.
107 * @param type type of slotmem.
108 * @param pool is pool used
109 * @return APR_SUCCESS if all went well
111 apr_status_t (* create)(ap_slotmem_instance_t **inst, const char *name, apr_size_t item_size, unsigned int item_num, ap_slotmem_type_t type, apr_pool_t *pool);
113 * attach to an existing slotmem.
114 * This would attach to shared memory, basically.
115 * @param inst where to store pointer to slotmem
116 * @param name a key used for debugging and in mod_status output or allow another process to share this space.
117 * @param item_size size of each item
118 * @param item_num max number of item.
119 * @param pool is pool to memory allocate.
120 * @return APR_SUCCESS if all went well
122 apr_status_t (* attach)(ap_slotmem_instance_t **inst, const char *name, apr_size_t *item_size, unsigned int *item_num, apr_pool_t *pool);
124 * get the memory ptr associated with this worker slot.
125 * @param s ap_slotmem_instance_t to use.
126 * @param item_id item to return for 0 to item_num
127 * @param mem address to store the pointer to the slot
128 * @return APR_SUCCESS if all went well
130 apr_status_t (* dptr)(ap_slotmem_instance_t *s, unsigned int item_id, void**mem);
132 * get/read the data associated with this worker slot.
133 * @param s ap_slotmem_instance_t to use.
134 * @param item_id item to return for 0 to item_num
135 * @param dest address to store the data
136 * @param dest_len length of dataset to retrieve
137 * @return APR_SUCCESS if all went well
139 apr_status_t (* get)(ap_slotmem_instance_t *s, unsigned int item_id, unsigned char *dest, apr_size_t dest_len);
141 * put/write the data associated with this worker slot.
142 * @param s ap_slotmem_instance_t to use.
143 * @param item_id item to return for 0 to item_num
144 * @param src address of the data to store in the slot
145 * @param src_len length of dataset to store in the slot
146 * @return APR_SUCCESS if all went well
148 apr_status_t (* put)(ap_slotmem_instance_t *slot, unsigned int item_id, unsigned char *src, apr_size_t src_len);
150 * return number of slots allocated for this entry.
151 * @param s ap_slotmem_instance_t to use.
152 * @return number of slots
154 unsigned int (* num_slots)(ap_slotmem_instance_t *s);
156 * return number of free (not used) slots allocated for this entry.
157 * Valid for slots which are AP_SLOTMEM_TYPE_PREGRAB as well as
158 * any which use get/release.
159 * @param s ap_slotmem_instance_t to use.
160 * @return number of slots
162 unsigned int (* num_free_slots)(ap_slotmem_instance_t *s);
164 * return slot size allocated for this entry.
165 * @param s ap_slotmem_instance_t to use.
166 * @return size of slot
168 apr_size_t (* slot_size)(ap_slotmem_instance_t *s);
170 * grab (or alloc) a free slot
171 * @param s ap_slotmem_instance_t to use.
172 * @param item_id ptr to the available slot id and marked as in-use
173 * @return APR_SUCCESS if all went well
175 apr_status_t (* grab)(ap_slotmem_instance_t *s, unsigned int *item_id);
177 * release (or free) the slot associated with this item_id
178 * @param s ap_slotmem_instance_t to use.
179 * @param item_id slot id to free and mark as no longer in-use
180 * @return APR_SUCCESS if all went well
182 apr_status_t (* release)(ap_slotmem_instance_t *s, unsigned int item_id);
184 * forced grab (or alloc) a slot associated with this item_id
185 * @param s ap_slotmem_instance_t to use.
186 * @param item_id to the specified slot id and marked as in-use
187 * @return APR_SUCCESS if all went well
189 apr_status_t (* fgrab)(ap_slotmem_instance_t *s, unsigned int item_id);
192 typedef struct ap_slotmem_provider_t ap_slotmem_provider_t;