ozo::transaction< Connection, Options > Class Template Reference

#include <ozo/transaction.h>

Description

template<typename Connection, typename Options>
class ozo::transaction< Connection, Options >

Transaction Connection model.

Connection concept model that describes the open transaction on the underlying connection. The transaction is not an RAII object it does not control transaction flow. It is dedicated to describe the current transaction and represent a transaction on the type level.

Warning

Depending on the underlying Connection the transaction object may model Nullable. If the object is in null state call of any member may lead to undefined behaviour.

Template Parameters

Connection	— the underlying Connection model type.
Options	— the transaction options type, see ozo::transaction_options for the details.

Thread safety

Distinct objects: Depends on underlyingConnectionmodel
Shared objects: Unsafe

Models

Connection

Types
using	lowest_layer_type = unwrap_type< handle_type >
	Lowest level Connection model type - fully unwrapped type.
using	native_handle_type = typename lowest_layer_type::native_handle_type
	Native connection handle type.
using	oid_map_type = typename lowest_layer_type::oid_map_type
	Oid map of types that are used with the connection.
using	error_context_type = typename lowest_layer_type::error_context_type
	Additional error context which could provide context depended information for errors.
using	executor_type = typename lowest_layer_type::executor_type
	The type of the executor associated with the object.
using	options_type = std::decay_t< Options >
	The type of options specified for the transaction.

Public Member Functions
	transaction ()=default
	transaction (Connection &&connection, Options options) noexcept(std::is_nothrow_move_constructible_v< Connection > &&std::is_nothrow_move_constructible_v< Options >)
native_handle_type	native_handle () const 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
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
constexpr const options_type &	options () const noexcept
lowest_layer_type &	lowest_layer () noexcept
const lowest_layer_type &	lowest_layer () const noexcept

Friends
handle_type	release_connection (transaction &&x) noexcept

Constructors

transaction() [1/2]

template<typename Connection , typename Options >

ozo::transaction< Connection, Options >::transaction ( )

default

Construct a new uninitialized transaction object.

If underlying Connection model is Nullable then ozo::is_null() should return true for the constructed object.

Warning

The constructed object is in an uninitialized state, which means it shall not be used until being initialized with a valid transaction object. Calling any member of the uninitialized object leads to undefined behavior.

transaction() [2/2]

template<typename Connection , typename Options >

ozo::transaction< Connection, Options >::transaction ( Connection &&  connection, Options  options  )

noexcept

Construct a new transaction object.

Note

Constructing a transaction object does not open any transaction, use ozo::begin() instead to open a transaction with required options.

Parameters

connection	— connection object to perform transaction on.
options	— options of the transaction

Member Function Documentation

async_wait_read()

template<typename Connection , typename Options >

template<typename WaitHandler >

void ozo::transaction< Connection, Options >::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.

Note

The object should be initialized for this call.

Parameters

handler

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

References ozo::transaction< Connection, Options >::lowest_layer().

async_wait_write()

template<typename Connection , typename Options >

template<typename WaitHandler >

void ozo::transaction< Connection, Options >::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.

Note

The object should be initialized for this call.

Parameters

handler

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

References ozo::transaction< Connection, Options >::lowest_layer().

cancel()

template<typename Connection , typename Options >

void ozo::transaction< Connection, Options >::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.

Note

The object should be initialized for this call.

References ozo::transaction< Connection, Options >::lowest_layer().

close()

template<typename Connection , typename Options >

error_code ozo::transaction< Connection, Options >::close ( )

noexcept

Close the connection.

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

Note

The object should be initialized for this call.

Returns

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

References ozo::transaction< Connection, Options >::lowest_layer().

get_error_context()

template<typename Connection , typename Options >

const error_context_type& ozo::transaction< Connection, Options >::get_error_context ( ) const

noexcept

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

Note

The object should be initialized for this call.

Returns

const error_context_type& — additional context for the last error

References ozo::transaction< Connection, Options >::lowest_layer().

