Loading...
Searching...
No Matches
pqxx::connecting Class Reference

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

## Public Member Functions

| connecting (zview connection_string=""_zv)
| Start connecting.
| 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.
constexpr bool | wait_to_read () const &noexcept
| Should we currently wait to be able to read from the socket?
constexpr bool | wait_to_write () const &noexcept
| Should we currently wait to be able to write to the socket?
void | process () &
| Progress towards completion (but don't block).
constexpr bool | done () const &noexcept
| Is our connection finished?
connection | produce () &&
| Produce the completed connection object.

## 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 cx = std::move(cg).produce();
// At this point, cx is a working connection. You can no longer use
// cg at all.
pqxx::connecting
An ongoing, non-blocking stepping stone to a connection.
Definition connection.hxx:1404
pqxx::connection
Connection to a database.
Definition connection.hxx:279

## Member Function Documentation

## 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()`.

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

- /build/libpqxx-dRO3di/libpqxx-7.10.0/include/pqxx/connection.hxx