123456789_123456789_123456789_123456789_123456789_

Class: PG::CancelConnection

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, Connection::Pollable, Enumerable
Inherits: Object
Defined in: ext/pg_cancel_connection.c,
ext/pg_cancel_connection.c,
lib/pg/cancel_connection.rb

Overview

The class to represent a connection to cancel a query.

On PostgreSQL-17+ client libaray this class is used to implement Connection#cancel . It works on older PostgreSQL server versions too.

Available since PostgreSQL-17

Class Method Summary

Instance Attribute Summary

Instance Method Summary

  • #async_cancel

    Alias for #cancel.

  • #cancel (also: #async_cancel)

    Requests that the server abandons processing of the current command in a blocking manner.

  • #error_message ⇒ String

    Returns the error message most recently generated by an operation on the cancel connection.

  • #finish ⇒ nil

    Closes the cancel connection (if it did not finish sending the cancel request yet).

  • #poll ⇒ Integer

    This is to poll libpq so that it can proceed with the cancel connection sequence.

  • #reset ⇒ nil

    Resets the CancelConnection so it can be reused for a new cancel connection.

  • #socket_io ⇒ IO

    Fetch an IO object created from the CancelConnection’s underlying socket.

  • #start ⇒ nil

    Requests that the server abandons processing of the current command in a non-blocking manner.

  • #status ⇒ Integer

    Returns the status of the cancel connection.

  • #sync_cancel ⇒ nil

    Requests that the server abandons processing of the current command in a blocking manner.

Connection::Pollable - Included

#polling_loop

Track the progress of the connection, waiting for the socket to become readable/writable before polling it.

Constructor Details

.new(conn) ⇒ Object

Prepares a connection over which a cancel request can be sent.

Creates a CancelConnection from a 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 CancelConnection object was connected successfully. This 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.

[ GitHub ] 

  


# File 'ext/pg_cancel_connection.c', line 139



VALUE
pg_cancon_initialize(VALUE self, VALUE rb_conn)
{
	t_pg_cancon *this = pg_cancon_get_this(self);
	PGconn *conn = pg_get_pgconn(rb_conn);

	this->pg_cancon = PQcancelCreate(conn);
	if (this->pg_cancon == NULL)
		pg_raise_conn_error( rb_eConnectionBad, self, "PQcancelCreate failed");

	return self;
}


  







Instance Attribute Details



  

    #async_connect_timeout   (rw)
  



  

    

The timeout used by #cancel and async_cancel to establish the cancel connection.


  



  [ GitHub ]


  

  


# File 'lib/pg/cancel_connection.rb', line 11



attr_accessor :async_connect_timeout


  







Instance Method Details



  

    #async_cancel  
  



  

    

Alias for #cancel.


  



  [ GitHub ]


  

  


# File 'lib/pg/cancel_connection.rb', line 28



alias async_cancel cancel


  








  

    #cancel      Also known as: #async_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.


  



  [ GitHub ]


  

  


# File 'lib/pg/cancel_connection.rb', line 24



def cancel
	start
	polling_loop(:poll, async_connect_timeout)
end


  








  

    #error_message  ⇒ String   



  

    

Returns the error message most recently generated by an operation on the cancel connection.



Nearly all 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.


  



  [ GitHub ]


  

  


# File 'ext/pg_cancel_connection.c', line 204



static VALUE
pg_cancon_error_message(VALUE self)
{
	PGcancelConn *conn = pg_cancon_get_conn(self);
	char *p_err;

	p_err = PQcancelErrorMessage(conn);

	return p_err ? rb_str_new_cstr(p_err) : Qnil;
}


  








  

    #finish  ⇒ nil   



  

    

Closes the cancel connection (if it did not finish sending the cancel request yet). Also frees memory used by the CancelConnection object.


  



  [ GitHub ]


  

  


# File 'ext/pg_cancel_connection.c', line 326



static VALUE
pg_cancon_finish(VALUE self)
{
	t_pg_cancon *this = pg_cancon_get_this( self );

	pg_cancon_close_socket_io( self );
	if( this->pg_cancon )
		PQcancelFinish(this->pg_cancon);
	this->pg_cancon = NULL;

	return Qnil;
}


  








  

    #poll  ⇒ Integer   



  

    

