This hides from the user the libpq's implementation detail of
requiring the first select() to wait for the connection socket to
become writable and makes it possible to have a uniform select loop
for both cursors and connections, in which you always start by polling
the object and then acting according to the result from poll().
Idea and implementation by Daniele Varrazzo.
If there is an asynchronous query, polling a cursor that did not
initiate it will raise an exception. Polling while there is no
asynchronous query underway still works, because the user needs to
have a way to get asynchronous NOTIFYs.
When a large query is sent to the backend (and probably in high
concurrency situations), writing the query could block. In
this case PQflush() should be called until it returns 0. The test checks
this is done correctly.
POLL_OK has been changed from 3 to 0 to let the user specify a short loop
just as "if not curs.poll()" instead of having to check for write and read
separately. For an example of this, see examples/notify.py.
Some methods were forbidden in asynchronous mode, the isolation level
of an asynchronous connection is not always 0 and these changes
influenced expected test results.
It was trying to get all pending results from the connection and if
the client sent many and anyone except the first one would not be
immediately available the loop in curs_get_last_result would call
PQgetResult blockingly.
Avoid that by calling PQisBusy every time and telling the client to
wait for more data if it returns 1.
The CONN_STATUS_SENT_* statuses were not being handled at all, and
they indicate that a query has been sent, but not fully, so the client
should wait for the socket to become writable again and flush the output.
The methods changed are connection.commit(), rollback(), reset(),
set_isolation_level(), set_client_encoding(), lobject(), cursor(str)
as well as cursor.execute() and cursor.callproc() if another query is
in progress and cursor.executemany(), cursor.copy_{from,to,expert)().
Drop the async kwarg from cursor.execute(), cursors created by
asynchronous connections will be asynchronous by default, ones created
by synchronous connections will be synchronous.
Mind that this might break third party subclasses of
psycopg2.extensions.cursor, if they try to chain to the superclass in
their execute() implementation and are passing the async kwarg. The
example cursors in psycopg2.extras have been fixed no to do that.
Clients using async connections are expected to do their own
transaction management by sending (asynchronously) BEGIN and COMMIT
statements.
As a bonus, it allows to drop one step from the async connection
building, namely getting the default isolation level from the server.
The isread() API was not safe, because the query might have not been
sent fully to the server after calling execute(). To make the async
API complete, a similar mechanism to async connections must be used.
The cursor now has a poll() method that you would use identically to
the poll() method of the connection class.
After calling psycopg2.connect(dsn, async=True) you can poll the
connection that will tell you whether its file descriptor should be
waited on to become writable or readable or that the connection
attempt has succeeded.
Edited commit by Jan to not expose internal state in extensions.py.
Remove the big loop in pq_fetch with the select() call, among
others. Code paths that don't support asynchronous queries should now
be adequately guarded.
The lobject.truncate(len=0) method will be available if psycopg2 has
been built against libpq from 8.3 or later (which is when the lobject
truncating support has been introduced).
