evfuse: comparison src/evsql.h

equal deleted inserted replaced

-:c65d0f4c3bff
+:f5037572c326
 #ifndef EVSQL_H
 #define EVSQL_H
 /**
+* @file src/evsql.h
+*
 * A SQL library designed for use with libevent and PostgreSQL's libpq. Provides support for queueing non-transactional
 * requests, transaction support, parametrized queries and result iteration.
 *
 * Currently, the API does not expose the underlying libpq data structures, but since it is currently the only
-* underlying implementation, there is no garuntee that the same API will actually work with other databases' interface
+* underlying implementation, there is no guarantee that the same API will actually work with other databases' interface
 * libraries...
-*/
+*
+* The order of function calls and callbacks goes something like this:
+*
+*  -   evsql_new_pq
+*
+*  -   evsql_trans
+*      -   evsql_trans_abort
+*      -   evsql_trans_error_cb
+*      -   evsql_trans_ready_cb
+*
+*  -   evsql_query, evsql_params_* + evsql_query_params, evsql_query_exec
+*      -   evsql_query_abort
+*      -   evsql_query_cb
+*          -   evsql_result_*
+*          -   evsql_result_free
+*
+*  -   evsql_trans_commit
+*      -   evsql_trans_done_cb
+*
+*/
+/**
+* System includes
+*/
 #include <stdint.h>
 #include <stdbool.h>
 #include <event2/event.h>
 /**
 /**
 * Value for use with EVSQL_TYPE_BINARY, this just a non-NUL-terminated char* and an explicit length
 */
 struct evsql_item_binary {
+/** The binary data */
 const char *ptr;
+/** Number of bytes pointed to by ptr */
 size_t len;
 };
 /**
 * Metadata about the format and type of an item, this does not hold any actual value.
 /**
 * An union to provide storage for the values of small types
 */
 union evsql_item_value {
+/** 16-bit unsigned integer */
 uint16_t uint16;
+/** 32-bit unsigned integer */
 uint32_t uint32;
+/** 64-bit unsigned integer */
 uint64_t uint64;
 };
 /**
 * A generic structure containing the type and value of a query parameter or a result field.
 /**
 * Result layout metadata. This contains the stucture needed to decode result rows.
 */
 struct evsql_result_info {
-// XXX: make up something useful to stick here
+/** XXX: make up something useful to stick here */
 int _unused;
 /**
 * A variable-length array of the item_info column types.
 */
 struct evsql_item_info columns[];
 };
 /**
 * Magic macros for defining param/result info -lists
+*
+* @name EVSQL_TYPE/PARAM_*
+* @{
 */
 /**
 * A `struct evsql_item_info` initializer, using FMT_BINARY and the given EVSQL_TYPE_ -suffix.
 *
 #define EVSQL_PARAMS(result_fmt)            { result_fmt,
 #define EVSQL_PARAM(typenam)                    { EVSQL_TYPE(typenam) }
 #define EVSQL_PARAMS_END                        { EVSQL_TYPE_END } \
 } // <<<
+// @}
+/**
+* Callback definitions
+*
+* @name evsql_*_cb
+*
+* @{
+*/
 /**
 * Callback for handling query results.
 *
 * The query has completed, either succesfully or unsuccesfully.
 *
 * @see evsql_trans
 * @see evsql_trans_commit
 */
 typedef void (*evsql_trans_done_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.
 evsql_error_cb error_fn,
 void *cb_arg
 );
 /**
+* Query API
+*
+* @name evsql_query_*
+* @{
+*/
+/**
+* Queue the given query for execution.
+*
+* If a trans is given (i.e. 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 using an idle connection, or
+* enqueued for later execution.
+*
+* Once the query is complete (got a result, got an error, the connection failed), then the query_cb will be called.
+* The callback can use the evsql_result_* functions to manipulate it.
+*
+* The returned evsql_query handle can be passed to evsql_query_abort at any point before query_fn being called.
+*
+* @param evsql the context handle from evsql_new_*
+* @param trans the optional transaction handle from evsql_trans
+* @param command the raw SQL command itself
+* @param query_fn the query_cb to call once the query is complete
+* @param cb_arg the void* passed to the above
+* @return the evsql_query handle that can be used to abort the query
+*/
+struct evsql_query *evsql_query (struct evsql *evsql, struct evsql_trans *trans, const char *command, evsql_query_cb query_fn, void *cb_arg);
+/**
+* Execute the given SQL query using the list of parameter types/values given via evsql_query_params.
+*
+* Use the EVSQL_PARAMS macros to declare the struct, and the evsql_param_* functions to populate the values.
+*
+* See evsql_query for more info about behaviour.
+*
+* XXX: explain SQL param syntax...
+*
+* @param evsql the context handle from evsql_new_*
+* @param trans the optional transaction handle from evsql_trans
+* @param command the SQL command to bind the parameters to
+* @param params the parameter types and values
+* @param query_fn the query_cb to call once the query is complete
+* @param cb_arg the void* passed to the above
+* @see evsql_query
+*/
+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
+);
+/**
+* Execute the given query_info's SQL query with the values given as variable arguments, using the evsql_query_info to
+* resolve the types.
+*
+* See evsql_query for more info about behaviour.
+*
+* @param evsql the context handle from evsql_new_*
+* @param trans the optional transaction handle from evsql_trans
+* @param query_info the SQL query information
+* @param query_fn the query_cb to call once the query is complete
+* @param cb_arg the void* passed to the above
+* @see evsql_query
+*/
+struct evsql_query *evsql_query_exec (struct evsql *evsql, struct evsql_trans *trans,
+const struct evsql_query_info *query_info,
+evsql_query_cb query_fn, void *cb_arg,
+...
+);
+/**
+* Abort a query returned by evsql_query_* that has not yet completed (query_fn has not been called yet).
+*
+* The actual query itself may or may not be aborted (and hence may or may not be executed on the server), but query_fn
+* will not be called anymore, and the query will dispose of itself and any results returned.
+*
+* If the query is part of a transaction, then trans must be given, and the query must be the query that is currently
+* executing on that trans. The transaction's ready_fn will be called once the query has been aborted and the
+* transaction is now idle again.
+*
+* @param trans if the query is part of a transaction, then it MUST be given here
+* @param query the in-progress query to abort
+*/
+void evsql_query_abort (struct evsql_trans *trans, struct evsql_query *query);
+/**
+* Print out a textual dump of the given query and parameters using DEBUG
+*
+* @param sql the SQL query command
+* @param params the list of parameter types and values
+*/
+void evsql_query_debug (const char *sql, const struct evsql_query_params *params);
+// @}
+/**
+* Transaction API
+*
+* @name evsql_trans_*
+* @{
+*/
+/**
 * Create a new transaction.
 *
 * A transaction will be allocated its own connection, and the "BEGIN TRANSACTION ..." query will be sent (use the
 * trans_type argument to specify this).
 *
 * will NOT be called), and the given trans_error_cb will be called. Note that this includes some, but not all,
 * cases where evsql_query_* returns an error.
 *
 * Once you are done with the transaction, call either evsql_trans_commit or evsql_trans_abort.
 *
+* @ingroup evsql_trans_*
 * @param evsql the context handle from evsql_new_*
 * @param type the type of transaction to create
 * @param error_fn the trans_error_cb to call if this transaction fails
 * @param ready_fn the trans_ready_cb to call once this transaction is ready for use
 * @param done_fn the trans_done_cb to call once this transaction has been commmited
 evsql_trans_done_cb done_fn,
 void *cb_arg
 );
 /**
-* Queue the given query for execution.
-*
-* If a trans is given (i.e. 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 using an idle connection, or
-* enqueued for later execution.
-*
-* Once the query is complete (got a result, got an error, the connection failed), then the query_cb will be called.
-* The callback can use the evsql_result_* functions to manipulate it.
-*
-* The returned evsql_query handle can be passed to evsql_query_abort at any point before query_fn being called.
-*
-* @param evsql the context handle from evsql_new_*
-* @param trans the optional transaction handle from evsql_trans
-* @param command the raw SQL command itself
-* @param query_fn the query_cb to call once the query is complete
-* @param cb_arg the void* passed to the above
-* @return the evsql_query handle that can be used to abort the query
-*/
-struct evsql_query *evsql_query (struct evsql *evsql, struct evsql_trans *trans, const char *command, evsql_query_cb query_fn, void *cb_arg);
-/**
-* Execute the given SQL query using the list of parameter types/values given via evsql_query_params.
-*
-* Use the EVSQL_PARAMS macros to declare the struct, and the evsql_param_* functions to populate the values.
-*
-* See evsql_query for more info about behaviour.
-*
-* XXX: explain SQL param syntax...
-*
-* @param command the SQL command to bind the parameters to
-* @param params the parameter types and values
-* @see evsql_query
-*/
-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
-);
-/**
-* Execute the given query_info's SQL query with the values given as variable arguments, using the evsql_query_info to
-* resolve the types.
-*
-* See evsql_query for more info about behaviour.
-*
-* @param query_info the SQL query information
-* @see evsql_query
-*/
-struct evsql_query *evsql_query_exec (struct evsql *evsql, struct evsql_trans *trans,
-const struct evsql_query_info *query_info,
-evsql_query_cb query_fn, void *cb_arg,
-...
-);
-/**
-* Abort a query returned by evsql_query_* that has not yet completed (query_fn has not been called yet).
-*
-* The actual query itself may or may not be aborted (and hence may or may not be executed on the server), but query_fn
-* will not be called anymore, and the query will dispose of itself and any results returned.
-*
-* If the query is part of a transaction, then trans must be given, and the query must be the query that is currently
-* executing on that trans. The transaction's ready_fn will be called once the query has been aborted and the
-* transaction is now idle again.
-*
-* @param trans if the query is part of a transaction, then it MUST be given here
-* @param query the in-progress query to abort
-*/
-void evsql_query_abort (struct evsql_trans *trans, struct evsql_query *query);
-/**
 * Commit a transaction using "COMMIT TRANSACTION".
 *
 * The transaction must be idle, just like for evsql_query. Once the transaction has been commited, the transaction's
 * done_fn will be called, after which the transaction must not be used anymore.
 *
 * @param trans the transaction from evsql_trans to abort
 * @see evsql_trans
 */
 void evsql_trans_abort (struct evsql_trans *trans);
