MySQL++ Reference Manual

- Main Page
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

# mysqlpp::ConnectionPool Class Reference

Manages a pool of connections for programs that need more than one Connection object at a time, but can't predict how many they need in advance. More...

`#include <cpool.h>`

Collaboration diagram for mysqlpp::ConnectionPool:

[legend]
List of all members.

## Public Member Functions
| ConnectionPool ()
| Create empty pool.
virtual | ~ConnectionPool ()
| Destroy object.
bool | empty () const
| Returns true if pool is empty.
virtual Connection * | grab ()
| Grab a free connection from the pool.
virtual void | release (const Connection *pc)
| Return a connection to the pool.
void | shrink ()
| Remove all unused connections from the pool.
## Protected Member Functions
void | clear (bool all=true)
| Drains the pool, freeing all allocated memory.
virtual Connection * | create ()=0
| Create a new connection.
virtual void | destroy (Connection *)=0
| Destroy a connection.
virtual unsigned int | max_idle_time ()=0
| Returns the maximum number of seconds a connection is able to remain idle before it is dropped.
size_t | size () const
| Returns the current size of the internal connection pool.
## Classes
struct | ConnectionInfo

## Detailed Description

Manages a pool of connections for programs that need more than one Connection object at a time, but can't predict how many they need in advance.

This class is useful in programs that need to make multiple simultaneous queries on the database; this requires multiple Connection objects due to a hard limitation of the underlying C API. Connection pools are most useful in multithreaded programs, but it can be helpful to have one in a single-threaded program as well. Sometimes it's necessary to get more data from the server while in the middle of processing data from an earlier query; this requires multiple connections. Whether you use a pool or manage connections yourself is up to you, but realize that this class takes care of a lot of subtle details for you that aren't obvious.

The pool's policy for connection reuse is to always return the most recently used connection that's not being used right now. This ensures that excess connections don't hang around any longer than they must. If the pool were to return the least recently used connection, it would be likely to result in a large pool of sparsely used connections because we'd keep resetting the last-used time of whichever connection is least recently used at that moment.

## Constructor & Destructor Documentation

virtual mysqlpp::ConnectionPool::~ConnectionPool | ( |  | ) | `[inline, virtual]`

Destroy object.

If the pool raises an assertion on destruction, it means our subclass isn't calling clear() in its dtor as it should.

## Member Function Documentation

void mysqlpp::ConnectionPool::clear | ( | bool | all = `true` | ) | `[protected]`

Drains the pool, freeing all allocated memory.

A derived class must call this in its dtor to avoid leaking all Connection objects still in existence. We can't do it up at this level because this class's dtor can't call our subclass's destroy() method.

Parameters:

  | all | if true, remove all connections, even those in use

virtual Connection* mysqlpp::ConnectionPool::create | ( |  | ) | `[protected, pure virtual]`

Create a new connection.

Subclasses must override this.

Essentially, this method lets your code tell ConnectionPool what server to connect to, what login parameters to use, what connection options to enable, etc. ConnectionPool can't know any of this without your help.

Return values:

  | A | connected Connection object

virtual void mysqlpp::ConnectionPool::destroy | ( | Connection * |  | ) | `[protected, pure virtual]`

Destroy a connection.

Subclasses must override this.

This is for destroying the objects returned by create(). Because we can't know what the derived class did to create the connection we can't reliably know how to destroy it.

Connection * mysqlpp::ConnectionPool::grab | ( |  | ) | `[virtual]`

Grab a free connection from the pool.

This method creates a new connection if an unused one doesn't exist, and destroys any that have remained unused for too long. If there is more than one free connection, we return the most recently used one; this allows older connections to die off over time when the caller's need for connections decreases.

Do not delete the returned pointer. This object manages the lifetime of connection objects it creates.

Return values:

  | a | pointer to the connection

virtual unsigned int mysqlpp::ConnectionPool::max_idle_time | ( |  | ) | `[protected, pure virtual]`

Returns the maximum number of seconds a connection is able to remain idle before it is dropped.

Subclasses must override this as it encodes a policy issue, something that MySQL++ can't declare by fiat.

Return values:

  | number | of seconds before an idle connection is destroyed due to lack of use

void mysqlpp::ConnectionPool::release | ( | const Connection * | pc | ) | `[virtual]`

Return a connection to the pool.

Marks the connection as no longer in use.

The pool updates the last-used time of a connection only on release, on the assumption that it was used just prior. There's nothing forcing you to do it this way: your code is free to delay releasing idle connections as long as it likes. You want to avoid this because it will make the pool perform poorly; if it doesn't know approximately how long a connection has really been idle, it can't make good judgements about when to remove it from the pool.

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

- cpool.h
- cpool.cpp