diff -r 82cfdb6680d1 -r 99a41f48e29b src/evsql.h
--- a/src/evsql.h	Sun Oct 12 14:57:06 2008 +0300
+++ b/src/evsql.h	Sun Oct 12 20:10:47 2008 +0300
@@ -20,6 +20,22 @@
 struct evsql_query;
 
 /*
+ * Transaction handle
+ */
+struct evsql_trans;
+
+/*
+ * Transaction type
+ */
+enum evsql_trans_type {
+    EVSQL_TRANS_DEFAULT,
+    EVSQL_TRANS_SERIALIZABLE,
+    EVSQL_TRANS_REPEATABLE_READ,
+    EVSQL_TRANS_READ_COMMITTED,
+    EVSQL_TRANS_READ_UNCOMMITTED,
+};
+
+/*
  * Parameter type
  */
 enum evsql_param_format {
@@ -77,48 +93,79 @@
 /*
  * Result type
  */
-union evsql_result {
-    // libpq
-    PGresult *pq;
-};
-
 struct evsql_result_info {
     struct evsql *evsql;
+    struct evsql_trans *trans;
     
     int error;
 
-    union evsql_result result;
+    union evsql_result {
+        // libpq
+        PGresult *pq;
+    } result;
 };
 
 /*
- * Callback for handling query-level errors.
+ * Callback for handling query results.
  *
- * The query has completed, either succesfully or unsuccesfully (look at info.error).
- * info.result contains the result à la the evsql's type.
+ * The query has completed, either succesfully or unsuccesfully (nonzero .error).
+ *
+ * Use the evsql_result_* functions to manipulate the results.
  */
 typedef void (*evsql_query_cb)(const struct evsql_result_info *res, void *arg);
 
 /*
- * Callback for handling connection-level errors.
+ * Callback for handling global-level errors.
  *
- * The SQL context/connection suffered an error. It is not valid anymore, and may not be used.
+ * The evsql is not useable anymore.
+ *
+ * XXX: this is not actually called yet, no retry logic implemented.
  */
 typedef void (*evsql_error_cb)(struct evsql *evsql, void *arg);
 
 /*
+ * Callback for handling transaction-level errors.
+ *
+ * The transaction is not useable anymore.
+ */
+typedef void (*evsql_trans_error_cb)(struct evsql_trans *trans, void *arg);
+
+/*
+ * The transaction is ready for use.
+ */
+typedef void (*evsql_trans_ready_cb)(struct evsql_trans *trans, void *arg);
+
+/*
  * Create a new PostgreSQL/libpq(evpq) -based evsql using the given conninfo.
+ *
+ * The given conninfo must stay valid for the duration of the evsql's lifetime.
  */
 struct evsql *evsql_new_pq (struct event_base *ev_base, const char *pq_conninfo, evsql_error_cb error_fn, void *cb_arg);
 
 /*
- * Queue the given query for execution.
+ * Create a new transaction.
+ *
+ * Transactions are separate connections that provide transaction-isolation.
+ *
+ * Once the transaction is ready for use, ready_fn will be called. If the transaction fails, any pending query will be forgotten, and error_fn called.
  */
-struct evsql_query *evsql_query (struct evsql *evsql, const char *command, evsql_query_cb query_fn, void *cb_arg);
+struct evsql_trans *evsql_trans (struct evsql *evsql, enum evsql_trans_type type, evsql_trans_error_cb error_fn, evsql_trans_ready_cb ready_fn, void *cb_arg);
 
 /*
- * Same, but uses the SQL-level support for binding parameters.
+ * Queue the given query for execution.
+ *
+ * If trans is specified (not NULL), then the transaction must be idle, and the query will be executed in that
+ * transaction's context. Otherwise, the query will be executed without a transaction, andmay be executed immediately,
+ * or if other similar queries are running, it will be queued for later execution.
+ *
+ * Once the query is complete (got a result, got an error, the connection failed), then the query_cb will be triggered.
  */
-struct evsql_query *evsql_query_params (struct evsql *evsql, const char *command, const struct evsql_query_params *params, evsql_query_cb query_fn, void *cb_arg);
+struct evsql_query *evsql_query (struct evsql *evsql, struct evsql_trans *trans, const char *command, evsql_query_cb query_fn, void *cb_arg);
+
+/*
+ * Same as evsql_query, but uses the SQL-level support for binding parameters.
+ */
+struct evsql_query *evsql_query_params (struct evsql *evsql, struct evsql_trans *trans, const char *command, const struct evsql_query_params *params, evsql_query_cb query_fn, void *cb_arg);
 
 /*
  * Param-building functions