pg 1.0.0 → 1.1.0.pre20180730144600

data/ext/pg_connection.c

@@ -1,6 +1,6 @@
 /*
  * pg_connection.c - PG::Connection class extension
- * $Id: pg_connection.c,v 1f0926bfa9a5 2018/01/04 18:14:32 lars $
+ * $Id$
  *
  */
 
@@ -198,6 +198,8 @@ pgconn_s_allocate( VALUE klass )
 	this->decoder_for_get_copy_data = Qnil;
 	this->trace_stream = Qnil;
 	this->external_encoding = Qnil;
+	this->socket = -1;
+	this->guess_result_memsize = 1;
 
 	return self;
 }
@@ -270,7 +272,6 @@ pgconn_init(int argc, VALUE *argv, VALUE self)
 	this = pg_get_connection( self );
 	conninfo = rb_funcall2( rb_cPGconn, rb_intern("parse_connect_args"), argc, argv );
 	this->pgconn = gvl_PQconnectdb(StringValueCStr(conninfo));
-
 	if(this->pgconn == NULL)
 		rb_raise(rb_ePGerror, "PQconnectdb() unable to allocate structure");
 
@@ -280,6 +281,10 @@ pgconn_init(int argc, VALUE *argv, VALUE self)
 		rb_exc_raise(error);
 	}
 
+	this->socket = PQsocket( this->pgconn );
+	if ( this->socket < 0 )
+		rb_raise(rb_eConnectionBad, "PQsocket() can't get socket descriptor");
+
 	pgconn_set_default_encoding( self );
 
 	if (rb_block_given_p()) {
@@ -330,6 +335,10 @@ pgconn_s_connect_start( int argc, VALUE *argv, VALUE klass )
 		rb_exc_raise(error);
 	}
 
+	this->socket = PQsocket( this->pgconn );
+	if ( this->socket < 0 )
+		rb_raise(rb_eConnectionBad, "PQsocket() can't get socket descriptor");
+
 	if ( rb_block_given_p() ) {
 		return rb_ensure( rb_yield, rb_conn, pgconn_finish, rb_conn );
 	}
@@ -899,10 +908,8 @@ pgconn_socket_io(VALUE self)
 
 		socket_io = rb_funcall( rb_cIO, rb_intern("for_fd"), 1, INT2NUM(ruby_sd) );
 
-		/* Disable autoclose feature, when supported */
-		if( rb_respond_to(socket_io, id_autoclose) ){
-			rb_funcall( socket_io, id_autoclose, 1, Qfalse );
-		}
+		/* Disable autoclose feature */
+		rb_funcall( socket_io, id_autoclose, 1, Qfalse );
 
 		this->socket_io = socket_io;
 	}
@@ -973,9 +980,9 @@ static VALUE pgconn_exec_params( int, VALUE *, VALUE );
  * and the PG::Result object will  automatically be cleared when the block terminates.
  * In this instance, <code>conn.exec</code> returns the value of the block.
  *
- * #exec is implemented on the synchronous command processing API of libpq, whereas
+ * #sync_exec is implemented on the synchronous command processing API of libpq, whereas
  * #async_exec is implemented on the asynchronous API.
- * #exec is somewhat faster that #async_exec, but blocks any signals to be processed until
+ * #sync_exec is somewhat faster that #async_exec, but blocks any signals to be processed until
  * the query is finished. This is most notably visible by a delayed reaction to Control+C.
  * Both methods ensure that other threads can process while waiting for the server to
  * complete the request.
@@ -987,8 +994,8 @@ pgconn_exec(int argc, VALUE *argv, VALUE self)
 	PGresult *result = NULL;
 	VALUE rb_pgresult;
 
-	/* If called with no parameters, use PQexec */
-	if ( argc == 1 ) {
+	/* If called with no or nil parameters, use PQexec for compatibility */
+	if ( argc == 1 || (argc >= 2 && argc <= 4 && NIL_P(argv[1]) )) {
 		VALUE query_str = argv[0];
 
 		result = gvl_PQexec(conn, pg_cstr_enc(query_str, ENCODING_GET(self)));
@@ -999,11 +1006,10 @@ pgconn_exec(int argc, VALUE *argv, VALUE self)
 		}
 		return rb_pgresult;
 	}
