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_ConnPoolGetGetNoWait (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:

  • OCI_SESSION_DEFAULT
  • OCI_SESSION_SYSDBA
  • OCI_SESSION_SYSOPER
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_ConnPoolFree().

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 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_ConnectionFree(), OCI_MutexAcquire(), and OCI_MutexRelease().

OCI_EXPORT unsigned int OCI_API OCI_ConnPoolGetTimeout ( OCI_ConnPool pool  ) 

Get the idle connection timeout.

Parameters:
pool - Connection pool handle
Note:
Connection idle for more than this time value (in seconds) is terminated
Timeout is not available for internal pooling implementation (client < 9i)
Returns:

Definition at line 382 of file connpool.c.

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:
Connection idle for more than this time value (in seconds) is terminated
This call has no effect if pooling is internally implemented (client < 9i)
Returns:

Definition at line 395 of file connpool.c.

OCI_EXPORT boolean OCI_API OCI_ConnPoolGetGetNoWait ( 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
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 444 of file connpool.c.

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 480 of file connpool.c.

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 516 of file connpool.c.

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 552 of file connpool.c.

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 565 of file connpool.c.

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 578 of file connpool.c.

Generated on Wed Jun 23 21:48:40 2010 for OCILIB (C Driver for Oracle) by  doxygen 1.6.3