From 1f7f9295bf4baf2b86ef5884b1c9929d0b31f758 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Tue, 30 Aug 2011 09:15:22 +0200 Subject: Document new connection constructor and create() factory callback --- NEWS | 7 +++ doc/manual.xhtml | 134 ++++++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 126 insertions(+), 15 deletions(-) diff --git a/NEWS b/NEWS index fac6eb6..41aa273 100644 --- a/NEWS +++ b/NEWS @@ -51,6 +51,13 @@ Version 1.6.0 more information, refer to Section 3.4, "Transactions" in the ODB manual. + * All the concrete connection classes now have a second constructor which + allows the creation of a connection instance from an already established + underlying connection handle. The connection_pool_factory and, in case of + SQLite, single_connection_factory now have a virtual create() function + that can be overridden to implement custom connection establishment and + configuration. + * Support for specifying the client character set for the MySQL database. For more information, refer to Section 11.2, "MySQL Database Class" in the ODB manual. diff --git a/doc/manual.xhtml b/doc/manual.xhtml index 25dddc7..ba8b309 100644 --- a/doc/manual.xhtml +++ b/doc/manual.xhtml @@ -8420,6 +8420,9 @@ namespace odb class connection: public odb::connection { public: + connection (database&); + connection (database&, MYSQL*); + MYSQL* handle (); }; @@ -8430,9 +8433,13 @@ namespace odb

For more information on the odb::connection interface, - refer to Section 3.5, "Connections". The - handle() accessor returns the native MySQL handle - corresponding to the connection.

+ refer to Section 3.5, "Connections". The first + overloaded mysql::connection constructor establishes a + new MySQL connection. The second constructor allows us to create + a connection instance by providing an already connected + native MySQL handle. Note that the connection + instance assumes ownership of this handle. The handle() + accessor returns the MySQL handle corresponding to the connection.

The mysql::connection_factory abstract class has the following interface:

@@ -8501,12 +8508,26 @@ namespace odb public: connection_pool_factory (std::size_t max_connections = 0, std::size_t min_connections = 0, - bool ping = true) + bool ping = true); + + protected: + class pooled_connection: public connection + { + public: + pooled_connection (database_type&); + pooled_connection (database_type&, MYSQL*); + }; + + typedef details::shared_ptr<pooled_connection> pooled_connection_ptr; + + virtual pooled_connection_ptr + create (); }; }; -

The max_connections argument specifies the maximum +

The max_connections argument in the + connection_pool_factory constructor specifies the maximum number of concurrent connections that this pool factory will maintain. Similarly, the min_connections argument specifies the minimum number of available connections that @@ -8548,6 +8569,12 @@ namespace odb factory detects that the connection has been terminated, it silently closes it and tries to find or create another connection instead.

+

The create() virtual function is called whenever the + pool needs to create a new connection. By deriving from the + connection_pool_factory class and overriding this + function we can implement custom connection establishment + and configuration.

+

If you pass NULL as the connection factory to one of the database constructors, then the connection_pool_factory instance will be @@ -8944,6 +8971,9 @@ namespace odb class connection: public odb::connection { public: + connection (database&, int extra_flags = 0); + connection (database&, sqlite3*); + transaction begin_immediate (); @@ -8960,14 +8990,23 @@ namespace odb

For more information on the odb::connection interface, - refer to Section 3.5, "Connections". The - begin_immediate() and begin_exclusive() + refer to Section 3.5, "Connections". The first + overloaded sqlite::connection constructor opens + a new SQLite connection. The extra_flags argument can + be used to specify extra sqlite3_open_v2() flags + that are combined with the flags specified in the + sqlite::database constructor. The second constructor + allows us to create a connection instance by providing + an already open native SQLite handle. Note that the + connection instance assumes ownership of this handle.

+ +

The begin_immediate() and begin_exclusive() functions allow us to start an immediate and an exclusive SQLite transaction on the connection, respectively. Their semantics are equivalent to the corresponding functions defined in the sqlite::database class (Section 12.2, "SQLite Database Class"). The handle() accessor - returns the native SQLite handle corresponding to the connection.

+ returns the SQLite handle corresponding to the connection.

The sqlite::connection_factory abstract class has the following interface:

@@ -9022,10 +9061,28 @@ namespace odb { public: single_connection_factory (); + + protected: + class single_connection: public connection + { + public: + single_connection (database_type&); + single_connection (database_type&, MYSQL*); + }; + + typedef details::shared_ptr<single_connection> single_connection_ptr; + + virtual single_connection_ptr + create (); }; }; +

