joes 2003/01/21 12:59:41
Modified: src apreq_cookie.c apreq_env.h apreq_tables.c
apreq_tables.h
Log:
Minor tweaks. Clean up table API docs.
Revision Changes Path
1.3 +8 -5 httpd-apreq-2/src/apreq_cookie.c
Index: apreq_cookie.c
===================================================================
RCS file: /home/cvs/httpd-apreq-2/src/apreq_cookie.c,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- apreq_cookie.c 21 Jan 2003 15:22:23 -0000 1.2
+++ apreq_cookie.c 21 Jan 2003 20:59:41 -0000 1.3
@@ -250,7 +250,8 @@
/* use the environment's cookie data */
/* fetch ctx->jar (cached jar) */
- if ( apreq_env_jar(ctx, &j) == APR_SUCCESS && j != NULL )
+ j = apreq_env_jar(ctx, NULL);
+ if ( j != NULL )
return j;
data = apreq_env_cookie(ctx);
@@ -259,7 +260,7 @@
/* XXX: potential race condition here
between env_jar fetch and env_jar set. */
- apreq_env_jar(ctx,&j); /* set (cache) ctx->jar */
+ apreq_env_jar(ctx,j); /* set (cache) ctx->jar */
if (data == NULL)
return j;
@@ -336,8 +337,6 @@
return j;
}
-#define ADD_ATTR(name) do { strcpy(f,c->name ? "; " #name "=%s" : \
- "%.0s"); f+= strlen(f); } while (0)
APREQ_DECLARE(int) apreq_cookie_serialize(const apreq_cookie_t *c,
char *buf, apr_size_t len)
@@ -356,6 +355,9 @@
if (c->v.name == NULL)
return -1;
+#define ADD_ATTR(name) do { strcpy(f,c->name ? "; " #name "=%s" : \
+ "%.0s"); f+= strlen(f); } while (0)
+
if (c->version == NETSCAPE) {
ADD_ATTR(path);
@@ -380,6 +382,8 @@
ADD_ATTR(comment);
ADD_ATTR(commentURL);
+#undef ADD_ATTR
+
/* "%.0s" very hackish, but it should be safe. max_age is
* the last va_arg, and we're not actually printing it in
* the "%.0s" case. Should check the apr_snprintf implementation
@@ -398,7 +402,6 @@
c->comment, c->commentURL, c->time.max_age);
}
-#undef ADD_ATTR
APREQ_DECLARE(const char*) apreq_cookie_as_string(const apreq_cookie_t *c,
apr_pool_t *p)
1.2 +6 -16 httpd-apreq-2/src/apreq_env.h
Index: apreq_env.h
===================================================================
RCS file: /home/cvs/httpd-apreq-2/src/apreq_env.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- apreq_env.h 21 Jan 2003 02:36:28 -0000 1.1
+++ apreq_env.h 21 Jan 2003 20:59:41 -0000 1.2
@@ -1,32 +1,24 @@
#ifndef APREQ_ENV_H
#define APREQ_ENV_H
-#include "apreq_cookie.h"
-
-/*
-#include "apreq_request.h"
-*/
-
#ifdef __cplusplus
extern "C" {
#endif
-/* XXX: Per-process initialization */
+/* ctx ~ request_rec */
struct apreq_request_env {
int foo;
-/*
- apr_status_t (*init)(void *ctx, apreq_parser_cfg_t *cfg);
- apreq_request_t *(*make)(void *ctx);
- apr_status_t (*parse)(apreq_request_t *req);
-*/
+ apr_status_t (*init)(void *ctx, void *cfg);
+ void *(*make)(void *ctx);
+ apr_status_t (*parse)(void *ctx);
};
struct apreq_cookie_env {
const char *(*in)(void *ctx);
const char *(*in2)(void *ctx);
- apr_status_t (*jar)(void *ctx, apreq_jar_t **j);
+ void *(*jar)(void *ctx, void *j);
apr_status_t (*out)(void *ctx, const char *c);
apr_status_t (*out2)(void *ctx, const char *c);
};
@@ -47,13 +39,11 @@
APREQ_DECLARE(void) apreq_log(const char *file, int line, int level,
apr_status_t status, void *ctx, const char
*fmt, ...);
-APREQ_DECLARE(apr_status_t) apreq_env_jar(void *ctx, apreq_jar_t **j);
+APREQ_DECLARE(void *) apreq_env_jar(void *ctx, void *j);
APREQ_DECLARE(const char *) apreq_env_cookie(void *ctx);
APREQ_DECLARE(const char *) apreq_env_cookie2(void *ctx);
APREQ_DECLARE(apr_status_t) apreq_env_set_cookie(void *ctx, const char *s);
APREQ_DECLARE(apr_status_t) apreq_env_set_cookie2(void *ctx, const char *s);
-APREQ_DECLARE(apr_status_t) apreq_env_cookie_jar(void *ctx,
- apreq_jar_t **j);
#define apreq_env_pool(r) APREQ_ENV.pool(r)
#define apreq_env_cookie(r) APREQ_ENV.c.in(r)
1.4 +6 -8 httpd-apreq-2/src/apreq_tables.c
Index: apreq_tables.c
===================================================================
RCS file: /home/cvs/httpd-apreq-2/src/apreq_tables.c,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- apreq_tables.c 21 Jan 2003 02:34:32 -0000 1.3
+++ apreq_tables.c 21 Jan 2003 20:59:41 -0000 1.4
@@ -628,26 +628,24 @@
return t->a.nelts - t->ghosts;
}
-APREQ_DECLARE(int) apreq_is_empty_table(const apreq_table_t *t)
-{
- return t->a.nelts > t->ghosts;
-}
-
-
APREQ_DECLARE(apreq_value_copy_t *)apreq_table_copier(apreq_table_t *t,
apreq_value_copy_t *c)
{
+ apreq_value_copy_t *original = t->copy;
+
if (c != NULL)
t->copy = c;
- return t->copy;
+ return original;
}
APREQ_DECLARE(apreq_value_merge_t *)apreq_table_merger(apreq_table_t *t,
apreq_value_merge_t
*m)
{
+ apreq_value_merge_t *original = t->merge;
+
if (m != NULL)
t->merge = m;
- return t->merge;
+ return original;
}
1.3 +190 -44 httpd-apreq-2/src/apreq_tables.h
Index: apreq_tables.h
===================================================================
RCS file: /home/cvs/httpd-apreq-2/src/apreq_tables.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- apreq_tables.h 20 Jan 2003 01:54:43 -0000 1.2
+++ apreq_tables.h 21 Jan 2003 20:59:41 -0000 1.3
@@ -66,23 +66,30 @@
extern "C" {
#endif /* __cplusplus */
-/*
- * Define the structures used by the APR general-purpose library.
- */
-
/**
* @file apreq_tables.h
- * @brief APR Table library
+ * @brief APREQ Table library
*/
/**
* @defgroup APREQ_Table Table routines
* @ingroup APREQ
*
- * Memory allocation stuff, like pools, arrays, and tables. Pools
- * and tables are opaque structures to applications, but arrays are
- * published.
+ * Basic ADT for managing collections in APREQ. Tables
+ * remember the order in which entries are added, and respect
+ * this order whenever iterator APIs are used.
+ *
+ * APREQ Tables have a hash-like lookup API as well, and support
+ * multivalued keys. Table keys are C strings, but the return values
+ * are guaranteed to point at the "data" attribute of an apreq_value_t.
+ * (The table key for an apreq_value_t is its "name".) Thus tables can
+ * be used to do lookups on binary/opaque data stored within an
+ * apreq_value_t.
+ *
+ * Tables also provide an abstract API for merging and copying the
+ * values it contains.
* @{
*/
+
/** the table abstract data type */
typedef struct apreq_table_t apreq_table_t;
@@ -91,7 +98,6 @@
* @param p The pool to allocate the pool out of
* @param nelts The number of elements in the initial table.
* @return The new table.
- * @warning This table can only store text data
*/
APREQ_DECLARE(apreq_table_t *) apreq_table_make(apr_pool_t *p, int nelts);
@@ -105,84 +111,176 @@
const apreq_table_t *t);
+/**
+ * Create an APR Table from an APREQ Table.
+ * @param p The pool to allocate the APR table from
+ * @param t The APREQ table to copy
+ */
APREQ_DECLARE(apr_table_t *)apreq_table_export(const apreq_table_t *t,
apr_pool_t *p);
+/**
+ * Create an APREQ Table from an APR Table.
+ * @param p The pool to allocate the APREQ table from
+ * @param t The APR table to copy
+ * @param f Flags for the APREQ table to use during construction.
+ */
APREQ_DECLARE(apreq_table_t *)apreq_table_import(apr_pool_t *p,
- const apr_table_t *s,
+ const apr_table_t *t,
const unsigned f);
-
/**
* Delete all of the elements from a table
* @param t The table to clear
*/
APREQ_DECLARE(void) apreq_table_clear(apreq_table_t *t);
+/**
+ * Return the number of elements within the table.
+ * @param t The table to clear
+ */
APREQ_DECLARE(int) apreq_table_nelts(const apreq_table_t *t);
-APREQ_DECLARE(int) apreq_is_empty_table(const apreq_table_t *t);
+#define apreq_table_is_empty(t) ( apreq_table_nelts(t) == 0 )
+
+/**
+ * Get/set method for the table's value copier.
+ * @param t Table.
+ * @param c The new t->copy callback. c = NULL is ignored;
+ * a non-NULL value replaces the table's internal copier.
+ * @return The original t->copy callback (prior to any assignment).
+ */
APREQ_DECLARE(apreq_value_copy_t *) apreq_table_copier(apreq_table_t *t,
apreq_value_copy_t *c);
-APREQ_DECLARE(apreq_value_merge_t *) apreq_table_merger(apreq_table_t *t,
- apreq_value_merge_t *m);
-APREQ_DECLARE(void) apreq_table_cache_lookups(apreq_table_t *t,
- const int on);
+/**
+ * Get/set method for the table's value merger.
+ * @param t Table.
+ * @param m The new t->merge callback. m = NULL is ignored;
+ * a non-NULL value replaces the table's internal merger.
+ * @return The original t->merge callback (prior to any assignment).
+ */
+
+APREQ_DECLARE(apreq_value_merge_t *) apreq_table_merger(apreq_table_t *t,
+ apreq_value_merge_t *m);
+/**
+ * Change the behavior of the table's internal search trees.
+ * @param t Table.
+ * @param on Activate/deactivate additional balancing algorithms.
+ * @remark By default, APREQ Tables use binary search trees to
+ * improve lookup performance. This function can instruct
+ * the table to maintain balance within those trees.
+ * In typical ( < 100 table entries ) situations, the
+ * additional overhead needed for maintaining tree-balance
+ * will cause performance to worsen, not improve.
+ *
+ * Handle with care.
+ */
APREQ_DECLARE(void) apreq_table_balance(apreq_table_t *t, const int on);
+
+/**
+ * Attempt to merge multivalued entries together, eliminating
+ * redunandant entries with t->merge. See apreq_table_merger
+ * for additional details.
+ *
+ * @param t Table.
+ */
APREQ_DECLARE(apr_status_t) apreq_table_normalize(apreq_table_t *t);
+/**
+ * Count the number of dead entries within the table.
+ * Mainly used for diagnostic purposes, since ghost entries are
+ * ignored by the table's accessor APIs.
+ *
+ * @param t Table.
+ */
APREQ_DECLARE(int) apreq_table_ghosts(apreq_table_t *t);
+
+/**
+ * Remove dead entries from the table. This can
+ * be a very expensive and somewhat useless function
+ * as far as the table API goes. It's voodoo, so
+ * try not to use it.
+ *
+ * @param t Table.
+ */
APREQ_DECLARE(int) apreq_table_exorcise(apreq_table_t *t);
/**
- * Get the value associated with a given key from the table. After this
call,
- * The data is still in the table
+ * Get the value associated with a given key from the table.
* @param t The table to search for the key
* @param key The key to search for
- * @return The value associated with the key
+ * @return The data associated with the key, guaranteed to
+ * point at the "data" attribute of an apreq_value_t struct.
+ *
*/
APREQ_DECLARE(const char*) apreq_table_get(const apreq_table_t *t,
const char *key);
+/**
+ * Get the value associated with a given key from the table,
+ * and cache the entry at the root of the tree it was found in.
+ * @param t The table to search for the key
+ * @param key The key to search for
+ * @return The data associated with the key, guaranteed to
+ * point at the "data" attribute of an apreq_value_t struct.
+ *
+ * @remark Caching is incompatible with tree-balance, so this
+ * function may deactivate the tree-balancing algorithm if
+ * necessary.
+ */
APREQ_DECLARE(const char *) apreq_table_get_cached(apreq_table_t *t,
const char *key);
-
+/**
+ * Return the (unique) keys in a (char *) array, preserving their
+ * original order.
+ * @param t Table.
+ * @param p Pool used to allocate the resulting array struct.
+ */
APREQ_DECLARE(apr_array_header_t *) apreq_table_keys(const apreq_table_t *t,
apr_pool_t *p);
+/**
+ * Return the (unique) values in an (apreq_value_t *) array,
+ * preserving their original order.
+ * @param t Table.
+ * @param p Pool used to allocate the resulting array struct.
+ * @remark For multivalued keys, the first apreq_value_t is
+ * returned.
+ */
APREQ_DECLARE(apr_array_header_t *) apreq_table_values(const apreq_table_t
*t,
apr_pool_t *p,
const char *key);
/**
- * Add a key/value pair to a table, if another element already exists with
the
- * same key, this will over-write the old data.
+ * Add an apreq_value_t to the table. If another value already exists
+ * with the same name, this will replace the old value.
* @param t The table to add the data to.
- * @param key The key fo use
* @param val The value to add
- * @remark When adding data, this function makes a copy of both the key and
the
- * value.
+ * @remark When adding data, this function uses the value's name as key.
+ * Nothing is copied.
*/
APREQ_DECLARE(void) apreq_table_set(apreq_table_t *t, const apreq_value_t
*v);
/**
- * Remove data from the table
- * @param t The table to remove data from
- * @param key The key of the data being removed
+ * Remove a key from the table.
+ * @param t Table.
+ * @param key The name of the apreq_values to remove.
+ * @remark The table will drops ALL values associated with the key.
*/
APREQ_DECLARE(void) apreq_table_unset(apreq_table_t *t, const char *key);
/**
- * Add data to a table by merging the value with data that has already been
- * stored
+ * Add data to a table by merging the value with previous ones.
* @param t The table to search for the data
- * @param key The key to merge data for
+ * @param key The key for locating previous values to merge with this one.
* @param val The data to add
- * @remark If the key is not found, then this function acts like
apr_table_add
+ * @remark If the key is not found, then this function acts like
apr_table_add.
+ * If multiple entries are found, they are all merged into a single value
+ * via t->merge.
*/
APREQ_DECLARE(void) apreq_table_merge(apreq_table_t *t,
@@ -192,10 +290,8 @@
* Add data to a table, regardless of whether there is another element with
the
* same key.
* @param t The table to add to
- * @param key The key to use
* @param val The value to add.
- * @remark When adding data, this function makes a copy of both the key and
the
- * value.
+ * @remark This function does not make copies.
*/
APREQ_DECLARE(void) apreq_table_add(apreq_table_t *t, const apreq_value_t
*v);
@@ -204,16 +300,24 @@
* @param p The pool to use for the new table
* @param over The first table to put in the new table
* @param under The table to add at the end of the new table
- * @return A new table containing all of the data from the two passed in
+ * @return A new table containing all of the data from the two passed in.
*/
-
APREQ_DECLARE(apreq_table_t *) apreq_table_overlay(apr_pool_t *p,
const apreq_table_t *over,
const apreq_table_t
*under);
-
+/**
+ * Append one table to the end of another.
+ * @param t The table to be modified.
+ * @param s The values from this table are added to "t".
+ * @remark This function splices the internal binary trees from "s"
+ * into "t", so it will be faster than iterating s with apreq_table_add.
+ * From a user's perspective, the result should be identical.
+ */
APREQ_DECLARE(void) apreq_table_cat(apreq_table_t *t, const apreq_table_t
*s);
/**
+ * XXX: This doc needs to be modified for APREQ. Volunteers?
+
* For each element in table b, either use setn or mergen to add the data
* to table a. Which method is used is determined by the flags passed in.
* @param a The table to add the data to.
@@ -256,19 +360,61 @@
/** Iterator API */
+/**
+ * Fetch a table entry using a specific index.
+ * @param t Table.
+ * @param val Location of resulting value.
+ * @param off Index of desired value. Upon success, off will be updated
+ * to reflect the actual offset of the value sought. Any
+ * difference reflects the presence of earlier ghosts in
+ * the table.
+ */
APREQ_DECLARE(apr_status_t) apreq_table_fetch(const apreq_table_t *t,
const apreq_value_t **val,
int *off);
+/**
+ * Locate the first value in the table.
+ * @param t Table.
+ * @param val Location of resulting value.
+ * @param off Index of first value. The offset will count
+ * the number of ghosts before the first value.
+ */
APREQ_DECLARE(apr_status_t) apreq_table_first(const apreq_table_t *t,
const apreq_value_t **val,
int *off);
+
+/**
+ * Locate the next value in the table.
+ * @param t Table.
+ * @param val Location of resulting value.
+ * @param off (Internal) Index of next value. On success, the offset
+ * will be 1 + the number of ghosts between the current offset
+ * and the new one.
+ */
APREQ_DECLARE(apr_status_t) apreq_table_next(const apreq_table_t *t,
const apreq_value_t **val,
int *off);
+/**
+ * Locate the last value in the table.
+ * @param t Table.
+ * @param val Location of the final value.
+ * @param off (Internal) Index of last value. The offset will be one
+ * less than the number of entries (including ghosts)
+ * occupying the table.
+ */
APREQ_DECLARE(apr_status_t) apreq_table_last(const apreq_table_t *t,
const apreq_value_t **val,
int *off);
+
+/**
+ * Locate the previous value in the table.
+ * @param t Table.
+ * @param val Location of previous value.
+ * @param off (Internal) Index of previous value. On success, the
+ * offset will be 1 + the number of ghosts between the
+ * current offset and the new one.
+ */
APREQ_DECLARE(apr_status_t) apreq_table_prev(const apreq_table_t *t,
const apreq_value_t **val,
int *off);
@@ -278,7 +424,7 @@
* and apr_table_vdo().
* @param rec The data passed as the first argument to apr_table_[v]do()
* @param key The key from this iteration of the table
- * @param key The value from this iteration of the table
+ * @param val The v->data from this iteration of the table
* @remark Iteration continues while this callback function returns non-zero.
* To export the callback function for apr_table_[v]do() it must be declared
* in the _NONSTD convention.
@@ -300,10 +446,10 @@
* are run.
* @return FALSE if one of the comp() iterations returned zero; TRUE if all
* iterations returned non-zero
- * @see apr_table_do_callback_fn_t
+ * @see apreq_table_do_callback_fn_t
*/
APREQ_DECLARE(int) apreq_table_do(apreq_table_do_callback_fn_t *comp,
- void *rec,
+ void *ctx,
const apreq_table_t *t, ...);
/**
@@ -320,11 +466,11 @@
* whose key matches are run.
* @return FALSE if one of the comp() iterations returned zero; TRUE if all
* iterations returned non-zero
- * @see apr_table_do_callback_fn_t
+ * @see apreq_table_do_callback_fn_t
*/
APREQ_DECLARE(int) apreq_table_vdo(apreq_table_do_callback_fn_t *comp,
- void *rec,
- const apreq_table_t *t, va_list);
+ void *ctx,
+ const apreq_table_t *t, va_list);
/** @} */
