|
MySQL++
3.3.0
|
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>
Public Member Functions | |
| ConnectionPool () | |
| Create empty pool. | |
| virtual | ~ConnectionPool () |
| Destroy object. More... | |
| bool | empty () const |
| Returns true if pool is empty. | |
| virtual Connection * | exchange (const Connection *pc) |
| Return a defective connection to the pool and get a new one back. More... | |
| virtual Connection * | grab () |
| Grab a free connection from the pool. More... | |
| virtual void | release (const Connection *pc) |
| Return a connection to the pool. More... | |
| void | remove (const Connection *pc) |
| Removes the given connection from the pool. More... | |
| virtual Connection * | safe_grab () |
| Grab a free connection from the pool, testing that it's connected before returning it. More... | |
| void | shrink () |
| Remove all unused connections from the pool. | |
Protected Member Functions | |
| void | clear (bool all=true) |
| Drains the pool, freeing all allocated memory. More... | |
| virtual Connection * | create ()=0 |
| Create a new connection. More... | |
| virtual void | destroy (Connection *)=0 |
| Destroy a connection. More... | |
| virtual unsigned int | max_idle_time ()=0 |
| Returns the maximum number of seconds a connection is able to remain idle before it is dropped. More... | |
| size_t | size () const |
| Returns the current size of the internal connection pool. | |
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.
|
inlinevirtual |
Destroy object.
If the pool raises an assertion on destruction, it means our subclass isn't calling clear() in its dtor as it should.
|
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 |
References remove().
|
protectedpure 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 |
Referenced by grab().
|
protectedpure 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.
|
virtual |
Return a defective connection to the pool and get a new one back.
Call this on receiving a BadQuery exception, with errnum() equal to CR_SERVER_GONE_ERROR. It means the server was restarted or otherwise dropped your connection to it, so the Connection object is no longer usable. You can avoid the need to use this by setting the ReconnectOption in your grab() override, but perhaps there are other reasons to need to exchange a bad connection for a good one.
This function wraps grab(), not safe_grab(), even though that could return another dead connection. The assumption is that if your code is smart enough to detect one bad connection, it should be smart enough to detect a whole string of them. Worst case, the whole pool is bad – remote server went away – and we have to empty the pool and start re-filling it.
| pc | pointer to a Connection object to be returned to the pool and marked as unused. |
| a | pointer to a different Connection object; not guaranteed to still be connected! |
|
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.
| a | pointer to the connection |
References create().
Referenced by exchange(), and safe_grab().
|
protectedpure 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 |
|
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.
| pc | pointer to a Connection object to be returned to the pool and marked as unused. |
Referenced by mysqlpp::ScopedConnection::~ScopedConnection().
| void mysqlpp::ConnectionPool::remove | ( | const Connection * | pc | ) |
Removes the given connection from the pool.
If you mean to simply return a connection to the pool after you're finished using it, call release() instead. This method is primarily for error handling: you somehow have figured out that the connection is defective, so want it destroyed and removed from the pool. If you also want a different connection to retry your operation on, call exchange() instead.
| pc | pointer to a Connection object to be removed from the pool and destroyed |
Referenced by clear(), exchange(), and safe_grab().
|
virtual |
Grab a free connection from the pool, testing that it's connected before returning it.
This is just a wrapper around grab(), Connection::ping() and release(), and is thus less efficient than grab(). Use it only when it's possible for MySQL server connections to go away unexpectedly, such as when the DB server can be restarted out from under your application.
| a | pointer to the connection |
1.9.1