mirror of
https://github.com/psycopg/psycopg2.git
synced 2025-02-25 05:00:32 +03:00
Added explanation of how asynchronous queries work.
This commit is contained in:
parent
988095298e
commit
b19922ebf3
65
doc/async.txt
Normal file
65
doc/async.txt
Normal file
|
@ -0,0 +1,65 @@
|
|||
psycopg asynchronous API
|
||||
************************
|
||||
|
||||
Program code can initiate an asynchronous query by passing an 'async=1' flag
|
||||
to the .execute() method. A very simple example, from the connection to the
|
||||
query:
|
||||
|
||||
conn = psycopg.connect(database='test')
|
||||
curs = conn.cursor()
|
||||
curs.execute("SEECT * from test WHERE fielda > %s", (1971,), async=1)
|
||||
|
||||
From then on any query on other cursors derived from the same connection is
|
||||
doomed to fail (and raise an exception) until the original cursor (the one
|
||||
executing the query) complete the asynchronous operation. This can happen in
|
||||
a number of different ways:
|
||||
|
||||
1) one of the .fetchXXX() methods is called, effectively blocking untill
|
||||
data has been sent from the backend to the client, terminating the
|
||||
query.
|
||||
|
||||
2) .cancel() is called. This method tries to abort the current query and
|
||||
will block until the query is aborted or fully executed. The return
|
||||
value is True if the query was successfully aborted or False if it
|
||||
was executed. Query result are discarded in both cases.
|
||||
|
||||
3) .execute() is called again on the same cursor (.execute() on a
|
||||
different cursor will simply raise an exception.) This waits for the
|
||||
complete execution of the current query, discard any data and execute
|
||||
the new one.
|
||||
|
||||
Note that calling .execute() two times in a row will not abort the former
|
||||
query and will temporarily go to synchronous mode until the first of the two
|
||||
queries is executed.
|
||||
|
||||
Cursors now have some extra methods that make them usefull during
|
||||
asynchronous queries:
|
||||
|
||||
.fileno()
|
||||
Returns the file descriptor associated with the current connection and
|
||||
make possible to use a cursor in a context where a file object would be
|
||||
expected (like in a select() call.)
|
||||
|
||||
.isbusy()
|
||||
Returns True if the backend is still processing the query or false if
|
||||
data is ready to be fetched (by one of the .fetchXXX() methods.)
|
||||
|
||||
A code snippet that shows how to use the cursor object in a select() call:
|
||||
|
||||
import psycopg
|
||||
import select
|
||||
|
||||
conn = psycopg.connect(database='test')
|
||||
curs = conn.cursor()
|
||||
curs.execute("SEECT * from test WHERE fielda > %s", (1971,), async=1)
|
||||
|
||||
# wait for input with a maximum timeout of 5 seconds
|
||||
query_ended = False
|
||||
while not query_ended:
|
||||
rread, rwrite, rspec = select([cursor, another_file], [], [], 5)
|
||||
if not cursor.isbusy():
|
||||
query_ended = True
|
||||
# manage input from other sources like other_file, etc.
|
||||
print "Query Results:"
|
||||
for row in cursor:
|
||||
print row
|
Loading…
Reference in New Issue
Block a user