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