+	rb_warning("forwarding exec to exec_params is deprecated");
 
 	/* Otherwise, just call #exec_params instead for backward-compatibility */
-	else {
-		return pgconn_exec_params( argc, argv, self );
-	}
+	return pgconn_exec_params( argc, argv, self );
 
 }
 
@@ -1306,14 +1312,16 @@ pgconn_exec_params( int argc, VALUE *argv, VALUE self )
 	int resultFormat;
 	struct query_params_data paramsData = { ENCODING_GET(self) };
 
+	/* For compatibility we accept 1 to 4 parameters */
 	rb_scan_args(argc, argv, "13", &command, &paramsData.params, &in_res_fmt, &paramsData.typemap);
 	paramsData.with_types = 1;
 
 	/*
-	 * Handle the edge-case where the caller is coming from #exec, but passed an explict +nil+
-	 * for the second parameter.
+	 * For backward compatibility no or +nil+ for the second parameter
+	 * is passed to #exec
 	 */
 	if ( NIL_P(paramsData.params) ) {
+		rb_warning("forwarding exec_params to exec is deprecated");
 		return pgconn_exec( 1, argv, self );
 	}
 	pgconn_query_assign_typemap( self, &paramsData );
@@ -1812,15 +1820,54 @@ pgconn_set_single_row_mode(VALUE self)
 	return self;
 }
 
+static VALUE pgconn_send_query_params(int argc, VALUE *argv, VALUE self);
+
 /*
  * call-seq:
- *    conn.send_query(sql [, params, result_format[, type_map ]] ) -> nil
+ *    conn.send_query(sql) -> nil
  *
  * Sends SQL query request specified by _sql_ to PostgreSQL for
  * asynchronous processing, and immediately returns.
  * On failure, it raises a PG::Error.
  *
- * +params+ is an optional array of the bind parameters for the SQL query.
+ * For backward compatibility, if you pass more than one parameter to this method,
+ * it will call #send_query_params for you. New code should explicitly use #send_query_params if
+ * argument placeholders are used.
+ *
+ */
+static VALUE
+pgconn_send_query(int argc, VALUE *argv, VALUE self)
+{
+	PGconn *conn = pg_get_pgconn(self);
+	VALUE error;
+
+	/* If called with no or nil parameters, use PQexec for compatibility */
+	if ( argc == 1 || (argc >= 2 && argc <= 4 && NIL_P(argv[1]) )) {
+		if(gvl_PQsendQuery(conn, pg_cstr_enc(argv[0], ENCODING_GET(self))) == 0) {
+			error = rb_exc_new2(rb_eUnableToSend, PQerrorMessage(conn));
+			rb_iv_set(error, "@connection", self);
+			rb_exc_raise(error);
+		}
+		return Qnil;
+	}
+
+	rb_warning("forwarding async_exec to async_exec_params and send_query to send_query_params is deprecated");
+
+	/* If called with parameters, and optionally result_format,
+	 * use PQsendQueryParams
+	 */
+	return pgconn_send_query_params( argc, argv, self);
+}
+
+/*
+ * call-seq:
+ *    conn.send_query_params(sql, params [, result_format [, type_map ]] ) -> nil
+ *
+ * Sends SQL query request specified by _sql_ to PostgreSQL for
+ * asynchronous processing, and immediately returns.
+ * On failure, it raises a PG::Error.
+ *
+ * +params+ is an array of the bind parameters for the SQL query.
  * Each element of the +params+ array may be either:
  *   a hash of the form:
  *     {:value  => String (value of bind parameter)
@@ -1851,7 +1898,7 @@ pgconn_set_single_row_mode(VALUE self)
  *
  */
 static VALUE