get_executor()

template<typename Connection , typename Options >

executor_type ozo::transaction< Connection, Options >::get_executor ( ) const

noexcept

Get the executor associated with the object.

Note

The object should be initialized for this call.

Returns

executor_type — executor object.

References ozo::transaction< Connection, Options >::lowest_layer().

is_bad()

template<typename Connection , typename Options >

bool ozo::transaction< Connection, Options >::is_bad ( ) const

noexcept

Determine whether the connection is in bad state.

Note

The object should be initialized for this call.

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

References ozo::transaction< Connection, Options >::lowest_layer().

Referenced by ozo::transaction< Connection, Options >::operator bool().

is_open()

template<typename Connection , typename Options >

bool ozo::transaction< Connection, Options >::is_open ( ) const

noexcept

Determine whether the connection is open. The object may be used in noninitialized state for this call.

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::transaction< Connection, Options >::lowest_layer().

lowest_layer() [1/2]

template<typename Connection , typename Options >

const lowest_layer_type& ozo::transaction< Connection, Options >::lowest_layer ( ) const

noexcept

Get a const reference to the lowest layer.

Note

The object should be initialized for this call.

References ozo::unwrap().

lowest_layer() [2/2]

template<typename Connection , typename Options >

lowest_layer_type& ozo::transaction< Connection, Options >::lowest_layer ( )

noexcept

Get a reference to the lowest layer.

Note

The object should be initialized for this call.

References ozo::unwrap().

Referenced by ozo::transaction< Connection, Options >::async_wait_read(), ozo::transaction< Connection, Options >::async_wait_write(), ozo::transaction< Connection, Options >::cancel(), ozo::transaction< Connection, Options >::close(), ozo::transaction< Connection, Options >::get_error_context(), ozo::transaction< Connection, Options >::get_executor(), ozo::transaction< Connection, Options >::is_bad(), ozo::transaction< Connection, Options >::is_open(), ozo::transaction< Connection, Options >::native_handle(), and ozo::transaction< Connection, Options >::oid_map().

native_handle()

template<typename Connection , typename Options >

native_handle_type ozo::transaction< Connection, Options >::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.

Note

The object should be initialized for this call.

Returns

native_handle_type — native connection handle.

References ozo::transaction< Connection, Options >::lowest_layer().

oid_map()

template<typename Connection , typename Options >

const oid_map_type& ozo::transaction< Connection, Options >::oid_map ( ) const

noexcept

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

Note

The object should be initialized for this call.

Returns

const oid_map_type& — reference on oid map object.

References ozo::transaction< Connection, Options >::lowest_layer().

operator bool()

template<typename Connection , typename Options >

ozo::transaction< Connection, Options >::operator bool ( ) const

noexcept

Determine whether the connection may be used for operations. The object may be used in noninitialized state for this call.

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::transaction< Connection, Options >::is_bad().

options()

template<typename Connection , typename Options >

constexpr const options_type& ozo::transaction< Connection, Options >::options ( ) const

constexprnoexcept

Get the transaction options. See ozo::transaction_options for the details.

Note

The object should be initialized for this call.

Referenced by ozo::get_transaction_deferrability(), ozo::get_transaction_isolation_level(), and ozo::get_transaction_mode().

set_error_context()

template<typename Connection , typename Options >

void ozo::transaction< Connection, Options >::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.

Note

The object should be initialized for this call.

Parameters

v	— new error context.

Friends And Related Function Documentation

release_connection

template<typename Connection , typename Options >

handle_type release_connection ( transaction< Connection, Options > &&  x )

friend

Release ownership of the underlying Connection model object.

This function may be used to obtain the underlying Connection model. After calling this function, the transaction object may not be used. The caller is the owner for the connection.

Warning

In case of a transaction in progress, no commit or rollback will be made. The caller is fully responsible for further transaction management.

Parameters

x	— transaction to release connection from, the object should be initialized for this call.

Returns

underlying Connection model object