Robert Haas <robertmh...@gmail.com> writes:
> On Wed, Jun 12, 2024 at 3:00 PM Tom Lane <t...@sss.pgh.pa.us> wrote:
>> So how about one of
>> pg_usec_time_t
>> pg_time_t_usec
>> ?
> The former seems better to me, since having _t not at the end does not
> seem too intuitive.
True. We can guess about how POSIX might spell this if they ever
invent the concept, but one choice they certainly would not make
is time_t_usec.
v3 attached uses pg_usec_time_t, and fixes one brown-paper-bag
bug the cfbot noticed in v2.
regards, tom lane
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 80179f9978..814c49bdd1 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -268,30 +268,52 @@ PGconn *PQsetdb(char *pghost,
<para>
<indexterm><primary>nonblocking connection</primary></indexterm>
Poll a connection's underlying socket descriptor retrieved with <xref linkend="libpq-PQsocket"/>.
+ The primary use of this function is iterating through the connection
+ sequence described in the documentation of
+ <xref linkend="libpq-PQconnectStartParams"/>.
<synopsis>
-int PQsocketPoll(int sock, int forRead, int forWrite, time_t end_time);
+typedef pg_int64 pg_usec_time_t;
+
+int PQsocketPoll(int sock, int forRead, int forWrite,
+ pg_usec_time_t end_time);
</synopsis>
</para>
<para>
- This function sets up polling of a file descriptor. The underlying function is either
+ This function performs polling of a file descriptor, optionally with
+ a timeout. The underlying function is either
<function>poll(2)</function> or <function>select(2)</function>, depending on platform
- support. The primary use of this function is iterating through the connection sequence
- described in the documentation of <xref linkend="libpq-PQconnectStartParams"/>. If
- <parameter>forRead</parameter> is specified, the function waits for the socket to be ready
- for reading. If <parameter>forWrite</parameter> is specified, the function waits for the
- socket to be ready for write. See <literal>POLLIN</literal> and <literal>POLLOUT</literal>
+ support.
+ If <parameter>forRead</parameter> is nonzero, the
+ function will terminate when the socket is ready for
+ reading. If <parameter>forWrite</parameter> is nonzero,
+ the function will terminate when the
+ socket is ready for writing.
+ See <literal>POLLIN</literal> and <literal>POLLOUT</literal>
from <function>poll(2)</function>, or <parameter>readfds</parameter> and
- <parameter>writefds</parameter> from <function>select(2)</function> for more information. If
- <parameter>end_time</parameter> is not <literal>-1</literal>, it specifies the time at which
- this function should stop waiting for the condition to be met.
+ <parameter>writefds</parameter> from <function>select(2)</function> for more information.
+ </para>
+
+ <para>
+ The timeout is specified by <parameter>end_time</parameter>, which
+ is the time to stop waiting expressed as a number of microseconds since
+ the Unix epoch (that is, <type>time_t</type> times 1 million).
+ Timeout is infinite if <parameter>end_time</parameter>
+ is <literal>-1</literal>. Timeout is immediate (no blocking) if
+ end_time is <literal>0</literal> (or indeed, any time before now).
+ Timeout values can be calculated conveniently by adding the desired
+ number of microseconds to the result of
+ <xref linkend="libpq-PQgetCurrentTimeUSec"/>.
+ Note that the underlying system calls may have less than microsecond
+ precision, so that the actual delay may be imprecise.
</para>
<para>
The function returns a value greater than <literal>0</literal> if the specified condition
is met, <literal>0</literal> if a timeout occurred, or <literal>-1</literal> if an error
occurred. The error can be retrieved by checking the <literal>errno(3)</literal> value. In
- the event <literal>forRead</literal> and <literal>forWrite</literal> are not set, the
+ the event both <parameter>forRead</parameter>
+ and <parameter>forWrite</parameter> are zero, the
function immediately returns a timeout condition.
</para>
</listitem>
@@ -8039,6 +8061,25 @@ int PQlibVersion(void);
</listitem>
</varlistentry>
+ <varlistentry id="libpq-PQgetCurrentTimeUSec">
+ <term><function>PQgetCurrentTimeUSec</function><indexterm><primary>PQgetCurrentTimeUSec</primary></indexterm></term>
+
+ <listitem>
+ <para>
+ Retrieves the current time, expressed as the number of microseconds
+ since the Unix epoch (that is, <type>time_t</type> times 1 million).
+<synopsis>
+pg_usec_time_t PQgetCurrentTimeUSec(void);
+</synopsis>
+ </para>
+
+ <para>
+ This is primarily useful for calculating timeout values to use with
+ <xref linkend="libpq-PQsocketPoll"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect1>
diff --git a/src/bin/psql/command.c b/src/bin/psql/command.c
index fae5940b54..180781ecd0 100644
--- a/src/bin/psql/command.c
+++ b/src/bin/psql/command.c
@@ -3764,7 +3764,7 @@ wait_until_connected(PGconn *conn)
{
int rc;
int sock;
- time_t end_time;
+ pg_usec_time_t end_time;
/*
* On every iteration of the connection sequence, let's check if the
@@ -3795,7 +3795,7 @@ wait_until_connected(PGconn *conn)
* solution happens to just be adding a timeout, so let's wait for 1
* second and check cancel_pressed again.
*/
- end_time = time(NULL) + 1;
+ end_time = PQgetCurrentTimeUSec() + 1000000;
rc = PQsocketPoll(sock, forRead, !forRead, end_time);
if (rc == -1)
return;
diff --git a/src/interfaces/libpq/exports.txt b/src/interfaces/libpq/exports.txt
index 8ee0811510..5d8213e0b5 100644
--- a/src/interfaces/libpq/exports.txt
+++ b/src/interfaces/libpq/exports.txt
@@ -204,3 +204,4 @@ PQcancelReset 201
PQcancelFinish 202
PQsocketPoll 203
PQsetChunkedRowsMode 204
+PQgetCurrentTimeUSec 205
diff --git a/src/interfaces/libpq/fe-connect.c b/src/interfaces/libpq/fe-connect.c
index 995621b626..19d067f4a2 100644
--- a/src/interfaces/libpq/fe-connect.c
+++ b/src/interfaces/libpq/fe-connect.c
@@ -2470,7 +2470,7 @@ int
pqConnectDBComplete(PGconn *conn)
{
PostgresPollingStatusType flag = PGRES_POLLING_WRITING;
- time_t finish_time = ((time_t) -1);
+ pg_usec_time_t end_time = -1;
int timeout = 0;
int last_whichhost = -2; /* certainly different from whichhost */
int last_whichaddr = -2; /* certainly different from whichaddr */
@@ -2519,7 +2519,7 @@ pqConnectDBComplete(PGconn *conn)
(conn->whichhost != last_whichhost ||
conn->whichaddr != last_whichaddr))
{
- finish_time = time(NULL) + timeout;
+ end_time = PQgetCurrentTimeUSec() + (pg_usec_time_t) timeout * 1000000;
last_whichhost = conn->whichhost;
last_whichaddr = conn->whichaddr;
}
@@ -2534,7 +2534,7 @@ pqConnectDBComplete(PGconn *conn)
return 1; /* success! */
case PGRES_POLLING_READING:
- ret = pqWaitTimed(1, 0, conn, finish_time);
+ ret = pqWaitTimed(1, 0, conn, end_time);
if (ret == -1)
{
/* hard failure, eg select() problem, aborts everything */
@@ -2544,7 +2544,7 @@ pqConnectDBComplete(PGconn *conn)
break;
case PGRES_POLLING_WRITING:
- ret = pqWaitTimed(0, 1, conn, finish_time);
+ ret = pqWaitTimed(0, 1, conn, end_time);
if (ret == -1)
{
/* hard failure, eg select() problem, aborts everything */
diff --git a/src/interfaces/libpq/fe-misc.c b/src/interfaces/libpq/fe-misc.c
index f562cd8d34..f235bfbb41 100644
--- a/src/interfaces/libpq/fe-misc.c
+++ b/src/interfaces/libpq/fe-misc.c
@@ -54,7 +54,7 @@
static int pqPutMsgBytes(const void *buf, size_t len, PGconn *conn);
static int pqSendSome(PGconn *conn, int len);
static int pqSocketCheck(PGconn *conn, int forRead, int forWrite,
- time_t end_time);
+ pg_usec_time_t end_time);
/*
* PQlibVersion: return the libpq version number
@@ -977,22 +977,25 @@ pqFlush(PGconn *conn)
int
pqWait(int forRead, int forWrite, PGconn *conn)
{
- return pqWaitTimed(forRead, forWrite, conn, (time_t) -1);
+ return pqWaitTimed(forRead, forWrite, conn, -1);
}
/*
- * pqWaitTimed: wait, but not past finish_time.
- *
- * finish_time = ((time_t) -1) disables the wait limit.
+ * pqWaitTimed: wait, but not past end_time.
*
* Returns -1 on failure, 0 if the socket is readable/writable, 1 if it timed out.
+ *
+ * The timeout is specified by end_time, which is the int64 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).
*/
int
-pqWaitTimed(int forRead, int forWrite, PGconn *conn, time_t finish_time)
+pqWaitTimed(int forRead, int forWrite, PGconn *conn, pg_usec_time_t end_time)
{
int result;
- result = pqSocketCheck(conn, forRead, forWrite, finish_time);
+ result = pqSocketCheck(conn, forRead, forWrite, end_time);
if (result < 0)
return -1; /* errorMessage is already set */
@@ -1013,7 +1016,7 @@ pqWaitTimed(int forRead, int forWrite, PGconn *conn, time_t finish_time)
int
pqReadReady(PGconn *conn)
{
- return pqSocketCheck(conn, 1, 0, (time_t) 0);
+ return pqSocketCheck(conn, 1, 0, 0);
}
/*
@@ -1023,7 +1026,7 @@ pqReadReady(PGconn *conn)
int
pqWriteReady(PGconn *conn)
{
- return pqSocketCheck(conn, 0, 1, (time_t) 0);
+ return pqSocketCheck(conn, 0, 1, 0);
}
/*
@@ -1035,7 +1038,7 @@ pqWriteReady(PGconn *conn)
* for read data directly.
*/
static int
-pqSocketCheck(PGconn *conn, int forRead, int forWrite, time_t end_time)
+pqSocketCheck(PGconn *conn, int forRead, int forWrite, pg_usec_time_t end_time)
{
int result;
@@ -1079,11 +1082,13 @@ pqSocketCheck(PGconn *conn, int forRead, int forWrite, time_t end_time)
* condition (without waiting). Return >0 if condition is met, 0
* if a timeout occurred, -1 if an error or interrupt occurred.
*
+ * The timeout is specified by end_time, which is the int64 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).
*/
int
-PQsocketPoll(int sock, int forRead, int forWrite, time_t end_time)
+PQsocketPoll(int sock, int forRead, int forWrite, pg_usec_time_t end_time)
{
/* We use poll(2) if available, otherwise select(2) */
#ifdef HAVE_POLL
@@ -1103,14 +1108,16 @@ PQsocketPoll(int sock, int forRead, int forWrite, time_t end_time)
input_fd.events |= POLLOUT;
/* Compute appropriate timeout interval */
- if (end_time == ((time_t) -1))
+ if (end_time == -1)
timeout_ms = -1;
+ else if (end_time == 0)
+ timeout_ms = 0;
else
{
- time_t now = time(NULL);
+ pg_usec_time_t now = PQgetCurrentTimeUSec();
if (end_time > now)
- timeout_ms = (end_time - now) * 1000;
+ timeout_ms = (end_time - now) / 1000;
else
timeout_ms = 0;
}
@@ -1138,17 +1145,28 @@ PQsocketPoll(int sock, int forRead, int forWrite, time_t end_time)
FD_SET(sock, &except_mask);
/* Compute appropriate timeout interval */
- if (end_time == ((time_t) -1))
+ if (end_time == -1)
ptr_timeout = NULL;
+ else if (end_time == 0)
+ {
+ timeout.tv_sec = 0;
+ timeout.tv_usec = 0;
+ ptr_timeout = &timeout;
+ }
else
{
- time_t now = time(NULL);
+ pg_usec_time_t now = PQgetCurrentTimeUSec();
if (end_time > now)
- timeout.tv_sec = end_time - now;
+ {
+ timeout.tv_sec = (end_time - now) / 1000000;
+ timeout.tv_usec = (end_time - now) % 1000000;
+ }
else
+ {
timeout.tv_sec = 0;
- timeout.tv_usec = 0;
+ timeout.tv_usec = 0;
+ }
ptr_timeout = &timeout;
}
@@ -1157,6 +1175,21 @@ PQsocketPoll(int sock, int forRead, int forWrite, time_t end_time)
#endif /* HAVE_POLL */
}
+/*
+ * PQgetCurrentTimeUSec: get current time with microsecond precision
+ *
+ * This provides a platform-independent way of producing a reference
+ * value for PQsocketPoll's timeout parameter.
+ */
+pg_usec_time_t
+PQgetCurrentTimeUSec(void)
+{
+ struct timeval tval;
+
+ gettimeofday(&tval, NULL);
+ return (pg_usec_time_t) tval.tv_sec * 1000000 + tval.tv_usec;
+}
+
/*
* A couple of "miscellaneous" multibyte related functions. They used
diff --git a/src/interfaces/libpq/libpq-fe.h b/src/interfaces/libpq/libpq-fe.h
index 73f6e65ae5..67a0aad40d 100644
--- a/src/interfaces/libpq/libpq-fe.h
+++ b/src/interfaces/libpq/libpq-fe.h
@@ -202,6 +202,9 @@ typedef struct pgNotify
struct pgNotify *next; /* list link */
} PGnotify;
+/* pg_usec_time_t is like time_t, but with microsecond resolution */
+typedef pg_int64 pg_usec_time_t;
+
/* Function types for notice-handling callbacks */
typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
typedef void (*PQnoticeProcessor) (void *arg, const char *message);
@@ -673,7 +676,11 @@ extern int lo_export(PGconn *conn, Oid lobjId, const char *filename);
extern int PQlibVersion(void);
/* Poll a socket for reading and/or writing with an optional timeout */
-extern int PQsocketPoll(int sock, int forRead, int forWrite, time_t end_time);
+extern int PQsocketPoll(int sock, int forRead, int forWrite,
+ pg_usec_time_t end_time);
+
+/* Get current time in the form PQsocketPoll wants */
+extern pg_usec_time_t PQgetCurrentTimeUSec(void);
/* Determine length of multibyte encoded char at *s */
extern int PQmblen(const char *s, int encoding);
diff --git a/src/interfaces/libpq/libpq-int.h b/src/interfaces/libpq/libpq-int.h
index 3886204c70..f36d76bf3f 100644
--- a/src/interfaces/libpq/libpq-int.h
+++ b/src/interfaces/libpq/libpq-int.h
@@ -755,7 +755,7 @@ extern int pqReadData(PGconn *conn);
extern int pqFlush(PGconn *conn);
extern int pqWait(int forRead, int forWrite, PGconn *conn);
extern int pqWaitTimed(int forRead, int forWrite, PGconn *conn,
- time_t finish_time);
+ pg_usec_time_t end_time);
extern int pqReadReady(PGconn *conn);
extern int pqWriteReady(PGconn *conn);
diff --git a/src/tools/pgindent/typedefs.list b/src/tools/pgindent/typedefs.list
index 4f57078d13..61ad417cde 100644
--- a/src/tools/pgindent/typedefs.list
+++ b/src/tools/pgindent/typedefs.list
@@ -3717,6 +3717,7 @@ pg_unicode_normprops
pg_unicode_properties
pg_unicode_range
pg_unicode_recompinfo
+pg_usec_time_t
pg_utf_to_local_combined
pg_uuid_t
pg_wc_probefunc
