mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

This patch (against the current CVS sources) adds to libpq the functions

Browse Source 
PQconnectStart
PQconnectPoll
PQresetStart
PQresetPoll
PQsetenvStart
PQsetenvPoll
PQsetenvAbort

and brings into the published interface

PQsetenv.

The first four are asynchronous analogues of PQconnectdb and PQreset -
they allow an application to connect to the DB without blocking on
remote I/O.

The PQsetenv functions perform an environment negotiation with the
server.

Internal to libpq, pqReadReady and pqWriteReady have been made available
across the library (they were previously static functions inside
fe-misc.c).  A lot of internal rearrangement has been necessary to
support these changes.

The API documentation has been updated also.

Caveats:

  o  The Windows code does not default to using non-blocking sockets,
since I have no documentation: Define WIN32_NON_BLOCKING_CONNECTIONS to
do that.

  o  The SSL code still blocks.


Ewan Mellor.
This commit is contained in:
Bruce Momjian 1999-11-30 03:08:19 +00:00
parent d264b53d2f
commit 3ab5b1f1e6
5 changed files with 1528 additions and 313 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

320
doc/src/sgml/libpq.sgml
View File

@ -57,14 +57,13 @@ header file <FileName>libpq-fe.h</FileName> and must link with the
<synopsis>
PGconn *PQconnectdb(const char *conninfo)
</synopsis>
This routine opens a new database connection using the parameters
taken from the string <literal>conninfo</literal>. Unlike PQsetdbLogin()
below, the parameter set
can be extended without changing the function signature, so use
of this routine is prefered for application programming. The passed
string can be empty to use all default
parameters, or it can contain one or more parameter settings
separated by whitespace.
This routine opens a new database connection using the parameters taken
from the string <literal>conninfo</literal>. Unlike PQsetdbLogin() below,
the parameter set can be extended without changing the function signature,
so use either of this routine or the non-blocking analogues PQconnectStart
/ PQconnectPoll is prefered for application programming. The passed string
can be empty to use all default parameters, or it can contain one or more
parameter settings separated by whitespace.
</Para>
<Para>
Each parameter setting is in the form <literal>keyword = value</literal>.
@ -80,8 +79,38 @@ PGconn *PQconnectdb(const char *conninfo)
<term><literal>host</literal></term>
<ListItem>
<Para>
Host to connect to. If a non-zero-length string is specified, TCP/IP communication is used.
Without a host name, libpq will connect using a local Unix domain socket.
Name of host to connect to. If a non-zero-length string is specified, TCP/IP
communication is used. Using this parameter causes a hostname look-up.
See hostaddr.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<term><literal>hostaddr</literal></term>
<ListItem>
<Para>
IP address of host to connect to. This should be in standard
numbers-and-dots form, as used by the BSD functions inet_aton et al. If
a non-zero-length string is specified, TCP/IP communication is used.
</Para>
<Para>
Using hostaddr instead of host allows the application to avoid a host
name look-up, which may be important in applications with time
constraints. However, Kerberos authentication requires the host
name. The following therefore applies. If host is specified without
hostaddr, a hostname look-up is forced. If hostaddr is specified without
host, the value for hostaddr gives the remote address; if Kerberos is
used, this causes a reverse name query. If both host and hostaddr are
specified, the value for hostaddr gives the remote address; the value
for host is ignored, unless Kerberos is used, in which case that value
is used for Kerberos authentication. Note that authentication is likely
to fail if libpq is passed a host name which is not the name of the
machine at hostaddr.
</Para>
<Para>
Without both a host name and host address, libpq will connect using a
local Unix domain socket.
</Para>
</ListItem>
</VarListEntry>
@ -149,6 +178,9 @@ PGconn *PQconnectdb(const char *conninfo)
The return value is a pointer to an abstract struct
representing the connection to the backend.
</Para>
<Para>
This function is not thread-safe.
</Para>
</ListItem>
<ListItem>
@ -167,6 +199,9 @@ PGconn *PQsetdbLogin(const char *pghost,
This is the predecessor of <function>PQconnectdb</function> with a fixed number
of parameters but the same functionality.
</Para>
<Para>
This function is not thread-safe.
</Para>
</ListItem>
<ListItem>
@ -185,6 +220,173 @@ PGconn *PQsetdb(char *pghost,
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQconnectStart</Function>
<Function>PQconnectPoll</Function>
Make a connection to the database server in a non-blocking manner.
<synopsis>
PGconn *PQconnectStart(const char *conninfo)
</synopsis>
<synopsis>
PostgresPollingStatusType *PQconnectPoll(PQconn *conn)
</synopsis>
These two routines are used to open a connection to a database server such
that your application's thread of execution is not blocked on remote I/O
whilst doing so.
</Para>
<Para>
The database connection is made using the parameters taken from the string
<literal>conninfo</literal>, passed to PQconnectStart. This string is in
the same format as described above for PQconnectdb.
</Para>
<Para>
Neither PQconnectStart nor PQconnectPoll will block, as long as a number of
restrictions are met:
<ItemizedList>
<ListItem>
<Para>
The hostaddr and host parameters are used appropriately to ensure that
name and reverse name queries are not made. See the documentation of
these parameters under PQconnectdb above for details.
</Para>
</ListItem>
<ListItem>
<Para>
If you call PQtrace, ensure that the stream object into which you trace
will not block.
</Para>
</ListItem>
<ListItem>
<Para>
You ensure for yourself that the socket is in the appropriate state
before calling PQconnectPoll, as described below.
</Para>
</ListItem>
</ItemizedList>
</Para>
<Para>
To begin, call conn=PQconnectStart("&lt;connection_info_string&gt;"). If
conn is NULL, then libpq has been unable to allocate a new PGconn
structure. Otherwise, a valid PGconn pointer is returned (though not yet
representing a valid connection to the database). On return from
PQconnectStart, call status=PQstatus(conn). If status equals
CONNECTION_BAD, PQconnectStart has failed.
</Para>
<Para>
If PQconnectStart succeeds, the next stage is to poll libpq so that it may
proceed with the connection sequence. Loop thus: Consider a connection
'inactive' by default. If PQconnectPoll last returned PGRES_POLLING_ACTIVE,
consider it 'active' instead. If PQconnectPoll(conn) last returned
PGRES_POLLING_READING, perform a select for reading on PQsocket(conn). If
it last returned PGRES_POLLING_WRITING, perform a select for writing on
PQsocket(conn). If you have yet to call PQconnectPoll, i.e. after the call
to PQconnectStart, behave as if it last returned PGRES_POLLING_WRITING. If
the select shows that the socket is ready, consider it 'active'. If it has
been decided that this connection is 'active', call PQconnectPoll(conn)
again. If this call returns PGRES_POLLING_FAILED, the connection procedure
has failed. If this call returns PGRES_POLLING_OK, the connection has been
successfully made.
</Para>
<Para>
Note that the use of select() to ensure that the socket is ready is merely
a (likely) example; those with other facilities available, such as a
poll() call, may of course use that instead.
</Para>
<Para>
At any time during connection, the status of the connection may be
checked, by calling PQstatus. If this is CONNECTION_BAD, then the
connection procedure has failed; if this is CONNECTION_OK, then the
connection is ready. Either of these states should be equally detectable
from the return value of PQconnectPoll, as above. Other states may be
shown during (and only during) an asynchronous connection procedure. These
indicate the current stage of the connection procedure, and may be useful
to provide feedback to the user for example. These statuses may include:
<ItemizedList>
<ListItem>
<Para>
CONNECTION_STARTED: Waiting for connection to be made.
</Para>
</ListItem>
<ListItem>
<Para>
CONNECTION_MADE: Connection OK; waiting to send.
</Para>
</ListItem>
<ListItem>
<Para>
CONNECTION_AWAITING_RESPONSE: Waiting for a response from the backend.
</Para>
</ListItem>
<ListItem>
<Para>
CONNECTION_AUTH_RESPONSE: Got an authentication response; about to deal
with it.
</Para>
</ListItem>
<ListItem>
<Para>
CONNECTION_ERROR_RESPONSE: Got an error response; about to deal with it.
</Para>
</ListItem>
<ListItem>
<Para>
CONNECTION_AUTH_OK: Received authentication; waiting for ReadyForQuery etc.
</Para>
</ListItem>
<ListItem>
<Para>
CONNECTION_SETENV: Negotiating environment.
</Para>
</ListItem>
</ItemizedList>
Note that, although these constants will remain (in order to maintain
compatibility) an application should never rely upon these appearing in a
particular order, or at all, or on the status always being one of these
documented values. An application may do something like this:
<ProgramListing>
switch(PQstatus(conn))
{
case CONNECTION_STARTED:
feedback = "Connecting...";
break;
case CONNECTION_MADE:
feedback = "Connected to server...";
break;
.
.
.
default:
feedback = "Connecting...";
}
</ProgramListing>
</Para>
<Para>
Note that if PQconnectStart returns a non-NULL pointer, you must call
PQfinish upon that, when you are finished with it, in order to dispose of
the structure and any associated memory blocks. This must be done even if a
call to PQconnectStart or PQconnectPoll failed.
</Para>
<Para>
PQconnectPoll will currently block if libpq is compiled with USE_SSL
defined. This restriction may be removed in the future.
</Para>
<Para>
PQconnectPoll will currently block under Windows, unless libpq is compiled
with WIN32_NON_BLOCKING_CONNECTIONS defined. This code has not yet been
tested under Windows, and so it is currently off by default. This may be
changed in the future.
</Para>
<Para>
These functions are not thread-safe.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQconndefaults</Function> Returns the default connection options.
@ -215,6 +417,9 @@ struct PQconninfoOption
will depend on environment variables and other context.
Callers must treat the connection options data as read-only.
</Para>
<Para>
This function is not thread-safe.
</Para>
</ListItem>
<ListItem>
@ -247,6 +452,31 @@ void PQreset(PGconn *conn)
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQresetStart</Function>
<Function>PQresetPoll</Function>
Reset the communication port with the backend, in a non-blocking manner.
<synopsis>
int PQresetStart(PGconn *conn);
</synopsis>
<synopsis>
PostgresPollingStatusType PQresetPoll(PGconn *conn);
</synopsis>
These functions will close the connection to the backend and attempt to
reestablish a new connection to the same postmaster, using all the same
parameters previously used. This may be useful for error recovery if a
working connection is lost. They differ from PQreset (above) in that they
act in a non-blocking manner. These functions suffer from the same
restrictions as PQconnectStart and PQconnectPoll.
</Para>
<Para>
Call PQresetStart. If it returns 0, the reset has failed. If it returns 1,
poll the reset using PQresetPoll in exactly the same way as you would
create the connection using PQconnectPoll.
</Para>
</ListItem>
</ItemizedList>
</Para>
@ -338,19 +568,25 @@ const char *PQoptions(const PGconn *conn)
<Para>
<Function>PQstatus</Function>
Returns the status of the connection.
The status can be <literal>CONNECTION_OK</literal> or <literal>CONNECTION_BAD</literal>.
<synopsis>
ConnStatusType PQstatus(const PGconn *conn)
</synopsis>
</Para>
<Para>
A failed connection attempt is signaled by status <literal>CONNECTION_BAD</literal>.
Ordinarily, an OK status will remain so until <function>PQfinish</function>, but a
The status can be one of a number of values. However, only two of these are
seen outside of an asynchronous connection procedure -
<literal>CONNECTION_OK</literal> or <literal>CONNECTION_BAD</literal>. A good
connection to the database has the status CONNECTION_OK. A failed connection
attempt is signaled by status <literal>CONNECTION_BAD</literal>. Ordinarily,
an OK status will remain so until <function>PQfinish</function>, but a
communications failure might result in the status changing to
<literal>CONNECTION_BAD</literal> prematurely. In that case the application could
try to recover by calling <function>PQreset</function>.
<literal>CONNECTION_BAD</literal> prematurely. In that case the application
could try to recover by calling <function>PQreset</function>.
</Para>
<Para>
See the entry for PQconnectStart and PQconnectPoll with regards to other status codes
that might be seen.
</ListItem>
<ListItem>
@ -385,6 +621,60 @@ server host, not the local host!
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQsetenvStart</Function>
<Function>PQsetenvPoll</Function>
<Function>PQsetenvAbort</Function>
Perform an environment negotiation.
<synopsis>
PGsetenvHandle *PQsetenvStart(PGconn *conn)
</synopsis>
<synopsis>
PostgresPollingStatusType *PQsetenvPoll(PGsetenvHandle handle)
</synopsis>
<synopsis>
void PQsetenvAbort(PGsetenvHandle handle)
</synopsis>
These two routines can be used to re-perform the environment negotiation
that occurs during the opening of a connection to a database server. I have
no idea why this might be useful (XXX anyone?) but it might prove useful
for users to be able to reconfigure their character encodings on-the-fly,
for example.
</Para>
<Para>
These functions will not block, subject to the restrictions applied to
PQconnectStart and PQconnectPoll.
</Para>
<Para>
To begin, call handle=PQsetenvStart(conn), where conn is an open connection
to the database server. If handle is NULL, then libpq has been unable to
allocate a new PGsetenvHandle structure. Otherwise, a valid handle is
returned. This handle is intended to be opaque - you may only use it to
call other functions in libpq (PQsetenvPoll, for example).
</Para>
<Para>
Poll the procedure using PQsetenvPoll, in exactly the same way as you would
create a connection using PQconnectPoll.
</Para>
<Para>
The procedure may be aborted at any time by calling PQsetenvAbort(handle).
</Para>
<Para>
These functions are not thread-safe.
</Para>
</ListItem>
<ListItem>
<Para>
<Function>PQsetenv</Function>
Perform an environment negotiation.
<synopsis>
int PQsetenv(PGconn *conn)
</synopsis>
This function performs the same duties as PQsetenvStart and PQsetenvPoll, but
blocks to do so. It returns 1 on success and 0 on failure.
</Para>
</ItemizedList>
</Para>
</Sect1>

1372
src/interfaces/libpq/fe-connect.c
View File

File diff suppressed because it is too large Load Diff

77
src/interfaces/libpq/fe-misc.c
View File

@ -24,7 +24,7 @@
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/interfaces/libpq/fe-misc.c,v 1.32 1999/11/11 00:10:14 momjian Exp $
* $Header: /cvsroot/pgsql/src/interfaces/libpq/fe-misc.c,v 1.33 1999/11/30 03:08:19 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -269,29 +269,69 @@ pqPutInt(int value, size_t bytes, PGconn *conn)
/* --------------------------------------------------------------------- */
/* pqReadReady: is select() saying the file is ready to read?
* Returns -1 on failure, 0 if not ready, 1 if ready.
*/
static int
int
pqReadReady(PGconn *conn)
{
fd_set input_mask;
struct timeval timeout;
if (conn->sock < 0)
return 0;
if (!conn || conn->sock < 0)
return -1;
FD_ZERO(&input_mask);
FD_SET(conn->sock, &input_mask);
timeout.tv_sec = 0;
timeout.tv_usec = 0;
retry:
if (select(conn->sock + 1, &input_mask, (fd_set *) NULL, (fd_set *) NULL,
&timeout) < 0)
{
if (errno == EINTR)
/* Interrupted system call - we'll just try again */
goto retry;
printfPQExpBuffer(&conn->errorMessage,
"pqReadReady() -- select() failed: errno=%d\n%s\n",
errno, strerror(errno));
return 0;
return -1;
}
return FD_ISSET(conn->sock, &input_mask);
return FD_ISSET(conn->sock, &input_mask) ? 1 : 0;
}
/* --------------------------------------------------------------------- */
/* pqWriteReady: is select() saying the file is ready to write?
* Returns -1 on failure, 0 if not ready, 1 if ready.
*/
int
pqWriteReady(PGconn *conn)
{
fd_set input_mask;
struct timeval timeout;
if (!conn || conn->sock < 0)
return -1;
FD_ZERO(&input_mask);
FD_SET(conn->sock, &input_mask);
timeout.tv_sec = 0;
timeout.tv_usec = 0;
retry:
if (select(conn->sock + 1, (fd_set *) NULL, &input_mask, (fd_set *) NULL,
&timeout) < 0)
{
if (errno == EINTR)
/* Interrupted system call - we'll just try again */
goto retry;
printfPQExpBuffer(&conn->errorMessage,
"pqWriteReady() -- select() failed: errno=%d\n%s\n",
errno, strerror(errno));
return -1;
}
return FD_ISSET(conn->sock, &input_mask) ? 1 : 0;
}
/* --------------------------------------------------------------------- */
@ -418,8 +458,17 @@ tryAgain:
* be taken much, since in normal practice we should not be trying to
* read data unless the file selected for reading already.
*/
if (!pqReadReady(conn))
return 0; /* definitely no data available */
switch (pqReadReady(conn))
{
case 0:
/* definitely no data available */
return 0;
case 1:
/* ready for read */
break;
default:
goto definitelyFailed;
}
/*
* Still not sure that it's EOF, because some data could have just
@ -570,6 +619,10 @@ pqFlush(PGconn *conn)
if (len > 0)
{
/* We didn't send it all, wait till we can send more */
/* At first glance this looks as though it should block. I think
* that it will be OK though, as long as the socket is
* non-blocking. */
if (pqWait(FALSE, TRUE, conn))
return EOF;
}
@ -599,9 +652,9 @@ pqWait(int forRead, int forWrite, PGconn *conn)
return EOF;
}
/* loop in case select returns EINTR */
for (;;)
if (forRead || forWrite)
{
retry:
FD_ZERO(&input_mask);
FD_ZERO(&output_mask);
if (forRead)
@ -612,14 +665,12 @@ pqWait(int forRead, int forWrite, PGconn *conn)
(struct timeval *) NULL) < 0)
{
if (errno == EINTR)
continue;
goto retry;
printfPQExpBuffer(&conn->errorMessage,
"pqWait() -- select() failed: errno=%d\n%s\n",
errno, strerror(errno));
return EOF;
}
/* On nonerror return, assume we're done */
break;
}
return 0;

