75 } // <<< |
91 } // <<< |
76 |
92 |
77 /* |
93 /* |
78 * Result type |
94 * Result type |
79 */ |
95 */ |
80 union evsql_result { |
|
81 // libpq |
|
82 PGresult *pq; |
|
83 }; |
|
84 |
|
85 struct evsql_result_info { |
96 struct evsql_result_info { |
86 struct evsql *evsql; |
97 struct evsql *evsql; |
|
98 struct evsql_trans *trans; |
87 |
99 |
88 int error; |
100 int error; |
89 |
101 |
90 union evsql_result result; |
102 union evsql_result { |
91 }; |
103 // libpq |
92 |
104 PGresult *pq; |
93 /* |
105 } result; |
94 * Callback for handling query-level errors. |
106 }; |
95 * |
107 |
96 * The query has completed, either succesfully or unsuccesfully (look at info.error). |
108 /* |
97 * info.result contains the result à la the evsql's type. |
109 * Callback for handling query results. |
|
110 * |
|
111 * The query has completed, either succesfully or unsuccesfully (nonzero .error). |
|
112 * |
|
113 * Use the evsql_result_* functions to manipulate the results. |
98 */ |
114 */ |
99 typedef void (*evsql_query_cb)(const struct evsql_result_info *res, void *arg); |
115 typedef void (*evsql_query_cb)(const struct evsql_result_info *res, void *arg); |
100 |
116 |
101 /* |
117 /* |
102 * Callback for handling connection-level errors. |
118 * Callback for handling global-level errors. |
103 * |
119 * |
104 * The SQL context/connection suffered an error. It is not valid anymore, and may not be used. |
120 * The evsql is not useable anymore. |
|
121 * |
|
122 * XXX: this is not actually called yet, no retry logic implemented. |
105 */ |
123 */ |
106 typedef void (*evsql_error_cb)(struct evsql *evsql, void *arg); |
124 typedef void (*evsql_error_cb)(struct evsql *evsql, void *arg); |
107 |
125 |
108 /* |
126 /* |
|
127 * Callback for handling transaction-level errors. |
|
128 * |
|
129 * The transaction is not useable anymore. |
|
130 */ |
|
131 typedef void (*evsql_trans_error_cb)(struct evsql_trans *trans, void *arg); |
|
132 |
|
133 /* |
|
134 * The transaction is ready for use. |
|
135 */ |
|
136 typedef void (*evsql_trans_ready_cb)(struct evsql_trans *trans, void *arg); |
|
137 |
|
138 /* |
109 * Create a new PostgreSQL/libpq(evpq) -based evsql using the given conninfo. |
139 * Create a new PostgreSQL/libpq(evpq) -based evsql using the given conninfo. |
|
140 * |
|
141 * The given conninfo must stay valid for the duration of the evsql's lifetime. |
110 */ |
142 */ |
111 struct evsql *evsql_new_pq (struct event_base *ev_base, const char *pq_conninfo, evsql_error_cb error_fn, void *cb_arg); |
143 struct evsql *evsql_new_pq (struct event_base *ev_base, const char *pq_conninfo, evsql_error_cb error_fn, void *cb_arg); |
112 |
144 |
113 /* |
145 /* |
|
146 * Create a new transaction. |
|
147 * |
|
148 * Transactions are separate connections that provide transaction-isolation. |
|
149 * |
|
150 * 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. |
|
151 */ |
|
152 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); |
|
153 |
|
154 /* |
114 * Queue the given query for execution. |
155 * Queue the given query for execution. |
115 */ |
156 * |
116 struct evsql_query *evsql_query (struct evsql *evsql, const char *command, evsql_query_cb query_fn, void *cb_arg); |
157 * If trans is specified (not NULL), then the transaction must be idle, and the query will be executed in that |
117 |
158 * transaction's context. Otherwise, the query will be executed without a transaction, andmay be executed immediately, |
118 /* |
159 * or if other similar queries are running, it will be queued for later execution. |
119 * Same, but uses the SQL-level support for binding parameters. |
160 * |
120 */ |
161 * Once the query is complete (got a result, got an error, the connection failed), then the query_cb will be triggered. |
121 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); |
162 */ |
|
163 struct evsql_query *evsql_query (struct evsql *evsql, struct evsql_trans *trans, const char *command, evsql_query_cb query_fn, void *cb_arg); |
|
164 |
|
165 /* |
|
166 * Same as evsql_query, but uses the SQL-level support for binding parameters. |
|
167 */ |
|
168 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); |
122 |
169 |
123 /* |
170 /* |
124 * Param-building functions |
171 * Param-building functions |
125 */ |
172 */ |
126 int evsql_param_string (struct evsql_query_params *params, size_t param, const char *ptr); |
173 int evsql_param_string (struct evsql_query_params *params, size_t param, const char *ptr); |