PPL6-Icon Patrick's Programming Library Version 6.4.21 - Dokumentation
ppl6::db::Pool Klassenreferenz

Klasse zur Verwaltung von Datenbank-Verbindungen. Mehr ...

Öffentliche Methoden

 Pool ()
 Konstruktor der Klasse. Mehr ...
 
 ~Pool ()
 Destruktor der Klasse. Mehr ...
 
void CheckPool ()
 Datenbank-Pools überprüfen. Mehr ...
 
int ClearFreePool (bool destroy=false)
 Alle freien Datenbank-Verbindungen trennen. Mehr ...
 
int ClearUsedPool (bool destroy=false)
 Alle benutzen Datenbank-Verbindungen trennen. Mehr ...
 
int Destroy (Database *db)
 Datenbankverbindung löschen. Mehr ...
 
DatabaseGet (bool wait=false, int ms=0)
 Datenbank-Connect holen. Mehr ...
 
int GetStatus (CAssocArray &status)
 Status sämtlicher Datenbank-Verbindungen auslesen. Mehr ...
 
int Release (Database *db)
 Datenbankverbindung in den Pool zurückgeben. Mehr ...
 
int SetConnectParams (CAssocArray &connect)
 Datenbank-Pool mit den Connect-Parametern initialisieren. Mehr ...
 
void SetLogfile (CLog *log)
 Logging aktivieren. Mehr ...
 
int SetName (const CString &Name)
 Namen des Pools festlegen. Mehr ...
 
int SetOption (const CString &Name, const CString &Value)
 Pool-spezifische Option setzen. Mehr ...
 
int SetOptions (CAssocArray &options)
 Pool-spezifische Optionen anhand eines Assoziativen Arrays setzen. Mehr ...
 

Private Methoden

int CalcHash (CString &hash, CAssocArray &param)
 Berechnet Hash aus Connect-Parametern. Mehr ...
 
DatabaseNew ()
 Interne Funktion zum Erstellen eines neuen Datenbank-Connects. Mehr ...
 

Private Attribute

CAssocArray ConnectParam
 Enthält eine Kopie der Connect-Parameter, die über die Funktion Pool::SetConnectParams gesetzt werden. Mehr ...
 
CGenericList Free
 Eine Liste, die alle derzeit freien Datenbank-Connects enthält. Mehr ...
 
int Grow
 Gibt an, wieviele neue Connects gleichzeitig erstellt werden sollen, wenn keine freien Connects mehr im Pool sind oder Pool::MinSpare unterschritten wurde. Es wird immer mindestens eine neue Verbindung erstellt, aber nicht mehr als Pool::MaxSpare. Default: 1. Mehr ...
 
CString Hash
 Ein MD5-Hash über die Connect-Parameter, der bei Aufruf der Funktion Pool::SetConnectParams gebildet wird. Mehr ...
 
int Id
 Eine eindeutige Id, die bei Verwendung des Pools durch die Klasse PoolEx vergeben wird. Mehr ...
 
bool IsInit
 Wird auf true gesetzt, wenn die Connect-Parameter über die Funktion Pool::SetConnectParams übergeben wurden. Mehr ...
 
int KeepAlive
 Gibt an, nach wieviel Sekunden ein Ping an eine freie Datenbank-Verbindung geschickt werden soll, um sicherzustellen, dass die Verbindung aufrecht erhalten bleibt. Ein Wert von 0 bedeutet, dass kein KeepAlive geschickt wird. Default: 60 (1 Minute). Mehr ...
 
double LastCheck
 Wird von der Klasse PoolEx verwendet und enthält den Timestamp der letzten Überprüfung des Pools. Mehr ...
 
CLogLog
 Pointer auf eine Logklasse, der über die Funktion Pool::SetLogfile gesetzt wird. Enthält die Variable einen Wert != 0 ist das Logging aktiviert. Mehr ...
 
int Max
 Gibt an, wieviele Connects maximal geöffnet werden dürfen. Default: 0 (uneingeschränkt) Mehr ...
 
int MaxSpare
 Gibt an, wieviele Freie Connects maximal vorgehalten werden sollen. Sind mehr Connects frei, werden diese nach erreichen des Timeouts abgebaut. Default: 0. Mehr ...
 