This is to poll libpq so that it can proceed with the cancel connection sequence.



The behavior is the same like Connection#connect_poll .



See also corresponding libpq function


  



  [ GitHub ]


  

  


# File 'ext/pg_cancel_connection.c', line 226



static VALUE
pg_cancon_poll(VALUE self)
{
	PostgresPollingStatusType status;
	PGcancelConn *conn = pg_cancon_get_conn(self);

	pg_cancon_close_socket_io( self );
	status = gvl_PQcancelPoll(conn);

	return INT2FIX((int)status);
}


  








  

    #reset  ⇒ nil   



  

    

Resets the CancelConnection so it can be reused for a new cancel connection.



If the CancelConnection is currently used to send a cancel request, then this connection is closed. It will then prepare the CancelConnection object such that it can be used to send a new cancel request.



This can be used to create one CancelConnection for a Connection and reuse it multiple times throughout the lifetime of the original Connection.


  



  [ GitHub ]


  

  


# File 'ext/pg_cancel_connection.c', line 308



static VALUE
pg_cancon_reset(VALUE self)
{
	PGcancelConn *conn = pg_cancon_get_conn(self);

	pg_cancon_close_socket_io( self );
	PQcancelReset(conn);

	return Qnil;
}


  








  

    #socket_io  ⇒ IO   



  

    

Fetch an IO object created from the CancelConnection’s underlying socket. This object can be used per socket_io.wait_readable, socket_io.wait_writable or for IO.select to wait for events while running asynchronous API calls. IO#wait_*able is Fiber.scheduler compatible in contrast to IO.select.



The IO object can change while the connection is established. So be sure not to cache the IO object, but repeat calling conn.socket_io instead.


  



  [ GitHub ]


  

  


# File 'ext/pg_cancel_connection.c', line 281



static VALUE
pg_cancon_socket_io(VALUE self)
{
	t_pg_cancon *this = pg_cancon_get_this( self );

	if ( !RTEST(this->socket_io) ) {
		int sd;
		if( (sd = PQcancelSocket(this->pg_cancon)) < 0){
			pg_raise_conn_error( rb_eConnectionBad, self, "PQcancelSocket() can't get socket descriptor");
		}
		return pg_wrap_socket_io( sd, self, &this->socket_io, &this->ruby_sd);
	}

	return this->socket_io;
}


  








  

    #start  ⇒ nil   



  

    

Requests that the server abandons processing of the current command in a non-blocking manner.



The behavior is the same like Connection.connect_start .



Use #poll to poll the status of the connection.


  



  [ GitHub ]


  

  


# File 'ext/pg_cancel_connection.c', line 184



static VALUE
pg_cancon_start(VALUE self)
{
	PGcancelConn *conn = pg_cancon_get_conn(self);

	pg_cancon_close_socket_io( self );
	if(gvl_PQcancelStart(conn) == 0)
		pg_raise_conn_error( rb_eConnectionBad, self, "PQcancelStart %s", PQcancelErrorMessage(conn));
	return Qnil;
}


  








  

    #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 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.


  



  [ GitHub ]


  

  


# File 'ext/pg_cancel_connection.c', line 259



static VALUE
pg_cancon_status(VALUE self)
{
	ConnStatusType status;
	PGcancelConn *conn = pg_cancon_get_conn(self);

	status = PQcancelStatus(conn);

	return INT2NUM(status);
}


  








  

    #sync_cancel  ⇒ nil   



  

    

Requests that the server abandons processing of the current command in a blocking manner.



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.


  



  [ GitHub ]


  

  


# File 'ext/pg_cancel_connection.c', line 162



static VALUE
pg_cancon_sync_cancel(VALUE self)
{
	PGcancelConn *conn = pg_cancon_get_conn(self);

	pg_cancon_close_socket_io( self );
	if(gvl_PQcancelBlocking(conn) == 0)
		pg_raise_conn_error( rb_eConnectionBad, self, "PQcancelBlocking %s", PQcancelErrorMessage(conn));
	return Qnil;
}