# HG changeset patch
# User Tero Marttila <terom@fixme.fi>
# Date 1219876948 -10800
# Node ID 10d514029c64bce8e2f1479bbeeff499e6ea9a61
# Parent  03a7e064f833f1290602cb83b31d7a1208adc7fd
documentation tweaks, add req_abort function prototype

diff -r 03a7e064f833 -r 10d514029c64 memcache.h
--- a/memcache.h	Thu Aug 28 01:34:14 2008 +0300
+++ b/memcache.h	Thu Aug 28 01:42:28 2008 +0300
@@ -9,16 +9,20 @@
 
 /*
  * Used to store the global information for a memcache context. A context contains both servers and active connections.
+ *
+ * Each context has one callback function defined, which is used for all requests.
  */
 struct memcache;
 
 /*
  * A transaction.
+ *
+ * Each request has one callback argument defined, which is used for that request's callbacks.
  */
 struct memcache_req;
 
 /*
- * Keys used
+ * Object keys
  */
 struct memcache_key {
     /*
@@ -220,6 +224,9 @@
     MEMCACHE_RPL_MAX,
 };
 
+/*
+ * Request states
+ */
 enum memcache_req_state {
     MEMCACHE_STATE_INVALID,
     
@@ -270,23 +277,32 @@
 };
 
 /*
- * Callback used
+ * Callback used.
+ *
+ * This is called whenever the request's state changes, including when new data is received in the STATE_REPLY_DATA
+ * state.
  */
 typedef int (*memcache_cb) (struct memcache_req *, void*);
 
 /*
  * Allocate a new memcache context for use with other methods.
+ *
+ * The given callback function is used for all requests in this context.
  */
 struct memcache *memcache_alloc (memcache_cb cb_fn);
 
 /*
  * Add a server to the pool of available servers.
+ *
+ * At most <max_connections> connections will be kept open to this server, and additional requests will be queued.
  */
 int memcache_add_server (struct memcache *mc, struct config_endpoint *endpoint, int max_connections);
 
 /*
  * Attempt to fetch a key from the cache.
  *
+ * The given callback argument will be used when invoking the context's callback for this request.
+ *
  * The state machine will work as follows:
  *
  *  req_state                  multi   req_reply
@@ -312,6 +328,8 @@
  *
  * The given memcache_key is copied, including the char array pointed to by buf.
  * Both obj and buf are also copied, but buf.data will not be copied - the pointer must remain valid until the request is done.
+ * 
+ * The given callback argument will be used when invoking the context's callback for this request.
  *
  * The state machine will work as follows:
  *
@@ -372,6 +390,15 @@
 const struct memcache_buf *memcache_req_buf (struct memcache_req *req);
 
 /*
+ * Abort a running request, regardless of what state it is in.
+ *
+ * You do not need to call req_free after this.
+ *
+ * XXX: unimplemented
+ */
+void memcache_req_abort (struct memcache_req *req);
+
+/*
  * Free a req that is in the STATE_DONE, STATE_DATA_DONE or STATE_ERROR state.
  */
 void memcache_req_free (struct memcache_req *req);