--- a/.hgignore Sat Dec 13 18:55:01 2008 +0200
+++ b/.hgignore Sat Dec 13 19:55:50 2008 +0200
@@ -4,4 +4,4 @@
^obj/
^build/deps/
\.[^/]+.sw[op]$
-^doc/html$
+^doc/(\w+/)?html$
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/doxygen-evsql.conf Sat Dec 13 19:55:50 2008 +0200
@@ -0,0 +1,6 @@
+@INCLUDE = doc/doxygen.conf
+
+PROJECT_NAME = evsql
+INPUT = doc/evsql.dox src/evsql.h
+OUTPUT_DIRECTORY = doc/evsql
+
--- a/doc/doxygen.conf Sat Dec 13 18:55:01 2008 +0200
+++ b/doc/doxygen.conf Sat Dec 13 19:55:50 2008 +0200
@@ -1306,14 +1306,14 @@
# file showing the direct and indirect include dependencies of the file with
# other documented files.
-INCLUDE_GRAPH = YES
+INCLUDE_GRAPH = NO
# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
# documented header file showing the documented files that directly or
# indirectly include this file.
-INCLUDED_BY_GRAPH = YES
+INCLUDED_BY_GRAPH = NO
# If the CALL_GRAPH and HAVE_DOT options are set to YES then
# doxygen will generate a call dependency graph for every global function
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/evsql.dox Sat Dec 13 19:55:50 2008 +0200
@@ -0,0 +1,68 @@
+/**
+@mainpage evsql
+@author Tero Marttila
+
+@section Introduction
+Evsql is a C-language SQL library designed for use with libevent, and primarily PostgreSQL's libpq.
+
+Evsql was born as a result of wanting to use a SQL database from within a libevent application, and discovering
+libpq's asynchronous API. Since the libpq API is somewhat cumbersome to use, I wrote a separate interface that
+drives libpq using libevent and makes writing asynchronous SQL clients a lot easier - plus adding some conveniance
+for parametrized queries and such along the way.
+
+The evsql API doesn't expose the underlying database library's API, although since the only currently existing
+implementation is libpq, this should really be thought of as a generically-named PostgreSQL library rather than a
+database-agnostic API...
+
+@section Usage
+Include the top-level evsql.h header, making sure you also have the evpq and lib modules available.
+
+@section Connecting
+Evsql sessions are represented using an opaque struct, called simply evsql. Use the \ref evsql_ evsql_new_ function corresponding to your
+database engine (PostgreSQL -> evsql_new_pq()) to allocate this handle. It is valid for use immediately, although the
+initial connection may not yet be complete.
+
+There is an evsql_close function, but it is currently not implemented.
+
+\ref evsql_
+
+@section Transactions
+Evsql supports both non-transactional queries and transactional queries. A transaction is allocated its own dedicated
+connection which it can use for its queries without being interfered by other queries/transactions. Evsql takes care of
+sending the initial "BEGIN TRANSACTION" query, and provides evsql_trans_commit()/evsql_trans_abort() functions to send the
+"COMMIT TRANSACTION" and "ROLLBACK TRANSACTION" queries.
+
+Note, however, that transactions can only handle one outstanding query at a time, whereas transactionless queries can
+be enqueued by evsql itself.
+
+\ref evsql_trans_
+
+@section Querying
+There is a single evsql_query function used for both transactional and non-transactional queries; you can pass NULL
+as the trans argument.
+
+The given callback function is invoked once the query has been processed and the result is available, or the query
+failed.
+
+The important distinction between transactional and non-transactional queries is that transactions only support one
+outstanding query at a time, meaning that you must wait for your callback to be invoked before calling evsql_query
+again for the transaction. Non-transactional queries are sent using an idle connection, and will be enqueued for later
+execution if no idle connections are available.
+
+evsql_query returns a handle that can be passed to evsql_query_abort to abort the query, ensuring that the callback
+given to evsql_query is not invoked, and any associated resources released.
+
+@section Parametrized Queries
+Evsql also provides functions to send parametrized queries, the behaviour of evsql_query explained above applies as
+well.
+
+The first of these is evsql_query_params, which takes the parametrized SQL command and a struct containing the
+parameter types and values as arguments.
+
+The second of these is evsql_query_exec, which takes a evsql_query_info struct containing the parametrized SQL command
+and the parameter types, and the parameter values themselves as a list of variable arguments (of the correct type!).
+
+@section API Reference
+The entire API is defined in the top-level evsql.h header.
+
+*/
--- a/src/evsql.h Sat Dec 13 18:55:01 2008 +0200
+++ b/src/evsql.h Sat Dec 13 19:55:50 2008 +0200
@@ -65,6 +65,8 @@
/**
* Various transaction isolation levels for conveniance
+ *
+ * @see evsql_trans
*/
enum evsql_trans_type {
EVSQL_TRANS_DEFAULT,
@@ -147,6 +149,8 @@
/**
* An union to provide storage for the values of small types
+ *
+ * @see evsql_item
*/
union evsql_item_value {
/** 16-bit unsigned integer */
@@ -161,6 +165,10 @@
/**
* A generic structure containing the type and value of a query parameter or a result field.
+ *
+ * @see evsql_query_info
+ * @see evsql_query_params
+ * @see evsql_result_info
*/
struct evsql_item {
/** The "header" containing the type and format */
@@ -195,6 +203,8 @@
* Query meta-info, similar to a prepared statement.
*
* Contains the literal SQL query and the types of the parameters, but no more.
+ *
+ * @see evsql_query_exec
*/
struct evsql_query_info {
/** The SQL query itself */
@@ -208,6 +218,8 @@
/**
* Contains the query parameter types and their actual values
+ *
+ * @see evsql_query_params
*/
struct evsql_query_params {
/** Requested result format for this query. XXX: move elsewhere */
@@ -221,6 +233,8 @@
/**
* Result layout metadata. This contains the stucture needed to decode result rows.
+ *
+ * @see evsql_result_begin
*/
struct evsql_result_info {
/** XXX: make up something useful to stick here */
@@ -234,6 +248,15 @@
/**
* Magic macros for defining param/result info -lists
+ *
+ * @code
+ * static struct evsql_query_params params = EVSQL_PARAMS(EVSQL_FMT_BINARY) {
+ * EVSQL_PARAM( UINT32 ),
+ * ...,
+ *
+ * EVSQL_PARAMS_END
+ * };
+ * @endcode
*
* @name EVSQL_TYPE/PARAM_*
* @{
@@ -242,6 +265,8 @@
/**
* A `struct evsql_item_info` initializer, using FMT_BINARY and the given EVSQL_TYPE_ -suffix.
*
+ * @param typenam the suffix of an evsql_item_type name
+ *
* @see struct evsql_item_info
* @see enum evsql_item_type
*/
@@ -255,18 +280,18 @@
#define EVSQL_TYPE_END { EVSQL_FMT_BINARY, EVSQL_TYPE_INVALID }
/**
- * Initializer block for a `struct evsql_query_params` struct. EVSQL_PARAMS/EVSQL_PARAMS_END should be used as a
- * pseudo-block with the following layout:
- *
- * static struct evsql_query_params params = EVSQL_PARAMS(EVSQL_FMT_BINARY) {
- * EVSQL_PARAM(...),
- * ...,
- *
- * EVSQL_PARAMS_END
- * };
+ * Initializer block for an evsql_query_params struct
*/
#define EVSQL_PARAMS(result_fmt) { result_fmt,
+
+/**
+ * An evsql_item initializer
+ */
#define EVSQL_PARAM(typenam) { EVSQL_TYPE(typenam) }
+
+/**
+ * Include the ending item and terminate the pseudo-block started using #EVSQL_PARAMS
+ */
#define EVSQL_PARAMS_END { EVSQL_TYPE_END } \
} // <<<
@@ -343,6 +368,13 @@
// @}
/**
+ * Session functions
+ *
+ * @name evsql_*
+ * @{
+ */
+
+/**
* 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.
@@ -361,6 +393,18 @@
);
/**
+ * Close a connection. Callbacks for waiting queries will not be run.
+ *
+ * XXX: not implemented yet.
+ *
+ * @ingroup evsql_*
+ * @param evsql the context handle from evsql_new_*
+ */
+void evsql_close (struct evsql *evsql);
+
+// @}
+
+/**
* Query API
*
* @name evsql_query_*
@@ -700,14 +744,4 @@
// @}
-/**
- * Close a connection. Callbacks for waiting queries will not be run.
- *
- * XXX: not implemented yet.
- *
- * @ingroup evsql_*
- * @param evsql the context handle from evsql_new_*
- */
-void evsql_close (struct evsql *evsql);
-
#endif /* EVSQL_H */