PG::
CancelConnection class
Superclass | rb_cObject |
Included Modules |
|
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
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.
Public Instance Methods
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.
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.
Closes the cancel connection (if it did not finish sending the cancel request yet). Also frees memory used by the PG::CancelConnection
object.
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
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
.
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.
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.
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.
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.