svn commit: r646415 - /httpd/httpd/trunk/modules/cache/ap_socache.h

[jo...@apache.org]

Author: jorton
Date: Wed Apr  9 09:13:02 2008
New Revision: 646415

URL: http://svn.apache.org/viewvc?rev=646415&view=rev
Log:
* modules/cache/ap_socache.h: Doxify.

Modified:
    httpd/httpd/trunk/modules/cache/ap_socache.h

Modified: httpd/httpd/trunk/modules/cache/ap_socache.h
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/modules/cache/ap_socache.h?rev=646415&r1=646414&r2=646415&view=diff
==============================================================================
--- httpd/httpd/trunk/modules/cache/ap_socache.h (original)
+++ httpd/httpd/trunk/modules/cache/ap_socache.h Wed Apr  9 09:13:02 2008
@@ -30,80 +30,129 @@
 #include "ap_provider.h"
 #include "apr_pools.h"
 
-/* If this flag is set, the store/retrieve/delete/status interfaces of
- * the provider are NOT safe to be called concurrently from multiple
- * processes or threads, and an external global mutex must be used to
- * serialize access to the provider. */
+/** If this flag is set, the store/retrieve/delete/status interfaces
+ * of the provider are NOT safe to be called concurrently from
+ * multiple processes or threads, and an external global mutex must be
+ * used to serialize access to the provider. */
 #define AP_SOCACHE_FLAG_NOTMPSAFE (0x0001)
 
-/* A cache instance. */
+/** A cache instance. */
 typedef struct ap_socache_instance_t ap_socache_instance_t;
 
-/* Hints which may be passed to the init function; providers may
+/** Hints which may be passed to the init function; providers may
  * ignore some or all of these hints. */
 struct ap_socache_hints {
-    /* Approximate average length of IDs: */
+    /** Approximate average length of IDs: */
     apr_size_t avg_id_len;
-    /* Approximate average size of objects: */
+    /** Approximate average size of objects: */
     apr_size_t avg_obj_size;
-    /* Interval (in seconds) after which an expiry run is
+    /** Interval (in seconds) after which an expiry run is
      * necessary. */
     time_t expiry_interval;
 };
 
