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 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 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. 15 */ 16 17#ifndef SLOTMEM_H 18#define SLOTMEM_H 19 20/* Memory handler for a shared memory divided in slot. 21 */ 22/** 23 * @file ap_slotmem.h 24 * @brief Memory Slot Extension Storage Module for Apache 25 * 26 * @defgroup MEM mem 27 * @ingroup APACHE_MODS 28 * @{ 29 */ 30 31#include "httpd.h" 32#include "http_config.h" 33#include "http_log.h" 34#include "ap_provider.h" 35 36#include "apr.h" 37#include "apr_strings.h" 38#include "apr_pools.h" 39#include "apr_shm.h" 40#include "apr_global_mutex.h" 41#include "apr_file_io.h" 42#include "apr_md5.h" 43 44#if APR_HAVE_UNISTD_H 45#include <unistd.h> /* for getpid() */ 46#endif 47 48#ifdef __cplusplus 49extern "C" { 50#endif 51 52#define AP_SLOTMEM_PROVIDER_GROUP "slotmem" 53#define AP_SLOTMEM_PROVIDER_VERSION "0" 54 55typedef unsigned int ap_slotmem_type_t; 56 57/* 58 * Values for ap_slotmem_type_t:: 59 * 60 * AP_SLOTMEM_TYPE_PERSIST: For transitory providers, persist 61 * the data on the file-system 62 * 63 * AP_SLOTMEM_TYPE_NOTMPSAFE: 64 * 65 * AP_SLOTMEM_TYPE_PREALLOC: Access to slots require they be grabbed 1st 66 * 67 * AP_SLOTMEM_TYPE_CLEARINUSE: If persisting, clear 'inuse' array before 68 * storing 69 */ 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) 74 75typedef struct ap_slotmem_instance_t ap_slotmem_instance_t; 76 77/** 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 83 */ 84typedef apr_status_t ap_slotmem_callback_fn_t(void* mem, void *data, apr_pool_t *pool); 85 86struct ap_slotmem_provider_t { 87 /* 88 * Name of the provider method 89 */ 90 const char *name; 91 /** 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 98 */ 99 apr_status_t (* doall)(ap_slotmem_instance_t *s, ap_slotmem_callback_fn_t *func, void *data, apr_pool_t *pool); 100 /** 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 110 */ 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); 112 /** 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 121 */ 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); 123 /** 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 129 */ 130 apr_status_t (* dptr)(ap_slotmem_instance_t *s, unsigned int item_id, void**mem); 131 /** 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 138 */ 139 apr_status_t (* get)(ap_slotmem_instance_t *s, unsigned int item_id, unsigned char *dest, apr_size_t dest_len); 140 /** 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 147 */ 148 apr_status_t (* put)(ap_slotmem_instance_t *slot, unsigned int item_id, unsigned char *src, apr_size_t src_len); 149 /** 150 * return number of slots allocated for this entry. 151 * @param s ap_slotmem_instance_t to use. 152 * @return number of slots 153 */ 154 unsigned int (* num_slots)(ap_slotmem_instance_t *s); 155 /** 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 161 */ 162 unsigned int (* num_free_slots)(ap_slotmem_instance_t *s); 163 /** 164 * return slot size allocated for this entry. 165 * @param s ap_slotmem_instance_t to use. 166 * @return size of slot 167 */ 168 apr_size_t (* slot_size)(ap_slotmem_instance_t *s); 169 /** 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 174 */ 175 apr_status_t (* grab)(ap_slotmem_instance_t *s, unsigned int *item_id); 176 /** 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 181 */ 182 apr_status_t (* release)(ap_slotmem_instance_t *s, unsigned int item_id); 183 /** 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 188 */ 189 apr_status_t (* fgrab)(ap_slotmem_instance_t *s, unsigned int item_id); 190}; 191 192typedef struct ap_slotmem_provider_t ap_slotmem_provider_t; 193 194#ifdef __cplusplus 195} 196#endif 197 198#endif 199/** @} */ 200