From 105024a47238e33647d346264b4f6fe68a7287ed Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 13 Jun 2024 15:14:32 -0400 Subject: Improve the granularity of PQsocketPoll's timeout parameter. Commit f5e4dedfa exposed libpq's internal function PQsocketPoll without a lot of thought about whether that was an API we really wanted to chisel in stone. The main problem with it is the use of time_t to specify the timeout. While we do want an absolute time so that a loop around PQsocketPoll doesn't have problems with timeout slippage, time_t has only 1-second resolution. That's already problematic for libpq's own internal usage --- for example, pqConnectDBComplete has long had a kluge to treat "connect_timeout=1" as 2 seconds so that it doesn't accidentally round to nearly zero. And it's even less likely to be satisfactory for external callers. Hence, let's change this while we still can. The best idea seems to be to use an int64 count of microseconds since the epoch --- basically the same thing as the backend's TimestampTz, but let's use the standard Unix epoch (1970-01-01) since that's more likely for clients to be easy to calculate. Millisecond resolution would be plenty for foreseeable uses, but maybe the day will come that we're glad we used microseconds. Also, since time(2) isn't especially helpful for computing timeouts defined this way, introduce a new function PQgetCurrentTimeUSec to get the current time in this form. Remove the hack in pqConnectDBComplete, so that "connect_timeout=1" now means what you'd expect. We can also remove the "#include " that f5e4dedfa added to libpq-fe.h, since there's no longer a need for time_t in that header. It seems better for v17 not to enlarge libpq-fe.h's include footprint from what it's historically been, anyway. I also failed to resist the temptation to do some wordsmithing on PQsocketPoll's documentation. Patch by me, per complaint from Dominique Devienne. Discussion: https://postgr.es/m/913559.1718055575@sss.pgh.pa.us --- doc/src/sgml/libpq.sgml | 121 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 84 insertions(+), 37 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 80179f99783..068ee60771c 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -262,41 +262,6 @@ PGconn *PQsetdb(char *pghost, - - PQsocketPollPQsocketPoll - - - nonblocking connection - Poll a connection's underlying socket descriptor retrieved with . - -int PQsocketPoll(int sock, int forRead, int forWrite, time_t end_time); - - - - - This function sets up polling of a file descriptor. The underlying function is either - poll(2) or select(2), depending on platform - support. The primary use of this function is iterating through the connection sequence - described in the documentation of . If - forRead is specified, the function waits for the socket to be ready - for reading. If forWrite is specified, the function waits for the - socket to be ready for write. See POLLIN and POLLOUT - from poll(2), or readfds and - writefds from select(2) for more information. If - end_time is not -1, it specifies the time at which - this function should stop waiting for the condition to be met. - - - - The function returns a value greater than 0 if the specified condition - is met, 0 if a timeout occurred, or -1 if an error - occurred. The error can be retrieved by checking the errno(3) value. In - the event forRead and forWrite are not set, the - function immediately returns a timeout condition. - - - - PQconnectStartParamsPQconnectStartParams PQconnectStartPQconnectStart @@ -546,6 +511,70 @@ switch(PQstatus(conn)) + + PQsocketPollPQsocketPoll + + + nonblocking connection + Poll a connection's underlying socket descriptor retrieved with + . + The primary use of this function is iterating through the connection + sequence described in the documentation of + . + +typedef pg_int64 pg_usec_time_t; + +int PQsocketPoll(int sock, int forRead, int forWrite, + pg_usec_time_t end_time); + + + + + This function performs polling of a file descriptor, optionally with + a timeout. + If forRead is nonzero, the + function will terminate when the socket is ready for + reading. If forWrite is nonzero, + the function will terminate when the + socket is ready for writing. + + + + The timeout is specified by end_time, which + is the time to stop waiting expressed as a number of microseconds since + the Unix epoch (that is, time_t times 1 million). + Timeout is infinite if end_time + is -1. Timeout is immediate (no blocking) if + end_time is 0 (or indeed, any time before now). + Timeout values can be calculated conveniently by adding the desired + number of microseconds to the result of + . + Note that the underlying system calls may have less than microsecond + precision, so that the actual delay may be imprecise. + + + + The function returns a value greater than 0 if the + specified condition is met, 0 if a timeout occurred, + or -1 if an error occurred. The error can be + retrieved by checking the errno(3) value. In the + event both forRead + and forWrite are zero, the function immediately + returns a timeout indication. + + + + PQsocketPoll is implemented using either + poll(2) or select(2), + depending on platform. See POLLIN + and POLLOUT from poll(2), + or readfds and + writefds from select(2), + for more information. + + + + PQconndefaultsPQconndefaults @@ -1390,8 +1419,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname Maximum time to wait while connecting, in seconds (write as a decimal integer, e.g., 10). Zero, negative, or not specified means - wait indefinitely. The minimum allowed timeout is 2 seconds, therefore - a value of 1 is interpreted as 2. + wait indefinitely. This timeout applies separately to each host name or IP address. For example, if you specify two hosts and connect_timeout is 5, each host will time out if no connection is made within 5 @@ -8039,6 +8067,25 @@ int PQlibVersion(void); + + PQgetCurrentTimeUSecPQgetCurrentTimeUSec + + + + Retrieves the current time, expressed as the number of microseconds + since the Unix epoch (that is, time_t times 1 million). + +pg_usec_time_t PQgetCurrentTimeUSec(void); + + + + + This is primarily useful for calculating timeout values to use with + . + + + + -- cgit v1.2.3