Re: BUG #5837: PQstatus() fails to report lost connection

> -----Original Message-----
> From: Kevin Grittner [mailto:Kevin.Grittner@wicourts.gov]
> Sent: Monday, January 24, 2011 9:50 AM
> To: Murray S. Kucherawy; Tom Lane
> Cc: Robert Haas; pgsql-bugs@postgresql.org
> Subject: Re: [BUGS] BUG #5837: PQstatus() fails to report lost connection
>=20
> "Murray S. Kucherawy" <msk@cloudmark.com> wrote:
>=20
> > Please, at a minimum, add some documentation about it.
>=20
> Current documentation at:
>=20
> http://www.postgresql.org/docs/9.0/interactive/libpq-async.html
>=20
> says:
>=20
> | PQgetResult must be called repeatedly until it returns a null
> | pointer, indicating that the command is done.
>=20
> What do you think would make this more clear?

"command is done" sounds like normal operation to me, but we're talking abo=
ut an obvious exception here.  The command (I assume that means the query t=
hat ultimately failed) can't even have started because the connection was g=
one.  That's why I find the description misleading.

Indeed, the function order you're talking about is PQgetResult(), which ret=
urns non-NULL in this condition (which looks like there's a result availabl=
e), but then PQresultStatus() returns PGRES_FATAL_ERROR.  It's not very obv=
ious to me that the right thing to do here is call PQgetResult() again just=
 to get PQstatus() to tell me the truth.  Now we're dealing with an excepti=
on rather than something normal.

So maybe something like this after the paragraph you cited would help:

"Note that after returning a PGresult object, PQresultStatus() could indica=
te a fatal error.  The caller should still iterate calling PQgetResult() to=
 completion (i.e. until it returns NULL) in order to allow libpq to process=
 the error information completely."