int Min
 Gibt an, wieviele Connects mindestens im Pool enthalten sein sollen. Mehr ...
 
int MinSpare
 Gibt an, wieviele Freie Connects minimal vorgehalten werden sollen. Default: 0. Mehr ...
 
CMutex Mutex
 Ein Muetx, der zur Gewährleistung der Threadsicherheit von allen Funktionen verwendet wird. Mehr ...
 
CString Name
 Der Name des Pools, der über die Funktion Pool::SetName festgelegt werden kann. Mehr ...
 
int Timeout
 Gibt an, nach welcher Zeit in Sekunden eine unbenutzte Verbindung abgebaut werden soll. Default: 300 (5 Minuten) Mehr ...
 
CGenericList Used
 Eine Liste, die alle gerade in Verwendung befindlichen Datenbank-Connects enthält. Mehr ...
 

Freundbeziehungen

class PoolEx
 
class PoolTree
 

Verwandte Funktionen

(Es handelt sich hierbei nicht um Elementfunktionen.)

static int PoolDestroyFunction (void *item, void *data)
 Löschen von Datenbank-Connects im Pool. Mehr ...
 

Ausführliche Beschreibung

Include:
#include <ppl6-db.h>
Beschreibung:
Mit dieser Klasse können beliebig viele Connects zu einer bestimmten Datenbank innerhalb eines Pools verwaltet werden.
Verwendung:
Bevor der Pool verwendet werden kann, muss er zunächst einmal wissen, welche Datenbank er verwenden soll. Dazu muss die Funktion Pool::SetConnectParams mit den entsprechenden Parametern in einem assoziativen Array aufgerufen werden. Die möglichen Parameter sind dabei die gleichen, wie beim Aufruf der Funktion Database::Connect. Optional können mit den Funktion Pool::SetOption oder Pool::SetOptions verschiedene Einstellungen zum verhalten des Pools verändert werden.
Nach der Initialisierung können anschließend mit der Funktion Pool::Get Datenbank-Verbindungen aus dem Pool geholt werden (der Pool sorgt selbst dafür, dass neue Verbindungen automatisch erstellt werden) und mit Pool::Release wieder in den Pool zurückgegeben werden. Mit Pool::Destroy kann eine Verbindung auch gelöscht werden, was zum Beispiel dann sinnvoll ist, wenn die Anwendung festgestellt hat, dass irgendwas nicht in Ordnung ist.
In regelmäßigen Abständen muß die Funktion Pool::CheckPool aufgerufen werden, am besten innerhalb eines Überwachungsthreads. Die Funktion prüft die vorhandenen Verbindungen, löscht überflüssige Verbindungen oder baut neue auf, wenn nicht mehr genug freie im Pool vorhanden sind.
Beispiel:
int DB_Pool_Example1() {
// Connect-Parameter festlegen
param.Set("type","sybase");
param.Set("host","database.example.com");
param.Set("port","1234");
param.Set("user","demo");
param.Set("password","demo");
param.Set("dbname","test");
// Pool erzeugen
// Pool mit den Connect-Parametern initialisieren
if (!Pool.SetConnectParams(param)) {
return;
}
// Verbindung aus dem Pool holen
ppl6::db::Database *db=Pool.Get();
if (!db) {
return;
}
// Verbindung verwenden
...
// Verbindung an den Pool zurückgeben
if (!Pool.Release(db)) {
return;
}
} // EOF

Beschreibung der Konstruktoren und Destruktoren

ppl6::db::Pool::Pool ( )
Beschreibung:
Der Konstruktor setzt diverse Parameter auf ihren Default-Wert:
  • min=0: Gibt an, wieviele Connects mindestens im Pool enthalten sein sollen
  • max=0: Gibt an, wieviele Connects maximal geöffnet werden dürfen. Default = uneingeschränkt
  • minspare=0: Gibt an, wieviele Freie Connects minimal vorgehalten werden sollen
  • maxspare=0: Gibt an, wieviele Freie Connects maximal vorgehalten werden sollen. Sind mehr Connects frei, werden diese nach erreichen des Timeouts abgebaut.
  • grow=1: Gibt an, wieviele neue Connects gleichzeitig erstellt werden sollen, wenn keine freien Connects mehr im Pool sind oder MinSpare unterschritten wurde. Es wird immer mindestens eine neue Verbindung erstellt, aber nicht mehr als maxspare.
  • timeout=300: Gibt an, nach welcher Zeit in Sekunden eine unbenutzte Verbindung abgebaut werden soll. Default = 300 (5 Minuten)
  • keepalive=60: Gibt an, nach wieviel Sekunden ein Ping an eine freie Datenbank-Verbindung geschickt werden soll, um sicherzustellen, dass die Verbindung aufrecht erhalten bleibt. Ein Wert von 0 bedeutet, dass kein KeepAlive geschickt wird. Default = 60 (1 Minute).
