ap_slotmem.h revision 714a36287cb6cc92748d7e87bbe549d660acae1c
842ae4bd224140319ae7feec1872b93dfd491143fielding/* Licensed to the Apache Software Foundation (ASF) under one or more
842ae4bd224140319ae7feec1872b93dfd491143fielding * contributor license agreements. See the NOTICE file distributed with
842ae4bd224140319ae7feec1872b93dfd491143fielding * this work for additional information regarding copyright ownership.
842ae4bd224140319ae7feec1872b93dfd491143fielding * The ASF licenses this file to You under the Apache License, Version 2.0
842ae4bd224140319ae7feec1872b93dfd491143fielding * (the "License"); you may not use this file except in compliance with
842ae4bd224140319ae7feec1872b93dfd491143fielding * the License. You may obtain a copy of the License at
04891cf70e0bfc38bfb027541dc821f04c754ff7nd * Unless required by applicable law or agreed to in writing, software
04891cf70e0bfc38bfb027541dc821f04c754ff7nd * distributed under the License is distributed on an "AS IS" BASIS,
04891cf70e0bfc38bfb027541dc821f04c754ff7nd * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
04891cf70e0bfc38bfb027541dc821f04c754ff7nd * See the License for the specific language governing permissions and
04891cf70e0bfc38bfb027541dc821f04c754ff7nd * limitations under the License.
3568de757bac0b47256647504c186d17ca272f85rbb/* Memory handler for a shared memory divided in slot.
3568de757bac0b47256647504c186d17ca272f85rbb * @brief Memory Slot Extension Storage Module for Apache
3568de757bac0b47256647504c186d17ca272f85rbb * @defgroup MEM mem
3568de757bac0b47256647504c186d17ca272f85rbb * @ingroup APACHE_MODS
3568de757bac0b47256647504c186d17ca272f85rbbextern "C" {
3568de757bac0b47256647504c186d17ca272f85rbbtypedef unsigned int ap_slotmem_type_t;
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Values for ap_slotmem_type_t::
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * AP_SLOTMEM_TYPE_PERSIST: For transitory providers, persist
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * the data on the file-system
cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick * AP_SLOTMEM_TYPE_NOTMPSAFE:
3568de757bac0b47256647504c186d17ca272f85rbb * AP_SLOTMEM_TYPE_PREALLOC: Access to slots require they be grabbed 1st
db12cd62083041bf90945eeb90cc40fbd2340797trawicktypedef struct ap_slotmem_instance_t ap_slotmem_instance_t;
9f979f5c8061f6f6f560d1824e0e378ff5b91931rpluem * callback function used for slotmem.
3568de757bac0b47256647504c186d17ca272f85rbb * @param mem is the memory associated with a worker.
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @param data is what is passed to slotmem.
3568de757bac0b47256647504c186d17ca272f85rbb * @param pool is pool used
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @return APR_SUCCESS if all went well
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantztypedef apr_status_t ap_slotmem_callback_fn_t(void* mem, void *data, apr_pool_t *pool);
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * Name of the provider method
8f3ec4772d2aeb347cf40e87c77627bb784dd018rbb const char *name;
3d96ee83babeec32482c9082c9426340cee8c44dwrowe * call the callback on all worker slots
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param s ap_slotmem_instance_t to use.
49aa87d735a13ae3d04012ee0df91ddb51f7c36esf * @param funct callback function to call for each element.
49aa87d735a13ae3d04012ee0df91ddb51f7c36esf * @param data parameter for the callback function.
cd8f8c995d415473f3bfb0b329b2450f2a722c3atrawick * @param pool is pool used
98fb535f829e2a95aabd82420931f476661fa8e3jorton * @return APR_SUCCESS if all went well
f0e395a55abfcad3d2bd7c63470003b08a93d567nd apr_status_t (* doall)(ap_slotmem_instance_t *s, ap_slotmem_callback_fn_t *func, void *data, apr_pool_t *pool);
f0e395a55abfcad3d2bd7c63470003b08a93d567nd * create a new slotmem with each item size is item_size.
98fb535f829e2a95aabd82420931f476661fa8e3jorton * This would create shared memory, basically.
7cd5419264796cfeaf8215383cf0f89130a81fectrawick * @param name is a key used for debugging and in mod_status output or allow another process to share this space.
7cd5419264796cfeaf8215383cf0f89130a81fectrawick * @param item_size size of each item
7cd5419264796cfeaf8215383cf0f89130a81fectrawick * @param item_num number of item to create.
7cd5419264796cfeaf8215383cf0f89130a81fectrawick * @param type type of slotmem.
7cd5419264796cfeaf8215383cf0f89130a81fectrawick * @param pool is pool used
7cd5419264796cfeaf8215383cf0f89130a81fectrawick * @return APR_SUCCESS if all went well
7cd5419264796cfeaf8215383cf0f89130a81fectrawick apr_status_t (* create)(ap_slotmem_instance_t **new, const char *name, apr_size_t item_size, unsigned int item_num, ap_slotmem_type_t type, apr_pool_t *pool);
41634f717c623556a16b27b25d7d909a66fe20f8wrowe * attach to an existing slotmem.
3568de757bac0b47256647504c186d17ca272f85rbb * This would attach to shared memory, basically.
3568de757bac0b47256647504c186d17ca272f85rbb * @param name is a key used for debugging and in mod_status output or allow another process to share this space.
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @param item_size size of each item
3568de757bac0b47256647504c186d17ca272f85rbb * @param item_num max number of item.
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @param pool is pool to memory allocate.
3568de757bac0b47256647504c186d17ca272f85rbb * @return APR_SUCCESS if all went well
3568de757bac0b47256647504c186d17ca272f85rbb apr_status_t (* attach)(ap_slotmem_instance_t **new, const char *name, apr_size_t *item_size, unsigned int *item_num, apr_pool_t *pool);
3568de757bac0b47256647504c186d17ca272f85rbb * get the memory ptr associated with this worker slot.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param s ap_slotmem_instance_t to use.
41634f717c623556a16b27b25d7d909a66fe20f8wrowe * @param item_id item to return for 0 to item_num
3568de757bac0b47256647504c186d17ca272f85rbb * @param mem address to store the pointer to the slot
3568de757bac0b47256647504c186d17ca272f85rbb * @return APR_SUCCESS if all went well
3568de757bac0b47256647504c186d17ca272f85rbb apr_status_t (* dptr)(ap_slotmem_instance_t *s, unsigned int item_id, void**mem);
3568de757bac0b47256647504c186d17ca272f85rbb * get/read the data associated with this worker slot.
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @param s ap_slotmem_instance_t to use.
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param item_id item to return for 0 to item_num
0f081398cf0eef8cc7c66a535d450110a92dc8aefielding * @param dest address to store the data
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @param dest_len length of dataset to retrieve
3568de757bac0b47256647504c186d17ca272f85rbb * @return APR_SUCCESS if all went well
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz apr_status_t (* get)(ap_slotmem_instance_t *s, unsigned int item_id, unsigned char *dest, apr_size_t dest_len);
3568de757bac0b47256647504c186d17ca272f85rbb * put/write the data associated with this worker slot.
24b534291150023e6b68eca89ddd33e475ccddc0wrowe * @param s ap_slotmem_instance_t to use.
3568de757bac0b47256647504c186d17ca272f85rbb * @param item_id item to return for 0 to item_num
24b534291150023e6b68eca89ddd33e475ccddc0wrowe * @param src address of the data to store in the slot
24b534291150023e6b68eca89ddd33e475ccddc0wrowe * @param src_len length of dataset to store in the slot
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @return APR_SUCCESS if all went well
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz apr_status_t (* put)(ap_slotmem_instance_t *slot, unsigned int item_id, unsigned char *src, apr_size_t src_len);
3568de757bac0b47256647504c186d17ca272f85rbb * return number of slots allocated for this entry.
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @param s ap_slotmem_instance_t to use.
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @return number of slots
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz unsigned int (* num_slots)(ap_slotmem_instance_t *s);
3568de757bac0b47256647504c186d17ca272f85rbb * return number of free (not used) slots allocated for this entry.
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * Valid for slots which are AP_SLOTMEM_TYPE_PREGRAB as well as
3568de757bac0b47256647504c186d17ca272f85rbb * any which use get/release.
3568de757bac0b47256647504c186d17ca272f85rbb * @param s ap_slotmem_instance_t to use.
3568de757bac0b47256647504c186d17ca272f85rbb * @return number of slots
3568de757bac0b47256647504c186d17ca272f85rbb unsigned int (* num_free_slots)(ap_slotmem_instance_t *s);
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * return slot size allocated for this entry.
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @param s ap_slotmem_instance_t to use.
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz * @return size of slot
3568de757bac0b47256647504c186d17ca272f85rbb * grab (or alloc) a free slot
3568de757bac0b47256647504c186d17ca272f85rbb * @param s ap_slotmem_instance_t to use.
3568de757bac0b47256647504c186d17ca272f85rbb * @param item_id ptr to the available slot id and marked as in-use
3568de757bac0b47256647504c186d17ca272f85rbb * @return APR_SUCCESS if all went well
28c170ac8e99644de58cad454c6e0f9b4b359be6jerenkrantz apr_status_t (* grab)(ap_slotmem_instance_t *s, unsigned int *item_id);
3568de757bac0b47256647504c186d17ca272f85rbb * release (or free) the slot associated with this item_id
3568de757bac0b47256647504c186d17ca272f85rbb * @param s ap_slotmem_instance_t to use.
3568de757bac0b47256647504c186d17ca272f85rbb * @param item_id slot id to free and mark as no longer in-use
3568de757bac0b47256647504c186d17ca272f85rbb * @return APR_SUCCESS if all went well
3568de757bac0b47256647504c186d17ca272f85rbb apr_status_t (* release)(ap_slotmem_instance_t *s, unsigned int item_id);