-// @{
-/**
-* Transaction-handling functions
-*/
 /**
 * Retrieve the transaction-specific error message from the underlying engine.
 *
 * Intended to be called from trans_error_cb
 */
 const char *evsql_trans_error (struct evsql_trans *trans);
 // @}
-// @{
 /**
 * Parameter-building functions.
 *
 * These manipulate the value of the given parameter index.
+*
+* @name evsql_param_*
+* @{
 */
 int evsql_param_binary (struct evsql_query_params *params, size_t param, const char *ptr, size_t len);
 int evsql_param_string (struct evsql_query_params *params, size_t param, const char *ptr);
 int evsql_param_uint16 (struct evsql_query_params *params, size_t param, uint16_t uval);
 int evsql_param_uint32 (struct evsql_query_params *params, size_t param, uint32_t uval);
 int evsql_param_null   (struct evsql_query_params *params, size_t param);
 int evsql_params_clear (struct evsql_query_params *params);
 // @}
-// @{
-/**
-* Query-handling functions
-*/
-/**
-* Print out a textual dump of the given query and parameters using DEBUG
-*/
-void evsql_query_debug (const char *sql, const struct evsql_query_params *params);
-// @}
-// @{
 /**
 * Result-handling functions
+*
+* @name evsql_result_*
+* @{
 */
 /**
 * Check the result for errors. Intended for use with non-data queries, i.e. CREATE, etc.
 *
 * @param nullok when true and the field value is NULL, *ptr and *size are not modified, otherwise NULL means an error
 * @return zero on success, <0 on error
 */
 int evsql_result_string (const struct evsql_result *res, size_t row, size_t col, const char **ptr, int nullok);
