Class: OCI8::ConnectionPool

Inherits:
OCIHandle show all
Defined in:
lib/oci8/connection_pool.rb,
ext/oci8/connection_pool.c

Overview

Connection pooling is the use of a group (the pool) of reusable physical connections by several sessions to balance loads. See: Oracle Call Interface Manual

This is equivalent to Oracle JDBC Driver OCI Connection Pooling.

Note that this is different with generally called connection pooling. Generally connection pooling caches connections in a pool. When an application needs a new connection, a connection is got from the pool. So that the amount of time to establish a connection is reduced. However connection pooling in ruby-oci8 is different with above.

One Oracle connection is devided into two layers: One is physical connection such as TCP/IP. The other is logical connection which is used by an application. The connection pooling in ruby-oci8 caches physical connections in a pool, not logical connections. When an application needs a new connection, a logical connection is created via a physical connection, which needs time to establish a connection unlike generally called connection pooling. When an application sends a query via a logical connection, a physical connection is got from the pool. The physical connection returns to the pool automatically when the query finishes. As long as logical connections are used sequentially, only one physical connection is used. When an application sends queries at a time, it needs more than one physical connection because one physical connection cannot transmit more then one query at a time.

Example:

# Create a connection pool.
# The number of initial physical connections: 1
# The number of maximum physical connections: 5
# the connection increment parameter: 2
# username and password are required to establish an implicit primary session.
cpool = OCI8::ConnectionPool.new(1, 5, 2, username, password, database)

#   The number of physical connections: 1
#   The number of logical connections: 0

# Create a session.
# Pass the connection pool to the third argument.
conn1 = OCI8.new(username, password, cpool)

# One logical connection was created.
#   The number of physical connections: 1
#   The number of logical connections: 1

# Create another session.
conn2 = OCI8.new(username, password, cpool)

# Another logical connection was created.
#   The number of physical connections: 1
#   The number of logical connections: 2

# Use conn1 and conn2 sequentially
conn1.exec('...')
conn2.exec('...')

# Both logical connections use one physical connection.
#   The number of physical connections: 1
#   The number of logical connections: 2

thr1 = Thread.new do
   conn1.exec('...')
end
thr2 = Thread.new do
   conn2.exec('...')
end
thr1.join
thr2.join

# Logical connections cannot use one physical connection at a time.
# So that the number of physical connections is incremented.
#   The number of physical connections: 3
#   The number of logical connections: 2

conn1.logoff

# One logical connection was closed.
#   The number of physical connections: 3
#   The number of logical connections: 1

conn2.logoff

# All logical connections were closed.
#   The number of physical connections: 3
#   The number of logical connections: 0

Instance Method Summary collapse

Instance Method Details

#busy_count ⇒ Integer

Returns the number of busy physical connections.

Returns:

  • (Integer) 


142
143
144
 
# File 'lib/oci8/connection_pool.rb', line 142

def busy_count
  attr_get_ub4(OCI_ATTR_CONN_BUSY_COUNT)
end

#destroy ⇒ Object 



175
176
177
 
# File 'lib/oci8/connection_pool.rb', line 175

def destroy
  free
end

#incr ⇒ Integer

Returns the connection increment parameter.

Returns:

  • (Integer) 


170
171
172
 
# File 'lib/oci8/connection_pool.rb', line 170

def incr
  attr_get_ub4(OCI_ATTR_CONN_INCR)
end

#max ⇒ Integer

Returns the number of maximum physical connections.

Returns:

  • (Integer) 


163
164
165
 
# File 'lib/oci8/connection_pool.rb', line 163

def max
  attr_get_ub4(OCI_ATTR_CONN_MAX)
end

#min ⇒ Integer

Returns the number of minimum physical connections.

Returns:

  • (Integer) 


156
157
158
 
# File 'lib/oci8/connection_pool.rb', line 156

def min
  attr_get_ub4(OCI_ATTR_CONN_MIN)
end

#nowait=(val) ⇒ Object

Changes the behavior when all the connections in the pool are busy and the number of connections has already reached the maximum.

Parameters:

  • val (Boolean) 


135
136
137
 
# File 'lib/oci8/connection_pool.rb', line 135

def nowait=(val)
  attr_set_ub1(OCI_ATTR_CONN_NOWAIT, val ? 1 : 0)
end

#nowait? ⇒ Boolean

If true, an error is thrown when all the connections in the pool are busy and the number of connections has already reached the maximum. Otherwise the call waits till it gets a connection. The default value is false.

Returns:

  • (Boolean) 


126
127
128
 
# File 'lib/oci8/connection_pool.rb', line 126

def nowait?
  attr_get_ub1(OCI_ATTR_CONN_NOWAIT) != 0
end

#open_count ⇒ Integer

Returns the number of open physical connections.

Returns:

  • (Integer) 


149
150
151
 
# File 'lib/oci8/connection_pool.rb', line 149

def open_count
  attr_get_ub4(OCI_ATTR_CONN_OPEN_COUNT)
end

#reinitialize(min, max, incr) ⇒ Object

Changes the the number of minimum connections, the number of maximum connections and the connection increment parameter.



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'ext/oci8/connection_pool.c', line 168

static VALUE oci8_cpool_reinitialize(VALUE self, VALUE conn_min, VALUE conn_max, VALUE conn_incr)
{
    oci8_cpool_t *cpool = TO_CPOOL(self);
    OraText *pool_name;
    sb4 pool_name_len;

    /* check arguments */
    Check_Type(conn_min, T_FIXNUM);
    Check_Type(conn_max, T_FIXNUM);
    Check_Type(conn_incr, T_FIXNUM);

    chker2(OCIConnectionPoolCreate(oci8_envhp, oci8_errhp, cpool->base.hp.poolhp,
                                   &pool_name, &pool_name_len, NULL, 0, 
                                   FIX2UINT(conn_min), FIX2UINT(conn_max),
                                   FIX2UINT(conn_incr),
                                   NULL, 0, NULL, 0, OCI_CPOOL_REINITIALIZE),
           &cpool->base);
    return self;
}

#timeout ⇒ Integer

Connections idle for more than this time value (in seconds) are terminated, to maintain an optimum number of open connections. If it is zero, the connections are never timed out. The default value is zero.

Note: Shrinkage of the pool only occurs when there is a network round trip. If there are no operations, then the connections stay alive.

Returns:

  • (Integer) 


111
112
113
 
# File 'lib/oci8/connection_pool.rb', line 111

def timeout
  attr_get_ub4(OCI_ATTR_CONN_TIMEOUT)
end

#timeout=(val) ⇒ Object

Changes the timeout in seconds to terminate idle connections.

Parameters:

  • val (Integer) 


118
119
120
 
# File 'lib/oci8/connection_pool.rb', line 118

def timeout=(val)
  attr_set_ub4(OCI_ATTR_CONN_TIMEOUT, val)
end