61
src/interfaces/libpq/libpq-fe.h
View File

@ -6,7 +6,7 @@
*
* Copyright (c) 1994, Regents of the University of California
*
* $Id: libpq-fe.h,v 1.52 1999/11/11 00:10:14 momjian Exp $
* $Id: libpq-fe.h,v 1.53 1999/11/30 03:08:19 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -29,10 +29,40 @@ extern "C"
typedef enum
{
/* Although you may decide to change this list in some way,
values which become unused should never be removed, nor
should constants be redefined - that would break
compatibility with existing code. */
CONNECTION_OK,
CONNECTION_BAD
CONNECTION_BAD,
/* Non-blocking mode only below here */
/* The existence of these should never be relied upon - they
should only be used for user feedback or similar purposes. */
CONNECTION_STARTED, /* Waiting for connection to be made. */
CONNECTION_MADE, /* Connection OK; waiting to send. */
CONNECTION_AWAITING_RESPONSE, /* Waiting for a response
from the backend. */
CONNECTION_AUTH_RESPONSE, /* Got an authentication
response; about to deal
with it. */
CONNECTION_ERROR_RESPONSE, /* Got an error
response; about to deal
with it. */
CONNECTION_AUTH_OK, /* Received authentication;
waiting for ReadyForQuery
etc. */
CONNECTION_SETENV /* Negotiating environment. */
} ConnStatusType;
typedef enum
{
PGRES_POLLING_FAILED = 0,
PGRES_POLLING_READING, /* These two indicate that one may */
PGRES_POLLING_WRITING, /* use select before polling again. */
PGRES_POLLING_OK,
PGRES_POLLING_ACTIVE /* Can call poll function immediately.*/
} PostgresPollingStatusType;
typedef enum
{
PGRES_EMPTY_QUERY = 0,
@ -67,6 +97,12 @@ extern "C"
*/
typedef struct pg_result PGresult;
/* PGsetenvHandle is an opaque handle which is returned by PQsetenvStart and
* which should be passed to PQsetenvPoll or PQsetenvAbort in order to refer
* to the particular process being performed.
*/
typedef struct pg_setenv_state *PGsetenvHandle;
/* PGnotify represents the occurrence of a NOTIFY message.
* Ideally this would be an opaque typedef, but it's so simple that it's
* unlikely to change.
@ -152,11 +188,15 @@ extern "C"
/* === in fe-connect.c === */
/* make a new client connection to the backend */
/* Asynchronous (non-blocking) */
extern PGconn *PQconnectStart(const char *conninfo);
extern PostgresPollingStatusType PQconnectPoll(PGconn *conn);
/* Synchronous (blocking) */
extern PGconn *PQconnectdb(const char *conninfo);
extern PGconn *PQsetdbLogin(const char *pghost, const char *pgport,
const char *pgoptions, const char *pgtty,
const char *dbName,
const char *login, const char *pwd);
const char *dbName,
const char *login, const char *pwd);
#define PQsetdb(M_PGHOST,M_PGPORT,M_PGOPT,M_PGTTY,M_DBNAME) \
PQsetdbLogin(M_PGHOST, M_PGPORT, M_PGOPT, M_PGTTY, M_DBNAME, NULL, NULL)
@ -170,6 +210,10 @@ extern "C"
* close the current connection and restablish a new one with the same
* parameters
*/
/* Asynchronous (non-blocking) */
extern int PQresetStart(PGconn *conn);
extern PostgresPollingStatusType PQresetPoll(PGconn *conn);
/* Synchronous (blocking) */
extern void PQreset(PGconn *conn);
/* issue a cancel request */
@ -195,6 +239,15 @@ extern "C"
/* Override default notice processor */
extern PQnoticeProcessor PQsetNoticeProcessor(PGconn *conn, PQnoticeProcessor proc, void *arg);
/* Passing of environment variables */
/* Asynchronous (non-blocking) */
extern PGsetenvHandle PQsetenvStart(PGconn *conn);
extern PostgresPollingStatusType PQsetenvPoll(PGsetenvHandle handle);
extern void PQsetenvAbort(PGsetenvHandle handle);
/* Synchronous (blocking) */
extern int PQsetenv(PGconn *conn);
/* === in fe-exec.c === */
/* Simple synchronous query */