-// @{
 /**
 * Use evsql_result_binary to read a binary field value, and then convert it using ntoh[slq], storing the value in
 * *val.
 *
 * The given row/col must be within bounds as returned by evsql_result_rows/cols.
 *
 * @param res the result handle passed to query_cb
 * @param row the row index to access
 * @param col the column index to access
-* @param val where to store the decoded value
+* @param uval where to store the decoded value
 * @param nullok when true and the field value is NULL, *ptr and *size are not modified, otherwise NULL means an error
 * @return zero on success, <0 on error
 */
 int evsql_result_uint16 (const struct evsql_result *res, size_t row, size_t col, uint16_t *uval, int nullok);
 int evsql_result_uint32 (const struct evsql_result *res, size_t row, size_t col, uint32_t *uval, int nullok);
 int evsql_result_uint64 (const struct evsql_result *res, size_t row, size_t col, uint64_t *uval, int nullok);
+/**
+* Every result handle passed to query_cb MUST be released by the user, using this function.
+*
+* @param res the result handle passed to query_cb
+*/
+void evsql_result_free (struct evsql_result *res);
 // @}
 /**
-* Every result handle passed to query_cb MUST be released by the user, using this function.
-*
-* @param res the result handle passed to query_cb
-*/
-void evsql_result_free (struct evsql_result *res);
-// @}
-/**
 * 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 */

branch	new-evsql
changeset 52	f5037572c326
parent 51	c65d0f4c3bff
child 53	0d6e07f4c9a1