+/** A socache provider structure.  socache providers are registered
+ * with the ap_provider.h interface using the AP_SOCACHE_PROVIDER_*
+ * constants. */
 typedef struct ap_socache_provider_t {
-    /* Canonical provider name: */
+    /** Canonical provider name: */
     const char *name;
 
-    /* Bitmask of AP_SOCACHE_FLAG_* flags: */
+    /** Bitmask of AP_SOCACHE_FLAG_* flags: */
     unsigned int flags;
 
-    /* Create a session cache based on the given configuration string
-     * ARG.  Returns NULL on success, or an error string on failure.
-     * Pool TMP should be used for any temporary allocations, pool P
-     * should be used for any allocations lasting as long as the
-     * lifetime of the return context.
+    /** 
+     * Create a session cache based on the given configuration string.
+     * The instance pointer returned in the instance paramater will be
+     * passed as the first argument to subsequent invocations.
      *
-     * The context pointer returned in *INSTANCE will be passed as the
-     * first argument to subsequent invocations. */
+     * @param instance Output parameter to which instance object is written.
+     * @param arg Used-specified configuration string
+     * @param tmp Pool to be used for any temporary allocations
+     * @param p Pool to be use for any allocations lasting as long as 
+     * the created instance
+     * @return NULL on success, or an error string on failure.
+     */
     const char *(*create)(ap_socache_instance_t **instance, const char *arg, 
                           apr_pool_t *tmp, apr_pool_t *p);
+
     /* Initialize the cache.  NAMESPACE must given a unique string
      * prefix for use with memcached; if hints is non-NULL, it gives a
-     * set of hints for the provider.  Return APR error code.  */
+     * set of hints for the provider.  Return APR error code. 
+
+     * @param instance The cache instance
+     * @param namespace A unique string identifying the consumer of this API
+     * @param hints Optional hints argument describing expected cache use
+     * @param s Server structure to which the cache is associated
+     * @param pool Pool for long-lived allocations
+     * @return APR status value indicating success.
+     */
     apr_status_t (*init)(ap_socache_instance_t *instance, const char *namespace, 
                          const struct ap_socache_hints *hints,
                          server_rec *s, apr_pool_t *pool);
-    /* Destroy a given cache context. */    
+
+    /** 
+     * Destroy a given cache instance object.
+     * @param instance The cache instance to destroy.
+     * @param s Associated server structure (for logging purposes)
+     */
     void (*destroy)(ap_socache_instance_t *instance, server_rec *s);
-    /* Store an object in the cache with key ID of length IDLEN, with
-     * DATA of length DATALEN.  The object expires at abolute time
-     * EXPIRY.  */
+
+    /** 
+     * Store an object in a cache instance.
+     * @param instance The cache instance
+     * @param s Associated server structure (for logging purposes)
+     * @param id Unique ID for the object; binary blob
+     * @param idlen Length of id blob
+     * @param expiry Absolute time at which the object expires
+     * @param data Data to store; binary blob
+     * @param datalen Length of data blob
+     */
     apr_status_t (*store)(ap_socache_instance_t *instance, server_rec *s, 
                           const unsigned char *id, unsigned int idlen, 
                           time_t expiry, 
                           unsigned char *data, unsigned int datalen);
-    /* Retrieve cached object with key ID of length IDLEN, returning
-     * TRUE on success or FALSE otherwise.  If TRUE, the data must be
-     * placed in DEST, which has length on entry of *DESTLEN.
-     * *DESTLEN must be updated to equal the length of data written on
-     * exit. */
+
+    /**
+     * Retrieve a cached object.
+     * @param instance The cache instance
+     * @param s Associated server structure (for logging purposes)
+     * @param id Unique ID for the object; binary blob
+     * @param idlen Length of id blob
+     * @param data Output buffer to place retrievd data (binary blob)
+     * @param datalen On entry, length of data buffer; on exit, the
+     * number of bytes written to the data buffer.
+     * @param pool Pool for temporary allocations.
+     */
     apr_status_t (*retrieve)(ap_socache_instance_t *instance, server_rec *s,
                              const unsigned char *id, unsigned int idlen,
                              unsigned char *data, unsigned int *datalen,
                              apr_pool_t *pool);
-    /* Remove an object from the cache with key ID of length IDLEN.
-     * POOL may be used for temporary allocations. */
+
+    /* Remove an object from the cache
+     * @param instance The cache instance
+     * @param s Associated server structure (for logging purposes)
+     * @param id Unique ID for the object; binary blob
+     * @param idlen Length of id blob
+     * @param pool Pool for temporary allocations.
+     */
     void (*delete)(ap_socache_instance_t *instance, server_rec *s,
                    const unsigned char *id, unsigned int idlen,
                    apr_pool_t *pool);
-    /* Dump cache status for mod_status output. */
+
+    /** Dump the status of a cache instance for mod_status.  Will use
+     * the ap_r* interfaces to produce appropriate status output.
+     *
+     * @param instance The cache instance
+     * @param r The request structure
+     * @param flags The AP_STATUS_* constants used (see mod_status.h)
+     */
     void (*status)(ap_socache_instance_t *instance, request_rec *r, int flags);
 } ap_socache_provider_t;
 
-/* Cache providers are registered using the ap_provider_* interface,
- * with the following group and version:  */
+/** The provider group used to register socache providers. */
 #define AP_SOCACHE_PROVIDER_GROUP "socache"
+/** The provider version used to register socache providers. */
 #define AP_SOCACHE_PROVIDER_VERSION "0"
 
 #endif /* AP_SOCACHE_H */