Add documentation to PG::CancelConnection

ext/pg_cancel_connection.c

@@ -5,7 +5,11 @@
  * Document-class: PG::CancelConnection
  *
  * The class to represent a connection to cancel a query.
- * An instance of this class can be created by PG::Connection#cancel .
+ *
+ * On PostgreSQL-17+ client libaray this class is used to implement PG::Connection#cancel .
+ * It works on older PostgreSQL server versions too.
+ *
+ * Available since PostgreSQL-17
  *
  */
 
@@ -25,9 +29,6 @@ typedef struct {
 } t_pg_cancon;
 
 
-/*
- * GC Mark function
- */
 static void
 pg_cancon_gc_mark( void *_this )
 {
@@ -81,7 +82,7 @@ static const rb_data_type_t pg_cancon_type = {
  * Document-method: allocate
  *
  * call-seq:
- *   PG::VeryTuple.allocate -> obj
+ *   PG::CancelConnection.allocate -> obj
  */
 static VALUE
 pg_cancon_s_allocate( VALUE klass )
@@ -119,6 +120,22 @@ pg_cancon_close_socket_io( VALUE self )
 	pg_unwrap_socket_io( self, &this->socket_io, this->ruby_sd);
 }
 
+/*
+ * call-seq:
+ *    PG::CancelConnection.new(conn) -> obj
+ *
+ * Prepares a connection over which a cancel request can be sent.
+ *
+ * Creates a PG::CancelConnection from a PG::Connection object, but it won't instantly start sending a cancel request over this connection.
+ * A cancel request can be sent over this connection in a blocking manner using #cancel and in a non-blocking manner using #start.
+ * #status can be used to check if the PG::CancelConnection object was connected successfully.
+ * This PG::CancelConnection object can be used to cancel the query that's running on the original connection in a thread-safe way.
+ *
+ * Many connection parameters of the original client will be reused when setting up the connection for the cancel request.
+ * Importantly, if the original connection requires encryption of the connection and/or verification of the target host (using sslmode or gssencmode), then the connection for the cancel request is made with these same requirements.
+ * Any connection options that are only used during authentication or after authentication of the client are ignored though, because cancellation requests do not require authentication and the connection is closed right after the cancellation request is submitted.
+ *
+ */
 VALUE
 pg_cancon_initialize(VALUE self, VALUE rb_conn)
 {
@@ -138,11 +155,8 @@ pg_cancon_initialize(VALUE self, VALUE rb_conn)
  *
  * Requests that the server abandons processing of the current command in a blocking manner.
  *
- * If the cancel request wasn't successfully dispatched an error message is raised.
- *
- * Successful dispatch of the cancellation is no guarantee that the request will have any effect, however.
- * If the cancellation is effective, the command being canceled will terminate early and raises an error.
- * If the cancellation fails (say, because the server was already done processing the command), then there will be no visible result at all.
+ * This method directly calls +PQcancelBlocking+ of libpq, so that it doesn't respond to ruby interrupts and doesn't trigger the +Thread.scheduler+ .
+ * It is threrfore recommended to call #cancel instead.
  *
  */
 static VALUE
@@ -160,6 +174,12 @@ pg_cancon_sync_cancel(VALUE self)
  * call-seq:
  *    conn.start -> nil
  *
+ * Requests that the server abandons processing of the current command in a non-blocking manner.
+ *
+ * The behavior is the same like PG::Connection.connect_start .
+ *
+ * Use #poll to poll the status of the connection.
+ *
  */
 static VALUE
 pg_cancon_start(VALUE self)
@@ -176,6 +196,10 @@ pg_cancon_start(VALUE self)
  * call-seq:
  *    conn.error_message -> String
  *
+ * Returns the error message most recently generated by an operation on the cancel connection.
+ *
+ * Nearly all PG::CancelConnection functions will set a message if they fail.
+ * Note that by libpq convention, a nonempty error_message result can consist of multiple lines, and will include a trailing newline.
  */
 static VALUE
 pg_cancon_error_message(VALUE self)
@@ -190,7 +214,13 @@ pg_cancon_error_message(VALUE self)
 
 /*
  * call-seq:
- *    conn.poll -> nil
+ *    conn.poll -> Integer
+ *
+ * This is to poll libpq so that it can proceed with the cancel connection sequence.
+ *
+ * The behavior is the same like PG::Connection#connect_poll .
+ *
+ * See also corresponding {libpq function}[https://www.postgresql.org/docs/current/libpq-cancel.html#LIBPQ-PQCANCELSTART]
  *
  */
 static VALUE
@@ -207,7 +237,23 @@ pg_cancon_poll(VALUE self)
 
 /*
  * call-seq:
- *    conn.status -> nil
+ *    conn.status -> Integer
+ *
+ * Returns the status of the cancel connection.
+ *
+ * The status can be one of a number of values.
+ * However, only three of these are seen outside of an asynchronous cancel procedure:
+ * +CONNECTION_ALLOCATED+, +CONNECTION_OK+ and +CONNECTION_BAD+.
+ * The initial state of a PG::CancelConnection that's successfully created is +CONNECTION_ALLOCATED+.
+ * A cancel request that was successfully dispatched has the status +CONNECTION_OK+.
+ * A failed cancel attempt is signaled by status +CONNECTION_BAD+.
+ * An OK status will remain so until #finish or #reset is called.
+ *
+ * See #poll with regards to other status codes that might be returned.
+ *
+ * Successful dispatch of the cancellation is no guarantee that the request will have any effect, however.
+ * If the cancellation is effective, the command being canceled will terminate early and return an error result.
+ * If the cancellation fails (say, because the server was already done processing the command), then there will be no visible result at all.
  *
  */
 static VALUE
@@ -227,7 +273,7 @@ pg_cancon_status(VALUE self)
  *
  * Fetch an IO object created from the CancelConnection's underlying socket.
  * This object can be used per <tt>socket_io.wait_readable</tt>, <tt>socket_io.wait_writable</tt> or for <tt>IO.select</tt> to wait for events while running asynchronous API calls.
- * <tt>IO#wait_*able</tt> is is <tt>Fiber.scheduler</tt> compatible in contrast to <tt>IO.select</tt>.
+ * <tt>IO#wait_*able</tt> is <tt>Fiber.scheduler</tt> compatible in contrast to <tt>IO.select</tt>.
  *
  * The IO object can change while the connection is established.
  * So be sure not to cache the IO object, but repeat calling <tt>conn.socket_io</tt> instead.
@@ -252,6 +298,12 @@ pg_cancon_socket_io(VALUE self)
  * call-seq:
  *    conn.reset -> nil
  *
+ * Resets the PG::CancelConnection so it can be reused for a new cancel connection.
+ *
+ * If the PG::CancelConnection is currently used to send a cancel request, then this connection is closed.
+ * It will then prepare the PG::CancelConnection object such that it can be used to send a new cancel request.
+ *
+ * This can be used to create one PG::CancelConnection for a PG::Connection and reuse it multiple times throughout the lifetime of the original PG::Connection.
  */
 static VALUE
 pg_cancon_reset(VALUE self)
@@ -264,6 +316,13 @@ pg_cancon_reset(VALUE self)
 	return Qnil;
 }
 
+/*
+ * call-seq:
+ *    conn.finish -> nil
+ *
+ * Closes the cancel connection (if it did not finish sending the cancel request yet). Also frees memory used by the PG::CancelConnection object.
+ *
+ */
 static VALUE
 pg_cancon_finish(VALUE self)
 {

ext/pg_connection.c

@@ -608,7 +608,7 @@ pgconn_reset_start(VALUE self)
  *    conn.reset_poll -> Integer
  *
  * Checks the status of a connection reset operation.
- * See #connect_start and #connect_poll for
+ * See Connection.connect_start and #connect_poll for
  * usage information and return values.
  */
 static VALUE
@@ -953,7 +953,7 @@ pg_wrap_socket_io(int sd, VALUE self, VALUE *p_socket_io, int *p_ruby_sd)
  *
  * Fetch an IO object created from the Connection's underlying socket.
  * This object can be used per <tt>socket_io.wait_readable</tt>, <tt>socket_io.wait_writable</tt> or for <tt>IO.select</tt> to wait for events while running asynchronous API calls.
- * <tt>IO#wait_*able</tt> is is <tt>Fiber.scheduler</tt> compatible in contrast to <tt>IO.select</tt>.
+ * <tt>IO#wait_*able</tt> is <tt>Fiber.scheduler</tt> compatible in contrast to <tt>IO.select</tt>.
  *
  * The IO object can change while the connection is established, but is memorized afterwards.
  * So be sure not to cache the IO object, but repeat calling <tt>conn.socket_io</tt> instead.

ext/pg_tuple.c

@@ -135,7 +135,7 @@ static const rb_data_type_t pg_tuple_type = {
  * Document-method: allocate
  *
  * call-seq:
- *   PG::VeryTuple.allocate -> obj
+ *   PG::Tuple.allocate -> obj
  */
 static VALUE
 pg_tuple_s_allocate( VALUE klass )

lib/pg/cancel_connection.rb

@@ -7,12 +7,24 @@
 	class PG::CancelConnection
 		include PG::Connection::Pollable
 
-		# The timeout used by async_cancel to establish the cancel connection.
+		# The timeout used by #cancel and async_cancel to establish the cancel connection.
 		attr_accessor :async_connect_timeout
 
-		def async_cancel
+		# call-seq:
+		#    conn.cancel
+		#
+		# Requests that the server abandons processing of the current command in a blocking manner.
+		#
+		# If the cancel request wasn't successfully dispatched an error message is raised.
+		#
+		# Successful dispatch of the cancellation is no guarantee that the request will have any effect, however.
+		# If the cancellation is effective, the command being canceled will terminate early and raises an error.
+		# If the cancellation fails (say, because the server was already done processing the command), then there will be no visible result at all.
+		#
+		def cancel
 			start
 			polling_loop(:poll, async_connect_timeout)
 		end
+		alias async_cancel cancel
 	end
 end

lib/pg/connection.rb

@@ -620,6 +620,9 @@ def sync_cancel
 		#
 		# Returns +nil+ on success, or a string containing the
 		# error message if a failure occurs.
+		#
+		# On PostgreSQL-17+ client libaray the class PG::CancelConnection is used.
+		# On older client library a pure ruby implementation is used.
 		def cancel
 			cancon = PG::CancelConnection.new(self)
 			cancon.async_connect_timeout = conninfo_hash[:connect_timeout]