11
src/interfaces/libpq/libpq-int.h
View File

@ -11,7 +11,7 @@
*
* Copyright (c) 1994, Regents of the University of California
*
* $Id: libpq-int.h,v 1.13 1999/11/11 00:10:14 momjian Exp $
* $Id: libpq-int.h,v 1.14 1999/11/30 03:08:19 momjian Exp $
*
*-------------------------------------------------------------------------
*/
@ -168,6 +168,10 @@ struct pg_conn
/* Saved values of connection options */
char *pghost; /* the machine on which the server is
* running */
char *pghostaddr; /* the IPv4 address of the machine on
* which the server is running, in
* IPv4 numbers-and-dots notation. Takes
* precedence over above. */
char *pgport; /* the server's communication port */
char *pgtty; /* tty on which the backend messages is
* displayed (NOT ACTUALLY USED???) */
@ -220,6 +224,9 @@ struct pg_conn
PGresult *result; /* result being constructed */
PGresAttValue *curTuple; /* tuple currently being read */
/* Handle for setenv request. Used during connection only. */
PGsetenvHandle setenv_handle;
#ifdef USE_SSL
SSL *ssl;
#endif
@ -268,6 +275,8 @@ extern int pqPutInt(int value, size_t bytes, PGconn *conn);
extern int pqReadData(PGconn *conn);
extern int pqFlush(PGconn *conn);
extern int pqWait(int forRead, int forWrite, PGconn *conn);
extern int pqReadReady(PGconn *conn);
extern int pqWriteReady(PGconn *conn);
/* bits in a byte */
#define BYTELEN 8