Description

Connection related functions.

Functions
template<typename T >
constexpr decltype(auto)	ozo::unwrap_connection (T &&conn) noexcept
	Unwrap connection if wrapped with Nullable. More...

template<typename Connection >
auto	ozo::get_native_handle (const Connection &conn) noexcept
	Get native connection handle object. More...

template<typename Connection >
auto	ozo::get_executor (const Connection &conn) noexcept
	Get the executor associated with the object. More...

template<typename T >
bool	ozo::connection_bad (const T &conn) noexcept
	Determine whether the connection is in bad state. More...

template<typename Connection >
bool	ozo::connection_good (const Connection &conn) noexcept
	Indicates if connection state is not bad. More...

template<typename Connection >
std::string_view	ozo::error_message (const Connection &conn)
	Get native libpq error message. More...

template<typename Connection >
const auto &	ozo::get_error_context (const Connection &conn)
	Get additional error context. More...

template<typename Connection >
std::string_view	ozo::get_database (const Connection &conn)
	Get the database name of the active connection. More...

template<typename Connection >
std::string_view	ozo::get_host (const Connection &conn)
	Get the host connected of the active connection. More...

template<typename Connection >
std::string_view	ozo::get_port (const Connection &conn)
	Get the port connected of the active connection. More...

template<typename Connection >
std::string_view	ozo::get_user (const Connection &conn)
	Get the user name of the active connection. More...

template<typename Connection >
std::string_view	ozo::get_password (const Connection &conn)
	Get the password of the active connection. More...

template<typename T , typename TimeConstraint , typename CompletionToken >
decltype(auto)	ozo::get_connection (T &&provider, TimeConstraint time_constraint, CompletionToken &&token)
	Get a connection object from connection provider with time constaint. More...

template<typename T , typename CompletionToken >
decltype(auto)	ozo::get_connection (T &&provider, CompletionToken &&token)
	Get a connection from connection provider. More...

template<typename Connection >
error_code	ozo::close_connection (Connection &&conn)
	Close connection to the database immediately. More...

template<typename Connection >
auto	ozo::defer_close_connection (Connection *conn)
	Close connection to the database when leaving the scope. More...

template<typename Connection >
transaction_status	ozo::get_transaction_status (Connection &&conn)
	Returns current status of a `Connection` object. More...

template<typename OidMap = empty_oid_map, typename Statistics = no_statistics>
auto	make_connection_info (std::string conn_str, const OidMap &oid_map=OidMap{}, Statistics statistics=Statistics{})
	Constructs `ozo::connection_info` `ConnectionSource`. More...

template<typename ConnectionSource , typename ThreadSafety = decltype(thread_safe)>
auto	make_connection_pool (ConnectionSource &&source, const connection_pool_config &config, const ThreadSafety &thread_safety=ThreadSafety{})
	Connection pool construct helper function. More...

Function Documentation

◆ close_connection()

template<typename Connection >

error_code ozo::close_connection ( Connection && conn )

Close connection to the database immediately.

This function closes connection to the database immediately.

Note: No query cancel operation will be made while closing connection. Use the function with attention - non cancelled query can still produce a work on server-side and consume resources. So it is better to use ozo::cancel() function.

Parameters

conn	— `Connection` to be closed

References ozo::unwrap_connection().

Referenced by ozo::defer_close_connection().

◆ connection_bad()

template<typename T >

bool ozo::connection_bad ( const T & conn )

noexcept

Determine whether the connection is in bad state.

Alias to unwrap_connection(conn).is_bad(). See the Connection documentation for more details.

Parameters

conn	— `Connection` object.

Returns: true if connection is in bad or null state, false - otherwise.

Referenced by ozo::connection_good().

◆ connection_good()

template<typename Connection >

bool ozo::connection_good ( const Connection & conn )

noexcept

Indicates if connection state is not bad.

Alias to !ozo::connection_bad(conn).

Parameters

conn	— `Connection` object.

Returns: false if connection is in bad state, true - otherwise

References ozo::connection_bad().

◆ defer_close_connection()

template<typename Connection >

auto ozo::defer_close_connection ( Connection * conn )

Close connection to the database when leaving the scope.

This function creates RAII guard object which calls ozo::close_connection() at the end of its scope. If nullptr is passed as argument or connection is null recursive no ozo::close_connection() would be made.

Parameters

conn	— pointer on a `Connection` to be closed.

Example

{
    auto guard = defer_close_connection(should_be_closed ? std::addressof(conn) : nullptr);
 
    // Process the connection
}

