CORAL connection service configuration

This page, under construction, reflects my current understanding of what CORAL is doing. It is based on the reverse engineering of effects observed in tests performed several months ago, that I may have misinterpreted or forgotten. More tests and code analysis are necessary to fully confirm what is described here.

Check also the original documentation for the CORAL ConnectionService component.

CORAL connection pool configuration

CORAL distinguishes between database connections and database sessions.

  • A CORAL connection represents a physical connection (a socket) between the client and the database.
  • A CORAL session represents a logical session allowing a user on the local client to interact with the remote database. Each session must be opened over an existing connection.
  • If connection sharing is disabled, each connection may host only 0 (idle) or 1 session. If connection sharing is enabled, each connection may host 0 (idle), 1 or more sessions.
  • Connections are created/opened before sessions and must be deleted/closed after sessions.

CORAL connections are managed by a connection pool.

  • Each connection is uniquely associated to a URL (a CORAL 'connection string'). Different URLs require different connections. For the same URL there can be more than one connections opened in the connection pool.
  • When a new session is created on a new URL, a new connection is created.
  • When a new session is created on a URL for which there are already connections in the connection pool, it can be created on an existing connection (if the connection is idle, or if connection sharing is enabled and the maximum number of sessions per connection has not been reached), or trigger the creation of a new connection for that URL.

Within the connection pool, connections have a limited lifetime.

  • When the last logical session is closed on a connection, the connection is said to be idle.
  • The connection timeout parameter determines the time after which an idle connection is considered expired. Expired connections can never be reused and are scheduled for deletion (to be cross checked...).

The cleanup of connections from the pool is managed either by the pool itself or by a separate pool automatic cleanup thread, which may enabled or disabled.

  • If the cleanup thread is enabled, it regularly checks for expired connections. Every pool automatic cleanup period, expired connections are deleted and removed from the pool.
  • In the main client thread, the pool also checks for expired connections whenever a new session is opened (or closed, too? to be cross-checked...), as well as when the pool is deleted at the end of the client job. Expired connections are deleted and removed from the pool, before creating the new required connection (to be cross-checked...). This is the only cleanup mechanism available if the clenup thread is disabled.
  • If the connection timeout parameter is set to 0, idle connections become immediately expired and are immediately deleted and removed from the pool. In this case, the automatic cleanup thread would be useless and is never started (even if it is set as 'enabled').

Connection timeout

As described above, the connection timeout parameter determines after how long an idle physical connection is marked as expired and becomes a candidate to be cleaned up (i.e. closed) by the connection pool or the pool automatic cleanup thread.

This parameter can be set using setConnectionTimeOut() and checked using connectionTimeOut().

The connection timeout parameter is NOT the connection pool automatic cleanup period! The latter is described in the next section.

Automatic cleanup thread

The pool automatic cleanup thread can be enabled and disabled using enablePoolAutomaticCleanUp() and disablePoolAutomaticCleanUp() and checked using isPoolAutomaticCleanUpEnabled().

Note that there will be NO automatic cleanup thread if connectionTimeOut() is 0, even if isPoolAutomaticCleanUpEnabled() is true! See the implementation coral::ConnectionService::ConnectionPool::startPool(): the thread is not started if this parameter is 0. In other words:

  • if connection timeout is 0, this implies that the connection cleanup thread is disabled (it is therefore recommended not to set connection timeout to 0 and enable the connection pool cleanup thread, as the result may be undefined)
  • if the connection cleanup thread is disabled, this does NOT imply that the connection timeout is 0: as mentioned above, an idle connection can still be reused in this case, even in a single threaded program, if a new session is opened on it before the connection becomes expired (question, is the thread started if the value isPoolAutomaticCleanUpEnabled() is changed half-way in an application?)

For these reasons, the connection service is often configured to have BOTH the cleanup thread disabled AND the timeout set to 0 (the latter would be enough, but not the former). One example is Marco's patch in COOL tools (see task #3546). Another example was observed in test prepared for related bug #71449 about releasing SQLite files, where the result of the test was much clearer after setting ALSO the connection timeout to 0, having already disabled the cleanup thread (see this cvs diff).

Other useful tests for these parameters are described in bug #76501, in bug #87164, in the NetworkGlitch test and in the MiscellaneousBugs test.

Connection pool automatic cleanup period

The connection pool automatic cleanup period determines the frequency with which the connection pool checks whether any of its idle connections are expired and can be closed.

Until CORAL_2_3_11 included there was no way to change the default value of this parameter (which was hardcoded to 10 seconds). More recently the possibility to change the default value via the environment variable CORAL_CONNECTIONPOOL_CLEANUPPERIOD has been added (see bug #72002).

-- AndreaValassi - 29-Aug-2010

Edit | Attach | Watch | Print version | History: r5 < r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r2 - 2011-09-28 - AndreaValassi
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    Persistency All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback