Connection Pools


Detailed Description

OCILIB support the OCI features Connection pooling introduced in Oracle 9i.

Note:
OCILIB implements its own pooling mechanism for Oracle 8i.
Example
#include "ocilib.h"

#define MAX_THREADS 50
#define MAX_CONN    10
#define SIZE_STR   260

void worker(OCI_Thread *thread, void *data)
{
    OCI_Connection *cn = OCI_ConnPoolGetConnection(data);
    char str[SIZE_STR+1];

    /* application work here */

    str[0] = 0;

    OCI_Immediate(cn, "select to_char(sysdate, 'YYYYMMDD HH24:MI:SS') from dual", OCI_ARG_TEXT, str);
    
    printf("%s\n", str);
    
    /* ... */

    OCI_ConnectionFree(cn);
}

int main(void)
{
    OCI_Thread *th[MAX_THREADS];
    OCI_ConnPool *pool;

    int i;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT | OCI_ENV_THREADED))
        return EXIT_FAILURE;

    /* create pool */

    pool = OCI_ConnPoolCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT, 0, MAX_CONN, 1);

    /* create threads */

    for (i = 0; i < MAX_THREADS; i++)
    {
        th[i] = OCI_ThreadCreate();
        OCI_ThreadRun(th[i], worker, pool);
    }
  
    /* wait for threads and cleanup */

    for (i = 0; i < MAX_THREADS; i++)
    {
       OCI_ThreadJoin(th[i]);
       OCI_ThreadFree(th[i]);
    }

    OCI_ConnPoolFree(pool);

    OCI_Cleanup();

 
    return EXIT_SUCCESS;
}


Functions

OCI_EXPORT OCI_ConnPool *OCI_API OCI_ConnPoolCreate (const mtext *db, const mtext *user, const mtext *pwd, unsigned int mode, unsigned int min_con, unsigned int max_con, unsigned int incr_con)
 Create a Connection pool.
OCI_EXPORT boolean OCI_API OCI_ConnPoolFree (OCI_ConnPool *pool)
 Destroy a Connection pool object.
OCI_EXPORT OCI_Connection *OCI_API OCI_ConnPoolGetConnection (OCI_ConnPool *pool)
 Get a connection from the pool.
OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetTimeout (OCI_ConnPool *pool)
 Get the idle connection timeout.
OCI_EXPORT boolean OCI_API OCI_ConnPoolSetTimeout (OCI_ConnPool *pool, unsigned int value)
 Set the idle connection timeout.
OCI_EXPORT boolean OCI_API OCI_ConnPoolGetlGetNoWait (OCI_ConnPool *pool)
 Get the waiting mode used when no more connections are available from the pool.
OCI_EXPORT boolean OCI_API OCI_ConnPoolSetNoWait (OCI_ConnPool *pool, boolean value)
 Set the waiting mode used when no more connections are available from the pool.
OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetBusyCount (OCI_ConnPool *pool)
 Return the current number of busy connections.
OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetOpenedCount (OCI_ConnPool *pool)
 Return the current number of opened connections.
OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetMin (OCI_ConnPool *pool)
 Return the minimum number of connections that can be opened to the database.
OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetMax (OCI_ConnPool *pool)
 Return the maximum number of connections that can be opened to the database.
OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetIncrement (OCI_ConnPool *pool)
 Return the increment for connections to be opened to the database when the pool is not full.


Function Documentation

OCI_EXPORT OCI_ConnPool* OCI_API OCI_ConnPoolCreate ( const mtext *  db,
const mtext *  user,
const mtext *  pwd,
unsigned int  mode,
unsigned int  min_con,
unsigned int  max_con,
unsigned int  incr_con 
)

Create a Connection pool.

Parameters:
db - Oracle Service Name
user - Oracle User name
pwd - Oracle User password
mode - Session mode
min_con - minimum number of connections that can be opened.
max_con - maximum number of connections that can be opened.
incr_con - next increment for connections to be opened
Possible values for parameter mode :

Note:
External credentials are supported by supplying a null value for the 'user' and 'pwd' parameters If the param 'db' is NULL then a connection to the default local DB is done

Returns:
Connection pool handle on success or NULL on failure

Definition at line 110 of file connpool.c.

References OCI_ConnPool::cons, OCI_ConnPool::db, OCI_ConnPool::err, OCI_ConnPool::handle, OCI_ConnPool::incr, OCI_ConnPool::max, OCI_ConnPool::min, OCI_ConnPool::mode, OCI_ConnPool::mutex, OCI_ConnPool::name, OCI_ConnPoolFree(), OCI_ConnPool::pwd, and OCI_ConnPool::user.

