granicus.if.org Git - apache/blob - 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  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
  49 extern "C" {
  50 #endif
  51
  52 #define AP_SLOTMEM_PROVIDER_GROUP "slotmem"
  53 #define AP_SLOTMEM_PROVIDER_VERSION "0"
  54
  55 typedef 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
  75 typedef 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  */
  84 typedef apr_status_t ap_slotmem_callback_fn_t(void* mem, void *data, apr_pool_t *pool);
  85
  86 struct 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
 192 typedef struct ap_slotmem_provider_t ap_slotmem_provider_t;
 193
 194 #ifdef __cplusplus
 195 }
 196 #endif
 197
 198 #endif
 199 /** @} */