#include <cpool.h>
Collaboration diagram for mysqlpp::ConnectionPool:
Public Member Functions | |
| ConnectionPool () | |
| Create empty pool. | |
| virtual | ~ConnectionPool () |
| Destroy object. | |
| bool | empty () const |
| Returns true if pool is empty. | |
| Connection * | grab () |
| Grab a free connection from the pool. | |
| 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. | |
Classes | |
| struct | ConnectionInfo |
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.
| 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.
| 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.
| 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.
| 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 | ( | ) |
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.
| 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.
| number | of seconds before an idle connection is destroyed due to lack of use |
| void mysqlpp::ConnectionPool::release | ( | const Connection * | pc | ) |
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.
1.4.7