-pgconn_send_query(int argc, VALUE *argv, VALUE self)
+pgconn_send_query_params(int argc, VALUE *argv, VALUE self)
 {
 	PGconn *conn = pg_get_pgconn(self);
 	int result;
@@ -1861,23 +1908,9 @@ pgconn_send_query(int argc, VALUE *argv, VALUE self)
 	int resultFormat;
 	struct query_params_data paramsData = { ENCODING_GET(self) };
 
-	rb_scan_args(argc, argv, "13", &command, &paramsData.params, &in_res_fmt, &paramsData.typemap);
+	rb_scan_args(argc, argv, "22", &command, &paramsData.params, &in_res_fmt, &paramsData.typemap);
 	paramsData.with_types = 1;
 
-	/* If called with no parameters, use PQsendQuery */
-	if(NIL_P(paramsData.params)) {
-		if(gvl_PQsendQuery(conn, pg_cstr_enc(command, paramsData.enc_idx)) == 0) {
-			error = rb_exc_new2(rb_eUnableToSend, PQerrorMessage(conn));
-			rb_iv_set(error, "@connection", self);
-			rb_exc_raise(error);
-		}
-		return Qnil;
-	}
-
-	/* If called with parameters, and optionally result_format,
-	 * use PQsendQueryParams
-	 */
-
 	pgconn_query_assign_typemap( self, &paramsData );
 	resultFormat = NIL_P(in_res_fmt) ? 0 : NUM2INT(in_res_fmt);
 	nParams = alloc_query_params( &paramsData );
@@ -2298,28 +2331,21 @@ pgconn_notifies(VALUE self)
 #if defined( _WIN32 )
 /*
  * On Windows, use platform-specific strategies to wait for the socket
- * instead of rb_thread_select().
+ * instead of rb_wait_for_single_fd().
  */
 
 int rb_w32_wait_events( HANDLE *events, int num, DWORD timeout );
 
-/* If WIN32 and Ruby 1.9 do not use rb_thread_select() which sometimes hangs
- * and does not wait (nor sleep) any time even if timeout is given.
- * Instead use the Winsock events and rb_w32_wait_events(). */
-
 static void *
-wait_socket_readable( PGconn *conn, struct timeval *ptimeout, void *(*is_readable)(PGconn *) )
+wait_socket_readable( t_pg_connection *this, struct timeval *ptimeout, void *(*is_readable)(PGconn *) )
 {
-	int sd = PQsocket( conn );
+	PGconn *conn = this->pgconn;
 	void *retval;
 	struct timeval aborttime={0,0}, currtime, waittime;
 	DWORD timeout_milisec = INFINITE;
 	DWORD wait_ret;
 	WSAEVENT hEvent;
 
-	if ( sd < 0 )
-		rb_raise(rb_eConnectionBad, "PQsocket() can't get socket descriptor");
-
 	hEvent = WSACreateEvent();
 
 	/* Check for connection errors (PQisBusy is true on connection errors) */
@@ -2334,7 +2360,7 @@ wait_socket_readable( PGconn *conn, struct timeval *ptimeout, void *(*is_readabl
 	}
 
 	while ( !(retval=is_readable(conn)) ) {
-		if ( WSAEventSelect(sd, hEvent, FD_READ|FD_CLOSE) == SOCKET_ERROR ) {
+		if ( WSAEventSelect(this->socket, hEvent, FD_READ|FD_CLOSE) == SOCKET_ERROR ) {
 			WSACloseEvent( hEvent );
 			rb_raise( rb_eConnectionBad, "WSAEventSelect socket error: %d", WSAGetLastError() );
 		}
@@ -2386,32 +2412,23 @@ wait_socket_readable( PGconn *conn, struct timeval *ptimeout, void *(*is_readabl
 /* non Win32 */
 
 static void *
-wait_socket_readable( PGconn *conn, struct timeval *ptimeout, void *(*is_readable)(PGconn *))
+wait_socket_readable( t_pg_connection *this, struct timeval *ptimeout, void *(*is_readable)(PGconn *))
 {
-	int sd = PQsocket( conn );
+	PGconn *conn = this->pgconn;
 	int ret;
 	void *retval;
-	rb_fdset_t sd_rset;
 	struct timeval aborttime={0,0}, currtime, waittime;
 
-	if ( sd < 0 )
-		rb_raise(rb_eConnectionBad, "PQsocket() can't get socket descriptor");
-
 	/* Check for connection errors (PQisBusy is true on connection errors) */
 	if ( PQconsumeInput(conn) == 0 )
 		rb_raise( rb_eConnectionBad, "PQconsumeInput() %s", PQerrorMessage(conn) );
 
-	rb_fd_init( &sd_rset );
-
 	if ( ptimeout ) {
 		gettimeofday(&currtime, NULL);
 		timeradd(&currtime, ptimeout, &aborttime);
 	}
 
 	while ( !(retval=is_readable(conn)) ) {
-		rb_fd_zero( &sd_rset );
-		rb_fd_set( sd, &sd_rset );
-
 		if ( ptimeout ) {
 			gettimeofday(&currtime, NULL);
 			timersub(&aborttime, &currtime, &waittime);
@@ -2420,30 +2437,26 @@ wait_socket_readable( PGconn *conn, struct timeval *ptimeout, void *(*is_readabl
 		/* Is the given timeout valid? */
 		if( !ptimeout || (waittime.tv_sec >= 0 && waittime.tv_usec >= 0) ){
 			/* Wait for the socket to become readable before checking again */
-			ret = rb_thread_fd_select( sd+1, &sd_rset, NULL, NULL, ptimeout ? &waittime : NULL );
+			ret = rb_wait_for_single_fd( this->socket, RB_WAITFD_IN, ptimeout ? &waittime : NULL );
 		} else {
 			ret = 0;
 		}
 
 		if ( ret < 0 ){
-			rb_fd_term( &sd_rset );
-			rb_sys_fail( "rb_thread_select()" );
+			rb_sys_fail( "rb_wait_for_single_fd()" );
 		}
 
 		/* Return false if the select() timed out */
 		if ( ret == 0 ){
-			rb_fd_term( &sd_rset );
 			return NULL;
 		}
 
 		/* Check for connection errors (PQisBusy is true on connection errors) */
 		if ( PQconsumeInput(conn) == 0 ){
-			rb_fd_term( &sd_rset );
 			rb_raise( rb_eConnectionBad, "PQconsumeInput() %s", PQerrorMessage(conn) );
 		}
 	}
 
-	rb_fd_term( &sd_rset );
 	return retval;
 }
 
@@ -2458,27 +2471,20 @@ notify_readable(PGconn *conn)
 
 /*
  * call-seq:
- *    conn.wait_for_notify( [ timeout ] ) -> String
- *    conn.wait_for_notify( [ timeout ] ) { |event, pid| block }
- *    conn.wait_for_notify( [ timeout ] ) { |event, pid, payload| block } # PostgreSQL 9.0
+ *    conn.wait_for_notify( [ timeout ] ) { |event, pid, payload| block } -> String
  *
  * Blocks while waiting for notification(s), or until the optional
  * _timeout_ is reached, whichever comes first.  _timeout_ is
  * measured in seconds and can be fractional.
  *
- * Returns +nil+ if _timeout_ is reached, the name of the NOTIFY
- * event otherwise.  If used in block form, passes the name of the
- * NOTIFY +event+ and the generating +pid+ into the block.
- *
- * Under PostgreSQL 9.0 and later, if the notification is sent with
- * the optional +payload+ string, it will be given to the block as the
- * third argument.
- *
+ * Returns +nil+ if _timeout_ is reached, the name of the NOTIFY event otherwise.
+ * If used in block form, passes the name of the NOTIFY +event+, the generating
+ * +pid+ and the optional +payload+ string into the block.
  */
 static VALUE
 pgconn_wait_for_notify(int argc, VALUE *argv, VALUE self)
 {
-	PGconn *conn = pg_get_pgconn( self );
+	t_pg_connection *this = pg_get_connection_safe( self );
 	PGnotify *pnotification;
 	struct timeval timeout;
 	struct timeval *ptimeout = NULL;
@@ -2494,7 +2500,7 @@ pgconn_wait_for_notify(int argc, VALUE *argv, VALUE self)
 		ptimeout = &timeout;
 	}
 
-	pnotification = (PGnotify*) wait_socket_readable( conn, ptimeout, notify_readable);
+	pnotification = (PGnotify*) wait_socket_readable( this, ptimeout, notify_readable);
 
 	/* Return nil if the select timed out */
 	if ( !pnotification ) return Qnil;
@@ -2632,16 +2638,18 @@ pgconn_put_copy_end(int argc, VALUE *argv, VALUE self)
 
 /*
  * call-seq:
- *    conn.get_copy_data( [ async = false [, decoder = nil ]] ) -> String
+ *    conn.get_copy_data( [ async = false [, decoder = nil ]] ) -> Object
  *
- * Return a string containing one row of data, +nil+
+ * Return one row of data, +nil+
  * if the copy is done, or +false+ if the call would
  * block (only possible if _async_ is true).
  *
- * _decoder_ can be a PG::Coder derivation (typically PG::TextDecoder::CopyRow).
- * This decodes the received data fields from PostgreSQL's COPY text format to an
- * Array of Strings. Optionally
- * the decoder can type cast the fields to various Ruby types in one step,
+ * If _decoder_ is not set or +nil+, data is returned as binary string.
+ *
+ * If _decoder_ is set to a PG::Coder derivation, the return type depends on this decoder.
+ * PG::TextDecoder::CopyRow decodes the received data fields from one row of PostgreSQL's
+ * COPY text format to an Array of Strings.
+ * Optionally the decoder can type cast the single fields to various Ruby types in one step,
  * if PG::TextDecoder::CopyRow#type_map is set accordingly.
  *
  * See also #copy_data.
@@ -3070,11 +3078,7 @@ get_result_readable(PGconn *conn)
  */
 static VALUE
 pgconn_block( int argc, VALUE *argv, VALUE self ) {
-	PGconn *conn = pg_get_pgconn( self );
-
-	/* If WIN32 and Ruby 1.9 do not use rb_thread_select() which sometimes hangs
-	 * and does not wait (nor sleep) any time even if timeout is given.
-	 * Instead use the Winsock events and rb_w32_wait_events(). */
+	t_pg_connection *this = pg_get_connection_safe( self );
 
 	struct timeval timeout;
 	struct timeval *ptimeout = NULL;
@@ -3089,7 +3093,7 @@ pgconn_block( int argc, VALUE *argv, VALUE self ) {
 		ptimeout = &timeout;
 	}
 
-	ret = wait_socket_readable( conn, ptimeout, get_result_readable);
+	ret = wait_socket_readable( this, ptimeout, get_result_readable);
 
 	if( !ret )
 		return Qfalse;
@@ -3142,24 +3146,186 @@ pgconn_get_last_result(VALUE self)
 
 /*
  * call-seq:
- *    conn.async_exec(sql [, params, result_format ] ) -> PG::Result
- *    conn.async_exec(sql [, params, result_format ] ) {|pg_result| block }
+ *    conn.discard_results()
+ *
+ * Silently discard any prior query result that application didn't eat.
+ * This is done prior of Connection#exec and sibling methods and can
+ * be called explicitly when using the async API.
+ */
+static VALUE
+pgconn_discard_results(VALUE self)
+{
+	PGconn *conn = pg_get_pgconn(self);
+
+	PGresult *cur;
+	while ((cur = gvl_PQgetResult(conn)) != NULL) {
+		int status = PQresultStatus(cur);
+		PQclear(cur);
+		if (status == PGRES_COPY_IN){
+			gvl_PQputCopyEnd(conn, "COPY terminated by new PQexec");
+		}
+		if (status == PGRES_COPY_OUT){
+			char *buffer = NULL;
+			while( gvl_PQgetCopyData(conn, &buffer, 0) > 0)
+				PQfreemem(buffer);
+		}
+	}
+
+	return Qnil;
+}
+
+/*
+ * call-seq:
+ *    conn.async_exec(sql) -> PG::Result
+ *    conn.async_exec(sql) {|pg_result| block }
  *
- * This function has the same behavior as #exec,
+ * This function has the same behavior as #sync_exec,
  * but is implemented using the asynchronous command
  * processing API of libpq.
+ *
+ * Both #sync_exec and #async_exec release the GVL while waiting for server response, so that concurrent threads will get executed.
+ * However #async_exec has two advantages:
+ *
+ * 1. #async_exec can be aborted by signals (like Ctrl-C), while #exec blocks signal processing until the query is answered.
+ * 2. Ruby VM gets notified about IO blocked operations.
+ *    It can therefore schedule thing like garbage collection, while queries are running like in this proposal: https://bugs.ruby-lang.org/issues/14723
  */
 static VALUE
 pgconn_async_exec(int argc, VALUE *argv, VALUE self)
 {
 	VALUE rb_pgresult = Qnil;
 
-	/* remove any remaining results from the queue */
+	pgconn_discard_results( self );
+	pgconn_send_query( argc, argv, self );
 	pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
-	pgconn_get_last_result( self );
+	rb_pgresult = pgconn_get_last_result( self );
 
-	pgconn_send_query( argc, argv, self );
-	pgconn_block( 0, NULL, self );
+	if ( rb_block_given_p() ) {
+		return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
+	}
+	return rb_pgresult;
+}
+
+
+/*
+ * call-seq:
+ *    conn.async_exec_params(sql, params [, result_format [, type_map ]] ) -> nil
+ *    conn.async_exec_params(sql, params [, result_format [, type_map ]] ) {|pg_result| block }
+ *
+ * This function has the same behavior as #sync_exec_params, but is implemented using the asynchronous command processing API of libpq.
+ * See #async_exec for the differences between the two API variants.
+ */
+static VALUE
+pgconn_async_exec_params(int argc, VALUE *argv, VALUE self)
+{
+	VALUE rb_pgresult = Qnil;
+
+	pgconn_discard_results( self );
+	/* If called with no or nil parameters, use PQsendQuery for compatibility */
+	if ( argc == 1 || (argc >= 2 && argc <= 4 && NIL_P(argv[1]) )) {
+		rb_warning("forwarding async_exec_params to async_exec is deprecated");
+		pgconn_send_query( argc, argv, self );
+	} else {
+		pgconn_send_query_params( argc, argv, self );
+	}
+	pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
+	rb_pgresult = pgconn_get_last_result( self );
+
+	if ( rb_block_given_p() ) {
+		return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
+	}
+	return rb_pgresult;
+}
+
+
+/*
+ * call-seq:
+ *    conn.async_prepare(stmt_name, sql [, param_types ] ) -> PG::Result
+ *
+ * This function has the same behavior as #sync_prepare, but is implemented using the asynchronous command processing API of libpq.
+ * See #async_exec for the differences between the two API variants.
+ */
+static VALUE
+pgconn_async_prepare(int argc, VALUE *argv, VALUE self)
+{
+	VALUE rb_pgresult = Qnil;
+
+	pgconn_discard_results( self );
+	pgconn_send_prepare( argc, argv, self );
+	pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
+	rb_pgresult = pgconn_get_last_result( self );
+
+	if ( rb_block_given_p() ) {
+		return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
+	}
+	return rb_pgresult;
+}
+
+
+/*
+ * call-seq:
+ *    conn.async_exec_prepared(statement_name [, params, result_format[, type_map]] ) -> PG::Result
+ *    conn.async_exec_prepared(statement_name [, params, result_format[, type_map]] ) {|pg_result| block }
+ *
+ * This function has the same behavior as #sync_exec_prepared, but is implemented using the asynchronous command processing API of libpq.
+ * See #async_exec for the differences between the two API variants.
+ */
+static VALUE
+pgconn_async_exec_prepared(int argc, VALUE *argv, VALUE self)
+{
+	VALUE rb_pgresult = Qnil;
+
+	pgconn_discard_results( self );
+	pgconn_send_query_prepared( argc, argv, self );
+	pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
+	rb_pgresult = pgconn_get_last_result( self );
+
+	if ( rb_block_given_p() ) {
+		return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
+	}
+	return rb_pgresult;
+}
+
+
+/*
+ * call-seq:
+ *    conn.async_describe_portal( portal_name ) -> PG::Result
+ *
+ * This function has the same behavior as #sync_describe_portal, but is implemented using the asynchronous command processing API of libpq.
+ * See #async_exec for the differences between the two API variants.
+ */
+static VALUE
+pgconn_async_describe_portal(VALUE self, VALUE portal)
+{
+	VALUE rb_pgresult = Qnil;
+
+	pgconn_discard_results( self );
+	pgconn_send_describe_portal( self, portal );
+	pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
+	rb_pgresult = pgconn_get_last_result( self );
+
+	if ( rb_block_given_p() ) {
+		return rb_ensure( rb_yield, rb_pgresult, pg_result_clear, rb_pgresult );
+	}
+	return rb_pgresult;
+}
+
+
+/*
+ * call-seq:
+ *    conn.async_describe_prepared( statement_name ) -> PG::Result
+ *
+ * This function has the same behavior as #sync_describe_prepared, but is implemented using the asynchronous command processing API of libpq.
+ * See #async_exec for the differences between the two API variants.
+ */
+static VALUE
+pgconn_async_describe_prepared(VALUE self, VALUE stmt_name)
+{
+	VALUE rb_pgresult = Qnil;
+
+	pgconn_discard_results( self );
+	pgconn_send_describe_prepared( self, stmt_name );
+	pgconn_block( 0, NULL, self ); /* wait for input (without blocking) before reading the last result */
 	rb_pgresult = pgconn_get_last_result( self );
 
 	if ( rb_block_given_p() ) {
@@ -3690,7 +3856,7 @@ pgconn_set_default_encoding( VALUE self )
 	if (( enc = rb_default_internal_encoding() )) {
 		encname = pg_get_rb_encoding_as_pg_encoding( enc );
 		if ( pgconn_set_client_encoding_async(self, encname) != 0 )
-			rb_warn( "Failed to set the default_internal encoding to %s: '%s'",
+			rb_warning( "Failed to set the default_internal encoding to %s: '%s'",
 			         encname, PQerrorMessage(conn) );
 		pgconn_set_internal_encoding_index( self );
 		return rb_enc_from_encoding( enc );
@@ -3879,6 +4045,20 @@ pgconn_decoder_for_get_copy_data_get(VALUE self)
 	return this->decoder_for_get_copy_data;
 }
 
+/*
+ * call-seq:
+ *    res.guess_result_memsize = enabled
+ *
+ * This method is for testing only and will probably be removed in the future.
+ */
+static VALUE
+pgconn_guess_result_memsize_set(VALUE self, VALUE enable)
+{
+	t_pg_connection *this = pg_get_connection( self );
+	this->guess_result_memsize = RTEST(enable);
+	return enable;
+}
+
 
 /*
  * Document-class: PG::Connection
@@ -3946,13 +4126,12 @@ init_pg_connection()
 	/* rb_define_method(rb_cPGconn, "getssl", pgconn_getssl, 0); */
 
 	/******     PG::Connection INSTANCE METHODS: Command Execution     ******/
-	rb_define_method(rb_cPGconn, "exec", pgconn_exec, -1);
-	rb_define_alias(rb_cPGconn, "query", "exec");
-	rb_define_method(rb_cPGconn, "exec_params", pgconn_exec_params, -1);
-	rb_define_method(rb_cPGconn, "prepare", pgconn_prepare, -1);
-	rb_define_method(rb_cPGconn, "exec_prepared", pgconn_exec_prepared, -1);
-	rb_define_method(rb_cPGconn, "describe_prepared", pgconn_describe_prepared, 1);
-	rb_define_method(rb_cPGconn, "describe_portal", pgconn_describe_portal, 1);
+	rb_define_method(rb_cPGconn, "sync_exec", pgconn_exec, -1);
+	rb_define_method(rb_cPGconn, "sync_exec_params", pgconn_exec_params, -1);
+	rb_define_method(rb_cPGconn, "sync_prepare", pgconn_prepare, -1);
+	rb_define_method(rb_cPGconn, "sync_exec_prepared", pgconn_exec_prepared, -1);
+	rb_define_method(rb_cPGconn, "sync_describe_prepared", pgconn_describe_prepared, 1);
+	rb_define_method(rb_cPGconn, "sync_describe_portal", pgconn_describe_portal, 1);
 	rb_define_method(rb_cPGconn, "make_empty_pgresult", pgconn_make_empty_pgresult, 1);
 	rb_define_method(rb_cPGconn, "escape_string", pgconn_s_escape, 1);
 	rb_define_alias(rb_cPGconn, "escape", "escape_string");
@@ -3964,10 +4143,18 @@ init_pg_connection()
 
 	/******     PG::Connection INSTANCE METHODS: Asynchronous Command Processing     ******/
 	rb_define_method(rb_cPGconn, "send_query", pgconn_send_query, -1);
+	rb_define_method(rb_cPGconn, "send_query_params", pgconn_send_query_params, -1);
+	rb_define_method(rb_cPGconn, "async_exec", pgconn_async_exec, -1);
+	rb_define_method(rb_cPGconn, "async_exec_params", pgconn_async_exec_params, -1);
+	rb_define_alias(rb_cPGconn, "async_query", "async_exec");
 	rb_define_method(rb_cPGconn, "send_prepare", pgconn_send_prepare, -1);
+	rb_define_method(rb_cPGconn, "async_prepare", pgconn_async_prepare, -1);
 	rb_define_method(rb_cPGconn, "send_query_prepared", pgconn_send_query_prepared, -1);
+	rb_define_method(rb_cPGconn, "async_exec_prepared", pgconn_async_exec_prepared, -1);
 	rb_define_method(rb_cPGconn, "send_describe_prepared", pgconn_send_describe_prepared, 1);
+	rb_define_method(rb_cPGconn, "async_describe_prepared", pgconn_async_describe_prepared, 1);
 	rb_define_method(rb_cPGconn, "send_describe_portal", pgconn_send_describe_portal, 1);
+	rb_define_method(rb_cPGconn, "async_describe_portal", pgconn_async_describe_portal, 1);
 	rb_define_method(rb_cPGconn, "get_result", pgconn_get_result, 0);
 	rb_define_method(rb_cPGconn, "consume_input", pgconn_consume_input, 0);
 	rb_define_method(rb_cPGconn, "is_busy", pgconn_is_busy, 0);
@@ -3975,6 +4162,7 @@ init_pg_connection()
 	rb_define_method(rb_cPGconn, "isnonblocking", pgconn_isnonblocking, 0);
 	rb_define_alias(rb_cPGconn, "nonblocking?", "isnonblocking");
 	rb_define_method(rb_cPGconn, "flush", pgconn_flush, 0);
+	rb_define_method(rb_cPGconn, "discard_results", pgconn_discard_results, 0);
 
 	/******     PG::Connection INSTANCE METHODS: Cancelling Queries in Progress     ******/
 	rb_define_method(rb_cPGconn, "cancel", pgconn_cancel, 0);
@@ -3991,6 +4179,7 @@ init_pg_connection()
 	rb_define_method(rb_cPGconn, "set_error_verbosity", pgconn_set_error_verbosity, 1);
 	rb_define_method(rb_cPGconn, "trace", pgconn_trace, 1);
 	rb_define_method(rb_cPGconn, "untrace", pgconn_untrace, 0);
+	rb_define_method(rb_cPGconn, "guess_result_memsize=", pgconn_guess_result_memsize_set, 1);
 
 	/******     PG::Connection INSTANCE METHODS: Notice Processing     ******/
 	rb_define_method(rb_cPGconn, "set_notice_receiver", pgconn_set_notice_receiver, 0);
@@ -4005,8 +4194,6 @@ init_pg_connection()
 	rb_define_method(rb_cPGconn, "wait_for_notify", pgconn_wait_for_notify, -1);
 	rb_define_alias(rb_cPGconn, "notifies_wait", "wait_for_notify");
 	rb_define_method(rb_cPGconn, "quote_ident", pgconn_s_quote_ident, 1);
-	rb_define_method(rb_cPGconn, "async_exec", pgconn_async_exec, -1);
-	rb_define_alias(rb_cPGconn, "async_query", "async_exec");
 	rb_define_method(rb_cPGconn, "get_last_result", pgconn_get_last_result, 0);
 #ifdef HAVE_PQENCRYPTPASSWORDCONN
 	rb_define_method(rb_cPGconn, "encrypt_password", pgconn_encrypt_password, -1);