ppl6::db::Pool::~Pool ( )
Beschreibung:
Der Destruktor sorgt dafür, dass alle Datenbank-Connects sauber getrennt werden.

Dokumentation der Elementfunktionen

int ppl6::db::Pool::CalcHash ( CString hash,
CAssocArray param 
)
private
Beschreibung:
Diese Funktion berechnet aus den Connect-Parametern einen eindeutigen MD5-Hash.
Parameter
[out]hashZielstring, in dem der Hash gespeichert werden soll
[in]paramEin Assoziatives Array, in dem die Connect-Parameter enthalten sind.
Rückgabe
Bei Erfolg liefert die Funktion true (1) zurück, sonst false(0).
Bemerkungen
Die Funktion verwendet folgende Keys, um den MD5-Hash zu erstellen:
  • type
  • interface (sofern angegeben)
  • host
  • port
  • user
  • password
  • dbname
  • charset
void ppl6::db::Pool::CheckPool ( )
Beschreibung:
Diese Funktion sollte regelmäßig innerhalb eines Überwachungsthreads aufgerufen werden, um die im Pool vorhandenen Verbindungen zu überprüfen und zu expiren. Die Funktion schickt regelmäßig an alle unbenutzen Verbindungen einen Ping (KeepAlive) und löscht Verbindungen, die nicht mehr reagieren.
Bei sehr großen Pools wird empfohlen diese Funktion innerhalb eines eigenen Threads aufzurufen, um andere Funktionen nicht zu blockieren.
int ppl6::db::Pool::ClearFreePool ( bool  destroy = false)
Beschreibung:
Mit dieser Funktion werden alle unbenutzen Datenbank-Verbindungen getrennt. Diese Funktion sollte bei Beendigung eines Programms aufgerufen werden, um alle Verbindungen korrekt zu trennen. Sie kann aber auch im Laufenden Betrieb aufgerufen werden, um den Pool zu leeren.
Parameter
[in]destroyOptionales Flag. Ist es auf true gesetzt, werden die Datenbank- Klassen mit delete gelöscht. Falls nicht (default), werden die Connects nur aus dem Pool gelöscht, bleiben aber bestehen.
Rückgabe
Die Funktion liefert immer true (1) zurück.
int ppl6::db::Pool::ClearUsedPool ( bool  destroy = false)
Beschreibung:
Mit dieser Funktion werden alle Datenbank-Verbindungen getrennt, die gerade in Benutzung sind. Diese Funktion sollte - wenn überhaupt - nur bei Beendigung eines Programms aufgerufen werden. Bei Aufruf im Laufenden Betrieb könnte es zu unvorhersehbaren Abstürzen kommen.
Parameter
[in]destroyOptionales Flag. Ist es auf true gesetzt, werden die Datenbank- Klassen mit delete gelöscht. Falls nicht (default), werden die Connects nur aus dem Pool gelöscht, bleiben aber bestehen.
Rückgabe
Die Funktion liefert immer true (1) zurück.
int ppl6::db::Pool::Destroy ( Database db)
Beschreibung:
Mit dieser Funktion wird eine zuvor mit Pool::Get geholte Verbindung getrennt und aus dem Pool gelöscht.
Parameter
[in]dbPointer auf eine Datenbankverbindung. Diese muss zuvor mit der Funktion Pool::Get geholt worden sein.
Rückgabe
Konnte die Verbindung erfolgreich gelöscht werden, liefert die Funktion true (1) zurück, sonst false (0). Ein Fehler kann nur auftreten, wenn die Verbindung nicht aus dem gleichen Pool stammt.
Database * ppl6::db::Pool::Get ( bool  wait = false,
int  ms = 0 
)
Beschreibung:
Mit dieser Funktion wird eine Verbindung aus dem Datenbank-Pool geholt oder eine neue erstellt.
Parameter
[in]waitOptionales Flag, das angibt, ob die Funktion warten soll, wenn das Maximum an Connects für diesen Pool bereits erreicht ist.
[in]msEin optionaler Wert, der in Kombination mit dem wait-Flag angibt, wieviele Millisekunden gewartet werden soll, bevor mit einem Timeout abgebrochen wird. Ist der Wert 0, wird endlos gewartet.
Rückgabe
Die Funktion gibt entweder ein gültiges Handle für die Datenbank zurück, oder im Fehlerfall NULL.
Bemerkungen
Die Funktion prüft immer, ob die Datenbankverbindung noch funktionsfähig ist, indem ein Ping geschickt wird. Es ist daher sichergestellt, dass nur funktionierende Verbindungen zurückgegeben werden.
int ppl6::db::Pool::GetStatus ( CAssocArray status)
Beschreibung:
Mit dieser Funktion kann der Status sämtlicher Datenbank-Verbindungen ausgelesen und in das übergebene assoziative Array status gespeichert werden.
Parameter
[out]statusEin assoziatives Array, in dem der Status aller Connects gespeichert werden soll
Rückgabe
Bei Erfolg gibt die Funktion 1 zurück, im Fehlerfall 0
Database * ppl6::db::Pool::New ( )
private
Beschreibung:
Diese Funktion wird intern von Pool::Get und Pool::CheckPool aufgerufen, um eine neue Datenbank-Verbindung zu erstellen.
Rückgabe
Die Funktion liefert einen Pointer auf eine neue Datenbankverbindung zurück, sofern eine neue Verbindung aufgebaut werden konnte, oder NULL im Fehlerfall. Dabei wird zunächst geprüft, ob das Maximum an Verbindungen - sofern definiert - bereits erreicht ist. Ist dies der Fall, wird eine Fehlermeldung zurückgegeben.
Bemerkungen
Die Funktion geht davon aus, dass der Mutex der Klasse bereits gesetzt ist.
int ppl6::db::Pool::Release ( Database db)
Beschreibung:
Mit dieser Funktion wird eine zuvor mit Pool::Get geholte Verbindung wieder zurück in den Pool gestellt.
Parameter
[in]dbPointer auf eine Datenbankverbindung. Diese muss zuvor mit der Funktion Pool::Get geholt worden sein.
Rückgabe
Konnte die Verbindung erfolgreich in den Pool zurückgestellt werden, liefert die Funktion true (1) zurück, sonst false (0).
Bemerkungen
Wurde zwischenzeitlich die Init-Funktion mit veränderten Connect-Parametern aufgerufen, wird die Verbindung nicht zurück in den Pool gestellt, sondern gelöscht.
int ppl6::db::Pool::SetConnectParams ( CAssocArray connect)
Beschreibung:
Mit dieser Funktion werden die Connect-Parameter für die Datenbank festgelegt und der Pool somit initialisiert. Mit der Funktionen Pool::SetOption oder Pool::SetOptions können weitere Pool-spezifische Optionen gesetzt werden. Mit der Funktion Pool::SetName kann dem Pool ein Name zugewiesen werden.
Parameter
[in]connectDie Connect-Parameter in einem Assoziativen Array, wie sie von der Funktion ppl6::db::Connect, bzw. der jeweiligen Datenbank-Klasse unterstützt werden.
Rückgabe
Die Funktion liefert bei Erfolg true (1) zurück, sonst false (0).
void ppl6::db::Pool::SetLogfile ( CLog log)
Beschreibung:
Mit dieser Funktion wird das Logging der Klasse aktiviert oder deaktiviert werden. Ist es aktiviert, schreibt jeder Funktionsaufruf eine oder mehrere Zeilen in die angegebene Logfile-Klasse.
Parameter
[in]logPointer auf eine Klasse vom Typ CLog, um das Logging zu aktivieren, oder NULL um es zu deaktivieren.
int ppl6::db::Pool::SetName ( const CString Name)
Beschreibung:
Mit Aufruf dieser Funktion wird der Name des Datenbank-Pools festgelegt. Der Name wird an verschiedenen Stellen verwendet, meist in Listen oder Status-Ausgaben.
Parameter
[in]NameDer Name des Pools
Rückgabe
Die Funktion gibt immer 1 zurück
int ppl6::db::Pool::SetOption ( const CString Name,
const CString Value 
)
Beschreibung:
Mit dieser Funktion können Pool-spezifische Optionen gesetzt werden. Folgende Optionen können verändert werden:
  • min: Gibt an, wieviele Connects mindestens im Pool enthalten sein sollen. Default = 0
  • max: Gibt an, wieviele Connects maximal geöffnet werden dürfen. Default = 0 = uneingeschränkt
  • minspare: Gibt an, wieviele Freie Connects minimal vorgehalten werden sollen. Default = 0
  • maxspare: Gibt an, wieviele Freie Connects maximal vorgehalten werden sollen. Sin mehr Connects frei, werden diese nach erreichen des Timeouts abgebaut. Default = 0
  • grow: Gibt an, wieviele neue Connects gleichzeitig erstellt werden sollen, wenn keine freien Connects mehr im Pool sind oder MinSpare unterschritten wurde. Es wird immer mindestens eine neue Verbindung erstellt, aber nicht mehr als maxspare. Default = 1
  • timeout: Gibt an, nach welcher Zeit in Sekunden eine unbenutzte Verbindung abgebaut werden soll. Default = 300 (5 Minuten)
  • keepalive: Gibt an, nach wieviel Sekunden ein Ping an eine freie Datenbank-Verbindung geschickt werden soll, um sicherzustellen, dass die Verbindung aufrecht erhalten bleibt. Ein Wert von 0 bedeutet, dass kein KeepAlive geschickt wird. Default = 60 (1 Minute).