References ozo::close_connection(), and ozo::is_null_recursive().

Referenced by ozo::failover::basic_try< Options, Context >::get_next_try().

◆ error_message()

template<typename Connection >

std::string_view ozo::error_message ( const Connection & conn )

Get native libpq error message.

Underlying libpq provides additional textual context for different errors which can be while interacting via connection. This function gives access for such messages.

Parameters

conn	— `Connection` to get message from.

Returns: std::string_view with a message.

References ozo::get_native_handle(), and ozo::is_null_recursive().

◆ get_connection() [1/2]

template<typename T , typename CompletionToken >

decltype(auto) ozo::get_connection	(	T &&	provider,
		CompletionToken &&	token
	)

Get a connection from connection provider.

This function is a shortcut to ozo::get_connection(provider, ozo::none, token) call.

Note: The function does not particitate in ADL since could be implemented via functional object.

Parameters

provider	— `ConnectionProvider` to get connection from.
token	— operation CompletionToken.

Returns: deduced from CompletionToken.

References ozo::get_operation_initiator(), and ozo::none.

◆ get_connection() [2/2]

template<typename T , typename TimeConstraint , typename CompletionToken >

decltype(auto) ozo::get_connection	(	T &&	provider,
		TimeConstraint	time_constraint,
		CompletionToken &&	token
	)

Get a connection object from connection provider with time constaint.

Retrives a connection object from connection provider within specified time constaint. The default implementation for the Connection object forwards this object and resets it's error context.

Note: The function does not particitate in ADL since could be implemented via functional object.

Parameters

provider	— `ConnectionProvider` to get connection from.
time_constraint	— #TimeConstraint for the operation.
token	— operation CompletionToken.

Returns: deduced from CompletionToken.

Customization point

This is a customization point of ConnectionProvider. By default ConnectionProvider should have async_get_connection() member function with signature:

template <typename TimeConstraint>

void async_get_connection(TimeConstraint t, Handler&& h);

This behaviour can be customized via async_get_connection_impl specialization. E.g. for custom implementation of Connection customization may looks like this (exposition only):

template <typename TimeConstrain, typename ...Ts>
struct async_get_connection_impl<MyConnection<Ts...>, TimeConstrain> {
    template <typename Conn, typename Handler>
    static constexpr void apply(Conn&& c, TimeConstraint t, Handler&& h) {
        c->prepareForNextOp();
        async_get_connection_impl_default<MyConnection<Ts...>, TimeConstrain>::apply(
            std::forward<Conn>(c), t, std::forward<Handler>(h)
        );
    }
};

◆ get_database()

template<typename Connection >

std::string_view ozo::get_database ( const Connection & conn )

Get the database name of the active connection.

See documentation for the underlying PQdb function for additional information.

Note: Connection should not be is null recursive.

Parameters

conn	— active connection to a database.

Returns: std::string_view — string view with database name.

References ozo::get_native_handle().

◆ get_error_context()

template<typename Connection >

const auto & ozo::get_error_context ( const Connection & conn )

Get additional error context.

Alias to unwrap_connection(conn).get_error_context(). See. Connection documentation for more details.

Parameters

conn	— `Connection` object which is not in null recursive state

Returns: reference on additional context

References ozo::unwrap_connection().

◆ get_executor()

template<typename Connection >

auto ozo::get_executor ( const Connection & conn )

noexcept

Get the executor associated with the object.

Alias to unwrap_connection(conn).get_executor(). See the Connection documentation for more details.

Parameters

conn	— `Connection` object.

Returns: executor associated with the object.

References ozo::unwrap_connection().

◆ get_host()

template<typename Connection >

std::string_view ozo::get_host ( const Connection & conn )

Get the host connected of the active connection.

See documentation for the underlying PQhost function for additional information.

Note: Connection should not be is null recursive.

Parameters

conn	— active connection to a database.

Returns: std::string_view — string view with host.

References ozo::get_native_handle().

◆ get_native_handle()

template<typename Connection >

auto ozo::get_native_handle ( const Connection & conn )

noexcept

Get native connection handle object.

Alias to unwrap_connection(conn).native_handle(). See the Connection documentation for more details.

Parameters

conn	— `Connection` object.

Returns: native connection handle.

References ozo::unwrap_connection().

Referenced by ozo::error_message(), ozo::get_cancel_handle(), ozo::get_database(), ozo::get_host(), ozo::get_password(), ozo::get_port(), and ozo::get_user().

◆ get_password()

template<typename Connection >

std::string_view ozo::get_password ( const Connection & conn )