OCI_EXPORT boolean OCI_API OCI_ConnPoolFree ( OCI_ConnPool pool  ) 

Destroy a Connection pool object.

Parameters:
pool - Connection pool handle
Returns:
TRUE on success otherwise FALSE

Definition at line 272 of file connpool.c.

Referenced by OCI_ConnPoolCreate().

OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetBusyCount ( OCI_ConnPool pool  ) 

Return the current number of busy connections.

Parameters:
pool - Connection pool handle

Definition at line 473 of file connpool.c.

References OCI_ConnPool::err, OCI_ConnPool::handle, and OCI_ConnPool::nb_busy.

OCI_EXPORT OCI_Connection* OCI_API OCI_ConnPoolGetConnection ( OCI_ConnPool pool  ) 

Get a connection from the pool.

Parameters:
pool - Connection pool handle
Note:
Returns:
Connection handle otherwise NULL on failure

Definition at line 293 of file connpool.c.

References OCI_ConnPool::cons, OCI_Connection::cstate, OCI_ConnPool::db, OCI_ConnPool::incr, OCI_ConnPool::max, OCI_ConnPool::mode, OCI_ConnPool::mutex, OCI_ConnPool::nb_opened, OCI_ConnectionFree(), OCI_MutexAcquire(), OCI_MutexRelease(), OCI_ConnPool::pwd, and OCI_ConnPool::user.

OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetIncrement ( OCI_ConnPool pool  ) 

Return the increment for connections to be opened to the database when the pool is not full.

Parameters:
pool - Connection pool handle

Definition at line 571 of file connpool.c.

References OCI_ConnPool::incr.

OCI_EXPORT boolean OCI_API OCI_ConnPoolGetlGetNoWait ( OCI_ConnPool pool  ) 

Get the waiting mode used when no more connections are available from the pool.

Parameters:
pool - Connection pool handle
Returns:
  • FALSE to wait for an available connection if the pool is saturated
  • TRUE to not wait for an available connection

Definition at line 424 of file connpool.c.

References OCI_ConnPool::nowait.

OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetMax ( OCI_ConnPool pool  ) 

Return the maximum number of connections that can be opened to the database.

Parameters:
pool - Connection pool handle

Definition at line 558 of file connpool.c.

References OCI_ConnPool::max.

OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetMin ( OCI_ConnPool pool  ) 

Return the minimum number of connections that can be opened to the database.

Parameters:
pool - Connection pool handle

Definition at line 545 of file connpool.c.

References OCI_ConnPool::min.

OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetOpenedCount ( OCI_ConnPool pool  ) 

Return the current number of opened connections.

Parameters:
pool - Connection pool handle

Definition at line 509 of file connpool.c.

References OCI_ConnPool::err, OCI_ConnPool::handle, and OCI_ConnPool::nb_opened.

OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetTimeout ( OCI_ConnPool pool  ) 

Get the idle connection timeout.

Parameters:
pool - Connection pool handle
Note:
Connections idle for more than this time value (in seconds) are terminated

Timeout is not available for internal pooling implementation (client < 9i)

Returns:

Definition at line 375 of file connpool.c.

References OCI_ConnPool::timeout.

OCI_EXPORT boolean OCI_API OCI_ConnPoolSetNoWait ( OCI_ConnPool pool,
boolean  value 
)

Set the waiting mode used when no more connections are available from the pool.

Parameters:
pool - connection pool handle
value - wait for connection
Note:
Pass :
  • FALSE to wait for an available connection if the pool is saturated
  • TRUE to not wait for an available connection
Returns:

Definition at line 437 of file connpool.c.

References OCI_ConnPool::err, OCI_ConnPool::handle, and OCI_ConnPool::nowait.

OCI_EXPORT boolean OCI_API OCI_ConnPoolSetTimeout ( OCI_ConnPool pool,
unsigned int  value 
)

Set the idle connection timeout.

Parameters:
pool - Connection pool handle
value - Timeout value
Note:
Connections idle for more than this time value (in seconds) are terminated

This call has no effect if pooling is internally implemented (client < 9i)

Returns:

Definition at line 388 of file connpool.c.

References OCI_ConnPool::err, OCI_ConnPool::handle, and OCI_ConnPool::timeout.


Generated on Thu Jul 30 17:41:54 2009 for OCILIB (C Driver for Oracle) by  doxygen 1.5.4