Parameter
[in]NameEin String, der den Namen der Option enthält.
[in]ValueEin String mit dem Wert der Option.
Rückgabe
Die Funktion liefert bei Erfolg true (1) zurück, sonst false (0).
int ppl6::db::Pool::SetOptions ( CAssocArray options)
Beschreibung:
Mit dieser Funktion können Pool-spezifische Optionen mittels eines Assoziativen Arrays gesetzt werden. Dabei wird das Array durchwandert und für jedes Element die Funktion Pool::SetOption aufgerufen
Parameter
[in]optionsEin Assoziatives Array mit zusätzlichen Optionen für die Verwaltung des Pools. Die möglichen Werte sind in der Funktion Pool::SetOption beschrieben.
Rückgabe
Die Funktion liefert bei Erfolg true (1) zurück, sonst false (0).

Freundbeziehungen und Funktionsdokumentation

static int PoolDestroyFunction ( void *  item,
void *  data 
)
related
Beschreibung:
Diese interne statische Funktion wird benutzt, um Datenbank-Connects im Pool zu löschen. Sie wird von den Listen Pool::Used und Pool::Free aufgerufen.
Parameter
[in]itemDer zu löschende Datenbank-Connect
[in]dataPointer auf die Pool-Klasse, wird jedoch nicht verwendet
Rückgabe
Liefert immer 1 zurück
friend class PoolEx
friend
friend class PoolTree
friend

Dokumentation der Datenelemente

ppl6::db::Pool::ConnectParam
private
ppl6::db::Pool::Free
private
ppl6::db::Pool::Grow
private
ppl6::db::Pool::Hash
private
ppl6::db::Pool::Id
private
ppl6::db::Pool::IsInit
private
ppl6::db::Pool::KeepAlive
private
ppl6::db::Pool::LastCheck
private
ppl6::db::Pool::Log
private
ppl6::db::Pool::Max
private
ppl6::db::Pool::MaxSpare
private
ppl6::db::Pool::Min
private
ppl6::db::Pool::MinSpare
private
ppl6::db::Pool::Mutex
private
ppl6::db::Pool::Name
private
ppl6::db::Pool::Timeout
private
ppl6::db::Pool::Used
private

Die Dokumentation für diese Klasse wurde erzeugt aufgrund der Dateien: