Connection functions


Data Structures

struct  rxv_spin_conn
 Connection structure. More...
struct  rxv_spin_cpool
 Connection pool structure. More...

Defines

#define RXV_SPIN_CONN_PGSQL   0x01
#define RXV_SPIN_CONN_MYSQL   0x02
#define RXV_SPIN_CONN_MINID   0x01
#define RXV_SPIN_CONN_MAXID   0x3F
#define RXV_SPIN_CONN_FOREIGN   0x40
#define RXV_SPIN_CONN_POOLED   0x80
#define RXV_SPIN_CONN_IS_PGSQL(c)   ((((c)->type)&RXV_SPIN_CONN_MAXID)==RXV_SPIN_CONN_PGSQL)
#define RXV_SPIN_CONN_IS_MYSQL(c)   ((((c)->type)&RXV_SPIN_CONN_MAXID)==RXV_SPIN_CONN_MYSQL)
#define RXV_SPIN_CONN_IS_FOREIGN(c)   (((c)->type)&RXV_SPIN_CONN_FOREIGN)
#define RXV_SPIN_CONN_IS_POOLED(c)   (((c)->type)&RXV_SPIN_CONN_POOLED)

Typedefs

typedef rxv_spin_conn rxv_spin_conn_t
typedef rxv_spin_cpool rxv_spin_cpool_t

Functions

rxv_spin_cpool_trxv_spin_cpool_create (apr_pool_t *pool)
rxv_spin_conn_trxv_spin_cpool_get (apr_pool_t *pool, rxv_spin_cpool_t *cpool, const char *conninfo)
rxv_spin_conn_trxv_spin_cpool_set (rxv_spin_cpool_t *cpool, const char *conninfo, void *conn, apr_status_t(*cleanup)(void *data))
apr_status_t rxv_spin_conn_close (rxv_spin_conn_t *conn)

Detailed Description

Connection functions (mod_spin API)

Define Documentation

#define RXV_SPIN_CONN_PGSQL   0x01

PostgreSQL connection type

#define RXV_SPIN_CONN_MYSQL   0x02

MySQL connection type

#define RXV_SPIN_CONN_MINID   0x01

lowest known connection type

#define RXV_SPIN_CONN_MAXID   0x3F

highest known connection type

#define RXV_SPIN_CONN_FOREIGN   0x40

foreign connection type

#define RXV_SPIN_CONN_POOLED   0x80

connection pooled flag

#define RXV_SPIN_CONN_IS_PGSQL (  )     ((((c)->type)&RXV_SPIN_CONN_MAXID)==RXV_SPIN_CONN_PGSQL)

check if this connection is of PostgreSQL type

#define RXV_SPIN_CONN_IS_MYSQL (  )     ((((c)->type)&RXV_SPIN_CONN_MAXID)==RXV_SPIN_CONN_MYSQL)

check if this connection is of MySQL type

#define RXV_SPIN_CONN_IS_FOREIGN (  )     (((c)->type)&RXV_SPIN_CONN_FOREIGN)

check if this connection is of MySQL type

#define RXV_SPIN_CONN_IS_POOLED (  )     (((c)->type)&RXV_SPIN_CONN_POOLED)

check if this connection is pooled


Typedef Documentation

typedef struct rxv_spin_conn rxv_spin_conn_t

connection type

typedef struct rxv_spin_cpool rxv_spin_cpool_t

connection pool type


Function Documentation

rxv_spin_cpool_t* rxv_spin_cpool_create ( apr_pool_t *  pool  ) 

Create a connection pool. Connection strings used to search for open connections within the pool are treated as case sensitive and they consist of the actual connection string preceded by the type (a single character).

Parameters:
pool Memory pool used for allocation
Returns:
pointer to the new connection pool, NULL on error
Example:
Remarks:
This function is not normally called from the application, even when connection pools are used. Connection pool creation and cleanup is performed automatically by mod_spin. If you decide to manage you own connection pools, you will need this function.
IMPORTANT:
The code of mod_spin calls this function to create one connection pool for each thread of Apache. If you call apr_proc_create() to run a new process from within any mod_spin applications, registered child cleanup function will close all connections and remove them from the pool before the new process is executed inside the forked one. This equally applies to the connection pools created by you.

rxv_spin_conn_t* rxv_spin_cpool_get ( apr_pool_t *  pool,
rxv_spin_cpool_t cpool,
const char *  conninfo 
)

Get a registered connection of foreign type from the connection pool.

Parameters:
pool Memory pool for temporary allocations
cpool Connection pool
conninfo Connection string for this connection
Returns:
Pointer to the connection or NULL if not found
Example:
 rxv_spin_cpool_get(ctx->pool,ctx->cpool,
                    "ldap://ldap.example.com/dc=example,dc=com");

rxv_spin_conn_t* rxv_spin_cpool_set ( rxv_spin_cpool_t cpool,
const char *  conninfo,
void *  conn,
apr_status_t(*)(void *data)  cleanup 
)

Register a connection of foreign type with the connection pool.

Parameters:
cpool Connection pool
conninfo Connection string for this connection
conn Connection pointer
cleanup Cleanup function to call on pool destruction
Returns:
Pointer to the connection, NULL on error
Example:
 rxv_spin_cpool_set(ctx->cpool,"ldap://ldap.example.com/dc=example,dc=com",
                    ldapconn,ldap_cleanup);
Remarks:
This function will register the connection even if the connection with the same key already exists. This may lead to multiple cleanup functions being registered for the same connection and eventually segfaults. Use rxv_spin_cpool_get() function to verify if the connection was registered before.
IMPORTANT:
The cleanup function MUST remove the connection from the hash table holding all pooled connections. Failing that, the next time such connection is requested, an invalid connection structure will be passed to the application, causing an almost certain segfault. See db_clean() function in mod_spin source (file db.c) for an example.
IMPORTANT:
The lifetime of the connection and all other variables passed into this function has to be at least the lifetime of the connection pool you are registering the connection with. Normally, connection pools have thread lifetime, so if you have shorter lifetime for your connection (e.g. request, connection), you are setting yourself up for segfaults. Also, if the lifetime of the connection is longer than the one of the connection pool, for instance, if it has the lifetime of the process and you are registering it with the regular thread based connection pool, you may experience segfaults if you rely on that connection once the thread exited. If you are managing your own connection pool, same issues apply, except for the fact that you control the lifetime of the connection pool, rather than mod_spin.

apr_status_t rxv_spin_conn_close ( rxv_spin_conn_t conn  ) 

Close a connection and remove it from the pool.

Parameters:
conn Connection
Returns:
APR_SUCCESS on success, otherwise an error
Example:
Remarks:
This function may be useful for explicit termination of pooled or non-pooled connections, especially if you're managing your own connection pools. If pooled connections aren't used, the connection will be closed anyway during the temporary pool cleanup (first argument to rxv_spin_db_connect()).


Generated on Mon Sep 4 21:18:50 2006 for mod_spin by  doxygen 1.4.7