Proposed new async API
Via the [[http://rubyforge.org/forum/forum.php?thread_id=23771&forum_id=12690|Rubyforge forum post]] by Mike Pomraning:
== Revisiting async API == By: Mike Pomraning [2008-03-27 19:00]
PGconn#async_exec is terrific for green threads, and several other libpq 'asynchronous API' functions  would benefit from similarly convenient wrapping.
However, exposing these as async_ methods might get a little crowded, and a touch awkward to pick the right family of methods. Instead, how about extending PGconn objects to support an async flag (e.g., a facets-like toggle async!/async? pair).
When enabled, exec(), prepare(), and (when supported) describe_prepared() and describe_portal() would behave analogously to async_exec: use the proper libpq 'send' function and politely rb_thread_select()/PQgetResult().
Better still, async mode could imply use of PQsetnonblocking/rb_thread_select()/PQflush, so that sending operations are as green-thread-friendly as receiving operations.
What does this community think? It's a bit of a deviation from the raw pq API, but so is 'async_exec', and AFAICT this pg.so API enhancement would Just Work (tm) without breaking anything, esp. if PGconn.new defaulted to async 'on' on green threaded platforms.
 "...other libpq 'asynchronous API' functions"
PQsendQueryPrepared (7.4) Exposed as send_query_prepared(), "async_exec_prepared" needed?
PQsendPrepare (8.0) Exposed as send_prepare(), "async_prepare" needed?
PQsendDescribePrepared (8.2) Not yet exposed. "send_describe_prepared" needed. "async_describe_prepared" needed?
PQsendDescribePortal (8.2) Not yet exposed. "send_describe_portal" needed. "async_describe_portal" needed?
== RE: Revisiting async API == By: Jeff Davis [2008-04-03 18:33]
I agree that it's exposing an implementation detail that's not really necessary.
I also agree that green-threaded applications can benefit from these types of wrappers.
The reason I'm not making it a priority is that: - it requires a significant amount of code, and it's fairly challenging to write good tests - the other functions are used much more rarely than exec - exec has a tendency to block for much longer than, say, a prepare. - if I understand correctly, ruby is moving toward native threads anyway with YARV
None of these put a stop to your proposals at all, and I think your ideas have a lot of merit.
I think the best approach, if we implement this as you say, is to come up with good refactoring of one of the functions to use the flag, and then use that as a template to refactor the rest.
Here are a couple more ideas: - Should we make it a flag at the class level or the connection level? - If we make it at the class level, we can also support async connections.
Thank you for your proposal. I apologize that my reply was so late, I was at a PostgreSQL conference and had some other work to catch up on.
== RE: Revisiting async API == By: Jeff Davis [2008-04-03 18:36]
I meant that I agree that "async_exec" is exposing an implementation detail, and it's cleaner to use a flag to change the behavior.