OTL 4.0, Template otl_connect_pool<OTLConnect,OTLException>

Template otl_connect_pool<OTLConnect,OTLException>

This is an OTL template class that allows the users to pool otl_connect objects. It requires C++11 compilers like more or less recent GNU C++ / CLANG (when -std=c++11 on the compiler command line and #define OTL_CPP_11_ON are used), or Visual C++ Studio (2012, or 2013). This connect pool class uses std::unique pointers in order to cleanly transfer (std::move()) connect object's ownership between the pool and the callers, and avoid memory leaks. All functions in this connect pool class are thread safe.

The otl_connect_pool class can be activated with #define OTL_CONNECT_POOL_ON

template<typename OTLConnect, typename OTLException> 
class otl_connect_pool{
public:

Function / typedef Description

otl_connect_pool();

Default constructor

otl_connect_pool(...);

Parameter	Description
const char* connect_str	connect string (see otl_connect::rlogon() for more detail)
bool auto_commit=false	connect auto_commit flag
size_t min_pool_size=8	minimum pool size. The connect pool allocates the specified number (min_pool_size) of otl_connect objects, and connects all of the connect objects to the database. If one of the connects fails, this function throws an otl_exception.
size_t max_pool_size=32	maximum pool size. The pool size can only grow up to the specified maximum size. When the pool is full, no more connect objects can be put into the pool.
size_t grow_pool_in_increments=1	When the pool needs to grow, this parameter specifies how many connections get added to the pool, but still less or equal to the maximum size.

General constructor. It may throw an otl_exception.

~otl_connect_pool(); Destructor.

void open(...);

Parameter	Description
const char* connect_str	connect string (see otl_connect::rlogon() for more detail)
bool auto_commit=false	connect auto_commit flag
size_t min_pool_size=8	minimum pool size. The connect pool allocates the specified number (min_pool_size) of otl_connect objects, and connects all of the connect objects to the database. If one of the connects fails, this function throws an otl_exception.
size_t max_pool_size=32	maximum pool size. The pool size can only grow up to the specified maximum size. When the pool is full, no more connect objects can be put into the pool.
size_t grow_pool_in_increments=1	When the pool needs to grow, this parameter specifies how many connections get added to the pool, but still less or equal to the maximum size.

Opens the pool and prepopulates it to the specified minimum size. If the pool was already opened, closes it first. It may throw an otl_exception.

void close(bool ignore_errors=false); Closes the pool: disconnects all connect objects from the database, and dealloactes the objects. If ignore_errors is set to false, then this function may throw an otl_exception. If ignore_errors is set to true, all possible database disconnect errors are ignored.

void change_max_pool_size(const size_t new_max_pool_size); Changes the maximum pool size if the current maximum pool size. If the current pool size is larger than the new maximum pool size, the pool shrinks to the new size.

void shrink_pool(...);

Parameter	Description
size_t min_pool_size	new minimum pool size
bool ignore_errors=false	ignore any database errors

Shrinks (disconnects from the database and deallocates the underlying connect objects) the pool size to the new specified minimum pool size. If the pools size is already smaller than the new specified minimum pool size, the function doesn't do anything. If ignore_errors is set to false, the function may throw an otl_exception. This function can be called by a timer to shrink excessive capacity of the pool. OTL doesn't use timers because timers aren't available in the C++ standard library yet.

typedef std::unique_ptr<OTLConnect> connect_ptr; (C++11) Unique pointer to the connect object.

connect_ptr get(const ignore_errors=true); Gets a connect object from the pool. The ownership of the connect object is transferred / moved (the caller should use std::move()) from the pool to the caller. If the pool is empty / at its maximum capacity or closed, the function returns an empty unique pointer. If ignore_errors is set to false, the function may throw an otl_exception.

bool put(connect_ptr&& p); Puts a connect object into the pool. The ownership of the connect object is transferred / moved (std::move()) from the caller to the pool. The function returns false if the pool is closed or full (filled to its maximum pool size). Otherwise, the function returns true. If the pool is full, the input unique pointer to the underlying connect object does not get moved, so it is the caller's responsibility to dispose of the connect object or reuse in some way.

bool is_open(); Returns the "pool open" flag.

size_t min_pool_size(); Returns the "minimum pool size".

size_t min_pool_size(); Returns the "maximum pool size".

size_t current_pool_size(); Returns the "current / dynamic pool size".

std::recursive_mutex& get_mutex(); Returns a read/write reference to the underlying mutex. It should be used when a sequence of more than one call needs to be done under a single mutex lock for consistency.

}; // end of otl_connect_pool

Prev Next Contents Go Home

Permission to use, copy, modify and redistribute this document for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.