ozo::connection< OidMap, Statistics > Class Template Reference

#include <ozo/connection.h>

Description

template<typename OidMap, typename Statistics>
class ozo::connection< OidMap, Statistics >

Default model for Connection concept.

Connection concept model which is used by the library as default model. The class object is non-copyable.

Template Parameters

OidMap	— oid map of types are used with connection
Statistics	— statistics of the connection (not supported yet)

Thread safety

Distinct objects: Safe
Shared objects: Unsafe

Models

Connection

Types
using	native_handle_type = ozo::pg::conn::pointer
	Native connection handle type.
using	oid_map_type = OidMap
	Oid map of types that are used with the connection.
using	error_context_type = std::string
	Additional error context which could provide context depended information for errors.
using	executor_type = io_context::executor_type
	The type of the executor associated with the object.

Public Member Functions
	connection (io_context &io, Statistics statistics)
native_handle_type	native_handle () const noexcept
oid_map_type &	oid_map () noexcept
const oid_map_type &	oid_map () const noexcept
const error_context_type &	get_error_context () const noexcept
void	set_error_context (error_context_type v=error_context_type{})
executor_type	get_executor () const noexcept
error_code	assign (ozo::pg::conn &&handle)
ozo::pg::conn	release ()
template<typename WaitHandler >
void	async_wait_write (WaitHandler &&handler)
template<typename WaitHandler >
void	async_wait_read (WaitHandler &&handler)
error_code	close () noexcept
void	cancel () noexcept
bool	is_bad () const noexcept
	operator bool () const noexcept
bool	is_open () const noexcept

Constructors

connection()

template<typename OidMap , typename Statistics >

ozo::connection< OidMap, Statistics >::connection	(	io_context &	io,
		Statistics	statistics
	)

Construct a new connection object.

Parameters

io	— execution context for IO operations associated with the object.
statistics	— initial statistics (not supported yet)

Member Function Documentation

assign()

template<typename OidMap , typename Statistics >

error_code ozo::connection< OidMap, Statistics >::assign

(

ozo::pg::conn &&

handle

)

Assign an existing native connection handle to the object.

Typically this function is used by the library within the connection establishing process. Users should not use it directly other than for a special purpose (e.g., special connection pool implementation and so on).

Warning

Don't call this function during any active operation executed on the object.

Parameters

handle

— rvalue reference on a new handle.

Returns

error_code — error code of the function call.

References ozo::error::pq_socket_failed.

async_wait_read()

template<typename OidMap , typename Statistics >

template<typename WaitHandler >

void ozo::connection< OidMap, Statistics >::async_wait_read

(

WaitHandler &&

handler

)

Asynchronously wait for the connection socket to become ready to read or to have pending error conditions.

Typically this function is used by the library within the connection establishing process and operation execution. Users should not use it directly other than for custom libpq-based opeartions.

Warning

The function is designated to the library operations use only. Don't call this function directly.

Parameters

handler

— wait handler with void(ozo::error_code, int=0) signature.

async_wait_write()

template<typename OidMap , typename Statistics >

template<typename WaitHandler >

void ozo::connection< OidMap, Statistics >::async_wait_write

(

WaitHandler &&

handler

)

Asynchronously wait for the connection socket to become ready to write or to have pending error conditions.

Typically this function is used by the library within the connection establishing process and operation execution. Users should not use it directly other than for custom libpq-based opeartions.

Warning

The function is designated to the library operations use only. Don't call this function directly.

Parameters

handler

— wait handler with void(ozo::error_code, int=0) signature.

cancel()

template<typename OidMap , typename Statistics >

void ozo::connection< OidMap, Statistics >::cancel

noexcept

Cancel all asynchronous operations associated with the connection.

This function causes all outstanding asynchronous operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation_aborted error.

close()

template<typename OidMap , typename Statistics >

error_code ozo::connection< OidMap, Statistics >::close

noexcept

Close the connection.

Any asynchronous operations will be cancelled immediately, and will complete with the boost::asio::error::operation_aborted error.

Returns

error_code - indicates what error occurred, if any. Note that, even if the function indicates an error, the underlying connection is closed.

get_error_context()

template<typename OidMap , typename Statistics >

const error_context_type& ozo::connection< OidMap, Statistics >::get_error_context ( ) const

noexcept

Get the additional context object for an error that occurred during the last operation on the connection.

Returns

const error_context_type& — additional context for the error

get_executor()

template<typename OidMap , typename Statistics >

executor_type ozo::connection< OidMap, Statistics >::get_executor ( ) const

noexcept

Get the executor associated with the object.

Returns

executor_type — executor object.

is_bad()

template<typename OidMap , typename Statistics >

bool ozo::connection< OidMap, Statistics >::is_bad

noexcept

Determine whether the connection is in bad state.

Returns

false — connection established, and it is ok to execute operations

true — connection is not established, no operation shall be performed, but an error context may be obtained via get_error_context() and ozo::error_message().

Referenced by ozo::connection< OidMap, Statistics >::operator bool().

is_open()

template<typename OidMap , typename Statistics >

bool ozo::connection< OidMap, Statistics >::is_open ( ) const

noexcept

Determine whether the connection is open.

Returns

false — connection is closed and no native handle associated with.

true — connection is open and there is a native handle associated with.

References ozo::connection< OidMap, Statistics >::native_handle().

native_handle()

template<typename OidMap , typename Statistics >

native_handle_type ozo::connection< OidMap, Statistics >::native_handle ( ) const

noexcept

Get native connection handle object.

This function may be used to obtain the underlying representation of the connection. This is intended to allow access to native libpq functionality that is not otherwise provided.

Warning

Don't use the function with the PQfinish function. Use the close() member function instead.

Returns

native_handle_type — native connection handle.

Referenced by ozo::connection< OidMap, Statistics >::is_open().

oid_map() [1/2]

template<typename OidMap , typename Statistics >

const oid_map_type& ozo::connection< OidMap, Statistics >::oid_map ( ) const

noexcept

Get a reference to an oid map object for types that are used with the connection.

Returns

const oid_map_type& — reference on oid map object.

oid_map() [2/2]

template<typename OidMap , typename Statistics >

oid_map_type& ozo::connection< OidMap, Statistics >::oid_map ( )

noexcept

Get a reference to an oid map object for types that are used with the connection. This method is used after connection establishing process to update the map.

Returns

oid_map_type& — reference on oid map object.

operator bool()

template<typename OidMap , typename Statistics >

ozo::connection< OidMap, Statistics >::operator bool ( ) const

noexcept

Determine whether the connection is not in bad state.

Returns

true — connection established, and it is ok to execute operations

false — connection is not established, no operation shall be performed, but an error context may be obtained via get_error_context() and ozo::error_message().

References ozo::connection< OidMap, Statistics >::is_bad().

release()

template<typename OidMap , typename Statistics >

ozo::pg::conn ozo::connection< OidMap, Statistics >::release

Release ownership of the native connection handle object.

This function may be used to obtain the underlying representation of the descriptor. After calling this function, is_open() returns false. The caller is the owner for the connection descriptor. All outstanding asynchronous read or write operations will finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation_aborted error.

Returns

ozo::pg::conn — native connection handle object

set_error_context()

template<typename OidMap , typename Statistics >

void ozo::connection< OidMap, Statistics >::set_error_context

(

error_context_type

v = error_context_type{}

)

Set the additional error context object. This function may be used to provide additional context-depended data that is related to the current operation error.

Parameters

v	— new error context.