# class PG::CancelConnection

The class to represent a connection to cancel a query.

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

### Public Class Methods

PG::CancelConnection.new(conn) → obj click to toggle source

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)
    {
            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;
    }

new(conn) click to toggle source

    # File lib/pg/cancel_connection.rb, line 11
    def initialize(conn)
            c_initialize(conn)

            # A cancel connection is always to one destination server only.
            # Prepare conninfo_hash with just enough information to allow a shared polling_loop.
            @host = conn.host
            @hostaddr = conn.hostaddr
            @port = conn.port

            @conninfo_hash = {
                    host: @host,
                    hostaddr: @hostaddr,
                    port: @port.to_s,
                    connect_timeout: conn.conninfo_hash[:connect_timeout],
            }
    end

Also aliased as: c_initialize

### Public Instance Methods

cancel
Alias for: cancel
c_initialize(conn)
Alias for: new
cancel click to toggle source

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.

    # File lib/pg/cancel_connection.rb, line 39
    def cancel
            start
            polling_loop(:poll)
    end

Also aliased as: async_cancel
error_message → String click to toggle source

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)
    {
            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 click to toggle source

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)
    {
            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 click to toggle source

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

    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 click to toggle source

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)
    {
            PGcancelConn *conn = pg_cancon_get_conn(self);

            pg_cancon_close_socket_io( self );
            PQcancelReset(conn);

            return Qnil;
    }

socket_io() → IO click to toggle source

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.

    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 click to toggle source

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)
    {
            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 click to toggle source

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
    pg_cancon_status(VALUE self)
    {
            ConnStatusType status;
            PGcancelConn *conn = pg_cancon_get_conn(self);

            status = PQcancelStatus(conn);

            return INT2NUM(status);
    }

sync_cancel → nil click to toggle source

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.

    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;
    }