include/ap_slotmem.h

   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  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
  43 #ifdef AP_NEED_SET_MUTEX_PERMS
  44 #include "unixd.h"
  45 #endif
  46
  47 #if APR_HAVE_UNISTD_H
  48 #include <unistd.h>         /* for getpid() */
  49 #endif
  50
  51 #define AP_SLOTMEM_STORAGE "slotmem"
  52
  53 typedef struct ap_slotmem_t ap_slotmem_t;
  54
  55 /**
  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
  60  * @return APR_SUCCESS if all went well
  61  */
  62 typedef apr_status_t ap_slotmem_callback_fn_t(void* mem, void *data, apr_pool_t *pool);
  63
  64 struct ap_slotmem_storage_method {
  65     /*
  66      * Name of the provider method
  67      */
  68     const char *name;
  69     /**
  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
  75      * @return APR_SUCCESS if all went well
  76      */
  77     apr_status_t (* slotmem_do)(ap_slotmem_t *s, ap_slotmem_callback_fn_t *func, void *data, apr_pool_t *pool);
  78     /**
  79      * create a new slotmem with each item size is item_size.
  80      * This would create shared memory, basically.
  81      * @param name is a key used for debugging and in mod_status output or allow another process to share this space.
  82      * @param item_size size of each item
  83      * @param item_num number of item to create.
  84      * @param pool is pool used
  85      * @return APR_SUCCESS if all went well
  86      */
  87     apr_status_t (* slotmem_create)(ap_slotmem_t **new, const char *name, apr_size_t item_size, unsigned int item_num, apr_pool_t *pool);
  88     /**
  89      * attach to an existing slotmem.
  90      * This would attach to  shared memory, basically.
  91      * @param name is a key used for debugging and in mod_status output or allow another process to share this space.
  92      * @param item_size size of each item
  93      * @param item_num max number of item.
  94      * @param pool is pool to memory allocate.
  95      * @return APR_SUCCESS if all went well
  96      */
  97     apr_status_t (* slotmem_attach)(ap_slotmem_t **new, const char *name, apr_size_t *item_size, unsigned int *item_num, apr_pool_t *pool);
  98     /**
  99      * get the memory ptr associated with this worker slot.
 100      * @param s ap_slotmem_t to use.
 101      * @param item_id item to return for 0 to item_num
 102      * @param mem address to store the pointer to the slot
 103      * @return APR_SUCCESS if all went well
 104      */
 105     apr_status_t (* slotmem_mem)(ap_slotmem_t *s, unsigned int item_id, void**mem);
 106     /**
 107      * lock the memory segment
 108      * NOTE: All slots share the same mutex
 109      * @param s ap_slotmem_t to use
 110      * @return APR_SUCCESS if all went well
 111      */
 112     apr_status_t (* slotmem_lock)(ap_slotmem_t *s);
 113     /**
 114      * unlock the memory segment
 115      * NOTE: All slots share the same mutex
 116      * @param s ap_slotmem_t to use.
 117      * @return APR_SUCCESS if all went well
 118      */
 119     apr_status_t (* slotmem_unlock)(ap_slotmem_t *s);
 120     /**
 121      * retrieve the memory associated with this worker slot.
 122      * @param s ap_slotmem_t to use.
 123      * @param item_id item to return for 0 to item_num
 124      * @param dest address to store the data
 125      * @param dest_len length of dataset to retrieve
 126      * @return APR_SUCCESS if all went well
 127      */
 128     apr_status_t (* slotmem_get)(ap_slotmem_t *s, unsigned int item_id, unsigned char *dest, apr_size_t dest_len);
 129     /**
 130      * store the memory associated with this worker slot.
 131      * @param s ap_slotmem_t to use.
 132      * @param item_id item to return for 0 to item_num
 133      * @param src address of the data to store in the slot
 134      * @param src_len length of dataset to store in the slot
 135      * @return APR_SUCCESS if all went well
 136      */
 137     apr_status_t (* slotmem_put)(ap_slotmem_t *slot, unsigned int item_id, unsigned char *src, apr_size_t src_len);
 138 };
 139
 140 typedef struct ap_slotmem_storage_method ap_slotmem_storage_method;
 141
 142 /*
 143  * mod_slotmem externals exposed to the outside world.
 144  *  Thus the provider nature of mod_slotmem is somewhat insulated
 145  *  from the end user but can still be used directed if need
 146  *  be. The rationale is to make it easier for additional
 147  *  memory providers to be provided and having a single
 148  *  simple interface for all
 149  */
 150 /**
 151  * obtain the array of provider methods desired
 152  * @param pool is the pool to use
 153  * @return pointer to array of provider names available
 154  */
 155 AP_DECLARE(apr_array_header_t *) ap_slotmem_methods(apr_pool_t *pool);
 156 /**
 157  * obtain the provider method desired
 158  * @param provider is name of the provider to use
 159  * @return pointer to provider or NULL
 160  */
 161 AP_DECLARE(ap_slotmem_storage_method *) ap_slotmem_method(const char *provider);
 162 /**
 163  * call the callback on all worker slots
 164  * @param sm ap_slotmem_storage_method provider obtained
 165  * @param s ap_slotmem_t to use.
 166  * @param funct callback function to call for each element.
 167  * @param data parameter for the callback function.
 168  * @param pool is pool used
 169  * @return APR_SUCCESS if all went well
 170  */
 171 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);
 172
 173 /**
 174  * create a new slotmem with each item size is item_size.
 175  * This would create shared memory, basically.
 176  * @param sm ap_slotmem_storage_method provider obtained
 177  * @param name is a key used for debugging and in mod_status output or allow another process to share this space.
 178  * @param item_size size of each item
 179  * @param item_num number of item to create.
 180  * @param pool is pool used
 181  * @return APR_SUCCESS if all went well
 182  */
 183 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, unsigned int item_num, apr_pool_t *pool);
 184
 185 /**
 186  * attach to an existing slotmem.
 187  * This would attach to  shared memory, basically.
 188  * @param sm ap_slotmem_storage_method provider obtained
 189  * @param name is a key used for debugging and in mod_status output or allow another process to share this space.
 190  * @param item_size size of each item
 191  * @param item_num max number of item.
 192  * @param pool is pool to memory allocate.
 193  * @return APR_SUCCESS if all went well
 194  */
 195 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, unsigned int *item_num, apr_pool_t *pool);
 196 /**
 197  * get the memory associated with this worker slot.
 198  * @param sm ap_slotmem_storage_method provider obtained
 199  * @param s ap_slotmem_t to use.
 200  * @param item_id item to return for 0 to item_num
 201  * @param mem address to store the pointer to the slot
 202  * @return APR_SUCCESS if all went well
 203  */
 204 AP_DECLARE(apr_status_t) ap_slotmem_mem(ap_slotmem_storage_method *sm, ap_slotmem_t *s, unsigned int item_id, void**mem);
 205 /**
 206  * lock the memory segment
 207  * NOTE: All slots share the same mutex
 208  * @param sm ap_slotmem_storage_method provider obtained
 209  * @param s ap_slotmem_t to use
 210  * @return APR_SUCCESS if all went well
 211  */
 212 AP_DECLARE(apr_status_t) ap_slotmem_lock(ap_slotmem_storage_method *sm, ap_slotmem_t *s);
 213 /**
 214  * unlock the memory segment
 215  * NOTE: All slots share the same mutex
 216  * @param sm ap_slotmem_storage_method provider obtained
 217  * @param s ap_slotmem_t to use.
 218  * @return APR_SUCCESS if all went well
 219  */
 220 AP_DECLARE(apr_status_t) ap_slotmem_unlock(ap_slotmem_storage_method *sm, ap_slotmem_t *s);
 221 /**
 222  * retrieve the memory associated with this worker slot.
 223  * @param sm ap_slotmem_storage_method provider obtained
 224  * @param s ap_slotmem_t to use.
 225  * @param item_id item to return for 0 to item_num
 226  * @param dest address to store the data
 227  * @param dest_len length of dataset to retrieve
 228  * @return APR_SUCCESS if all went well
 229  */
 230 AP_DECLARE(apr_status_t) ap_slotmem_get(ap_slotmem_storage_method *sm, ap_slotmem_t *s, unsigned int item_id, unsigned char *dest, apr_size_t dest_len);
 231 /**
 232  * store the memory associated with this worker slot.
 233  * @param sm ap_slotmem_storage_method provider obtained
 234  * @param s ap_slotmem_t to use.
 235  * @param item_id item to return for 0 to item_num
 236  * @param src address of the data to store in the slot
 237  * @param src_len length of dataset to store in the slot
 238  * @return APR_SUCCESS if all went well
 239  */
 240 AP_DECLARE(apr_status_t) ap_slotmem_put(ap_slotmem_storage_method *sm, ap_slotmem_t *s, unsigned int item_id, unsigned char *src, apr_size_t src_len);
 241
 242 #endif /*SLOTMEM_H*/