Questions about Pools

[felipenoris]

In dpiPool_acquireConnection, the input parameter *pool is described as:

pool [IN] – the pool from which a connection is to be acquired. If the reference is NULL or invalid an error is returned.

Also, dpiPool_acquireConnection expects a parameter dpiConnCreateParams *params, which has a field pool described as:

Specifies the session pool from which to acquire a connection or NULL if a standalone connection should be created. The default value is NULL.

Aparently, dpiConn_create also has capability to create a connection from a pool, as described in the docs:

Creates a standalone connection to a database or acquires a connection from a session pool and returns a reference to the connection.

Questions

• When I use dpiPool_acquireConnection, the attribute pool in dpiConnCreateParams *params is ignored?

• dpiConn_create does the same thing as dpiPool_acquireConnection if the attribute pool in dpiConnCreateParams *params has a reference to a Pool?

• What is a session ? The docs describe a Pool to be a session pool, but dpiPoolCreateParams.minSessions defines the number of sessions (connections? different users in non-homogeneous sessions?) for a single pool.

• In the dpiPool_acquireConnection docs, it says: Acquires a connection from the pool and returns a reference to it. This reference should be released as soon as it is no longer needed. The release of a connection reference should be done by calling dpiConn_close() or dpiConn_release(), right?

Thanks in advance!

[anthony-tuininga]

When I use dpiPool_acquireConnection, the attribute pool in dpiConnCreateParams *params is ignored?

Yes. I've added a note in the documentation regarding this.

dpiConn_create does the same thing as dpiPool_acquireConnection if the attribute pool in dpiConnCreateParams *params has a reference to a Pool?

Yes. I've added a note in the documentation regarding this.

What is a session ? The docs describe a Pool to be a session pool, but dpiPoolCreateParams.minSessions defines the number of sessions (connections? different users in non-homogeneous sessions?) for a single pool.

Sessions and connections are effectively the same. Each time you acquire a connection from the pool you get a brand new object -- even if the "session" that is attached to that connection is the same one you checked out previously. As such I agree that it can be a bit confusing to differentiate between "sessions" and "connections". If you understand them to be virtually identical (just that the pool owns "sessions" which are virtual "connections" which you can transform into "real" connections by acquiring them) I think you can't go too far wrong. @cjbj and I were talking about this last week. Perhaps it might be wise to come up with a good definition of the distinction and publish that -- and be consistent in the documentation when referring to a "session" and a "connection" -- or simply eliminate the distinction altogether!

In the dpiPool_acquireConnection docs, it says: Acquires a connection from the pool and returns a reference to it. This reference should be released as soon as it is no longer needed. The release of a connection reference should be done by calling dpiConn_close() or dpiConn_release(), right?

What it means is that you should call dpiConn_release(). Calling dpiConn_close() frees up the server resources but a reference is still retained. If you forget to call dpiConn_release() then the memory ODPI-C allocates internally for the connection will be retained permanently and you will experience a memory leak. I've clarified that in the documentation.

[felipenoris]

@anthony-tuininga thanks again for answering and improving the docs!

Just one comment on the last question: I understand that one must call dpiConn_release to prevent memory leak. But what I missed in the docs was how to put a session/connection back into the pool. And after a few tests, it looks like I just have to call dpiConn_close on the connection. Even if it's not yet released, just by closing it I'm able to acquire a new session/connection from the pool.

Cheers!

[anthony-tuininga]

You're welcome. And thanks for asking questions! Without those questions I would simply assume that the documentation is perfectly clear and contains all of the information you need. :-) I've added a further note to the documentation of dpiPool_acquireConnection() that a call to dpiConn_close() will release the connection back to the pool.