# HG changeset patch # User Tero Marttila # Date 1229190950 -7200 # Node ID 0d6e07f4c9a14012bccfeaf652d1bceae5330eca # Parent f5037572c326f95cd0f961f6b6754753de74b6d9 separate evsql documentation diff -r f5037572c326 -r 0d6e07f4c9a1 .hgignore --- 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$ diff -r f5037572c326 -r 0d6e07f4c9a1 doc/doxygen-evsql.conf --- /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 + diff -r f5037572c326 -r 0d6e07f4c9a1 doc/doxygen.conf --- 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 diff -r f5037572c326 -r 0d6e07f4c9a1 doc/evsql.dox --- /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. + +*/ diff -r f5037572c326 -r 0d6e07f4c9a1 src/evsql.h --- 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 */