--- 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);