The create() virtual function is called when the + factory needs to create the connection. By deriving from the + single_connection_factory class and overriding this + function we can implement custom connection establishment + and configuration.

The new_connection_factory class creates a new connection whenever one is requested. When a connection is no @@ -9058,12 +9115,26 @@ namespace odb { public: connection_pool_factory (std::size_t max_connections = 0, - std::size_t min_connections = 0) + std::size_t min_connections = 0); + + protected: + class pooled_connection: public connection + { + public: + pooled_connection (database_type&, int extra_flags = 0); + pooled_connection (database_type&, sqlite3*); + }; + + typedef details::shared_ptr<pooled_connection> pooled_connection_ptr; + + virtual pooled_connection_ptr + create (); }; }; -

The max_connections argument specifies the maximum +

The max_connections argument in the + connection_pool_factory constructor specifies the maximum number of concurrent connections that this pool factory will maintain. Similarly, the min_connections argument specifies the minimum number of available connections that @@ -9096,6 +9167,12 @@ namespace odb the pool will never close a connection and instead maintain all the connections that were ever created.

+

The create() virtual function is called whenever the + pool needs to create a new connection. By deriving from the + connection_pool_factory class and overriding this + function we can implement custom connection establishment + and configuration.

+

By default, connections created by new_connection_factory and connection_pool_factory enable the SQLite shared cache mode and use the unlock notify functionality to aid concurrency. To @@ -9642,6 +9719,9 @@ namespace odb class connection: public odb::connection { public: + connection (database&); + connection (database&, PGconn*); + PGconn* handle (); }; @@ -9652,9 +9732,13 @@ namespace odb

For more information on the odb::connection interface, - refer to Section 3.5, "Connections". The - handle() accessor returns the native PostgreSQL handle - corresponding to the connection.

+ refer to Section 3.5, "Connections". The first + overloaded pgsql::connection constructor establishes a + new PostgreSQL connection. The second constructor allows us to create + a connection instance by providing an already connected + native PostgreSQL handle. Note that the connection + instance assumes ownership of this handle. The handle() + accessor returns the PostgreSQL handle corresponding to the connection.

The pgsql::connection_factory abstract class has the following interface:

@@ -9722,12 +9806,26 @@ namespace odb { public: connection_pool_factory (std::size_t max_connections = 0, - std::size_t min_connections = 0) + std::size_t min_connections = 0); + + protected: + class pooled_connection: public connection + { + public: + pooled_connection (database_type&); + pooled_connection (database_type&, PGconn*); + }; + + typedef details::shared_ptr<pooled_connection> pooled_connection_ptr; + + virtual pooled_connection_ptr + create (); }; }; -

The max_connections argument specifies the maximum +

The max_connections argument in the + connection_pool_factory constructor specifies the maximum number of concurrent connections that this pool factory will maintain. Similarly, the min_connections argument specifies the minimum number of available connections that @@ -9760,6 +9858,12 @@ namespace odb the pool will never close a connection and instead maintain all the connections that were ever created.

+

The create() virtual function is called whenever the + pool needs to create a new connection. By deriving from the + connection_pool_factory class and overriding this + function we can implement custom connection establishment + and configuration.

+

If you pass NULL as the connection factory to one of the database constructors, then the connection_pool_factory instance will be created by default -- cgit v1.1