Get the password of the active connection.

See documentation for the underlying PQpass function for additional information.

Note: Connection should not be is null recursive.

Parameters

conn	— active connection to a database.

Returns: std::string_view — string view with password.

References ozo::get_native_handle().

◆ get_port()

template<typename Connection >

std::string_view ozo::get_port ( const Connection & conn )

Get the port connected of the active connection.

See documentation for the underlying PQport function for additional information.

Note: Connection should not be is null recursive.

Parameters

conn	— active connection to a database.

Returns: std::string_view — string view with port.

References ozo::get_native_handle().

◆ get_transaction_status()

template<typename Connection >

transaction_status ozo::get_transaction_status ( Connection && conn )

Returns current status of a Connection object.

Returns current status of specified Connection. If the Connection is #Nullable in null-state returns ozo::transaction_status::unknown. In other case it returns value associated with libpq connection transaction status.

Parameters

conn	— `Connection`

Returns: transaction_status — status of the Connection

Exceptions

std::invalid_argument — in case of unsupported value returned by libpq function. It is better to use -Werror compiler flag to prevent such possability by checking enumeration coverage in the switch-case statement.

◆ get_user()

template<typename Connection >

std::string_view ozo::get_user ( const Connection & conn )

Get the user name of the active connection.

See documentation for the underlying PQuser function for additional information.

Note: Connection should not be is null recursive.

Parameters

conn	— active connection to a database.

Returns: std::string_view — string view with user name.

References ozo::get_native_handle().

◆ make_connection_info()

template<typename OidMap = empty_oid_map, typename Statistics = no_statistics>

auto make_connection_info	(	std::string	conn_str,
		const OidMap &	oid_map = `OidMap{}`,
		Statistics	statistics = `Statistics{}`
	)

Parameters

conn_str	— standard libpq connection string.
OidMap	— oid map for user defined types.
statistics	— statistics to collect for a connection.

Returns: ozo::connection_info specialization.

◆ make_connection_pool()

template<typename ConnectionSource , typename ThreadSafety = decltype(thread_safe)>

auto make_connection_pool	(	ConnectionSource &&	source,
		const connection_pool_config &	config,
		const ThreadSafety &	thread_safety = `ThreadSafety{}`
	)

Helper function which creates connection pool based on ConnectionSource and configuration parameters.

Parameters

source	— connection source object which is being used to create connection to a database.
config	— pool configuration.
thread_safety	— admissibility to use in multithreaded environment without additional synchronization. Thread safe by default (`ozo::thread_safety<true>`).

Returns: ozo::connection_pool object.

◆ unwrap_connection()

template<typename T >

constexpr decltype(auto) ozo::unwrap_connection ( T && conn )

constexprnoexcept

Unwrap connection if wrapped with Nullable.

Unwraps wrapped connection recursively. Returns unwrapped connection object.

Customization Point

This is customization point for the Connection enhancement. To customize it it is better to specialize ozo::unwrap_connection_impl template for custom type. E.g. such overload is used for the ozo::pooled_connection of this library. The deafult implementation of the function is perfect forwarding. And may look like this (for exposition only - actual implementation may be different):

template <typename T>
struct unwrap_connection_impl {
    template <typename Conn>
    static constexpr decltype(auto) apply(Conn&& conn) noexcept {
        return std::forward<Conn>(conn);
    }
};

If you are specialize the template for your own parameterized connection wrapper implementation do not forget to call unwrap_connection for the underlying connection type. E.g.:

template <typename T>
struct unwrap_connection_impl<CustomWrapper<T>>{
    template <typename Conn>
    static constexpr decltype(auto) apply(Conn&& conn) noexcept {
        return unwrap_connection(conn.underlying());
    }
};

Function overload works as well, but it is safer to specialize the template.

Parameters

conn	— wrapped or unwrapped `Connection`

Returns: unwrapped Connection object reference

Referenced by ozo::close_connection(), ozo::get_error_context(), ozo::get_executor(), and ozo::get_native_handle().

Description

Functions

Function Documentation

◆ close_connection()

◆ connection_bad()

◆ connection_good()

◆ defer_close_connection()

◆ error_message()

◆ get_connection() [1/2]

◆ get_connection() [2/2]

◆ get_database()

◆ get_error_context()

◆ get_executor()

◆ get_host()

◆ get_native_handle()

◆ get_password()

◆ get_port()

◆ get_transaction_status()

◆ get_user()

◆ make_connection_info()

◆ make_connection_pool()

◆ unwrap_connection()