pqxx::connecting Class Reference

An ongoing, non-blocking stepping stone to a connection. More...

#include <connection.hxx>

Public Member Functions
	connecting (zview connection_string=""_zv)
	Start connecting. More...
	connecting (connecting const &)=delete
	connecting (connecting &&)=default
connecting &	operator= (connecting const &)=delete
connecting &	operator= (connecting &&)=default
int	sock () const &noexcept
	Get the socket. The socket may change during the connection process. More...
constexpr bool	wait_to_read () const &noexcept
	Should we currently wait to be able to read from the socket? More...
constexpr bool	wait_to_write () const &noexcept
	Should we currently wait to be able to write to the socket? More...
void	process () &
	Progress towards completion (but don't block). More...
constexpr bool	done () const &noexcept
	Is our connection finished? More...
connection	produce () &&
	Produce the completed connection object. More...

Detailed Description

An ongoing, non-blocking stepping stone to a connection.

Use this when you want to create a connection to the database, but without blocking your whole thread. It is only available on systems that have the <fcntl.h> header, and Windows.

Connecting in this way is probably not "faster" (it's more complicated and has some extra overhead), but in some situations you can use it to make your application as a whole faster. It all depends on having other useful work to do in the same thread, and being able to wait on a socket. If you have other I/O going on at the same time, your event loop can wait for both the libpqxx socket and your own sockets, and wake up whenever any of them is ready to do work.

Connecting in this way is not properly "asynchronous;" it's merely "nonblocking." This means it's not a super-high-performance mechanism like you might get with e.g. io_uring. In particular, if we need to look up the database hostname in DNS, that will happen synchronously.

To use this, create the connecting object, passing a connection string. Then loop: If wait_to_read returns true, wait for the socket to have incoming data on it. If wait_to_write returns true, wait for the socket to be ready for writing. Then call process to process any incoming or outgoing data. Do all of this until done returns true (or there is an exception). Finally, call produce to get the completed connection.

For example:

pqxx::connecting cg{};
 
// Loop until we're done connecting.
while (!cg.done())
{
    wait_for_fd(cg.sock(), cg.wait_to_read(), cg.wait_to_write());
    cg.process();
}
 
pqxx::connection conn = std::move(cg).produce();
 
// At this point, conn is a working connection.  You can no longer use
// cg at all.

Constructor & Destructor Documentation

connecting() [1/3]

pqxx::connecting::connecting

(

zview

connection_string = ""_zv

)

Start connecting.

connecting() [2/3]

pqxx::connecting::connecting ( connecting const &  )

delete

connecting() [3/3]

pqxx::connecting::connecting ( connecting &&  )

default

Member Function Documentation

done()

constexpr bool pqxx::connecting::done ( ) const &

constexprnoexcept

Is our connection finished?

operator=() [1/2]

connecting& pqxx::connecting::operator= ( connecting &&  )

default

operator=() [2/2]

connecting& pqxx::connecting::operator= ( connecting const &  )

delete

process()

void pqxx::connecting::process

(

)

&

Progress towards completion (but don't block).

produce()

connection pqxx::connecting::produce

(

)

&&

Produce the completed connection object.

Use this only once, after done returned true. Once you have called this, the connecting instance has no more use or meaning. You can't call any of its member functions afterwards.

This member function is rvalue-qualified, meaning that you can only call it on an rvalue instance of the class. If what you have is not an rvalue, turn it into one by wrapping it in std::move().

sock()

int pqxx::connecting::sock ( ) const &

noexcept

Get the socket. The socket may change during the connection process.

wait_to_read()

constexpr bool pqxx::connecting::wait_to_read ( ) const &

constexprnoexcept

Should we currently wait to be able to read from the socket?

wait_to_write()

constexpr bool pqxx::connecting::wait_to_write ( ) const &

constexprnoexcept

Should we currently wait to be able to write to the socket?

---

The documentation for this class was generated from the following file:

• connection.hxx