Notes for Using C Driver

Lifecycle of NuoDB_ResultSet Types

A NuoDB_ResultSet type is returned by various functions in the C driver API. There is no need for a client application to create NuoDB_ResultSet types. However, a client application should call NuoDB_ResultSetFree() when a NuoDB_ResultSet is no longer needed.

A NuoDB_ResultSet behaves differently depending on whether the AUTOCOMMIT property is on or off. If autocommit is on, you are limited to one active, valid NuoDB_ResultSet. Associated NuoDB_ResultSetMetaData types and NuoDB_ResultSet types returned from getGeneratedKeys() in NuoDB_Statement can be open at the same time but they have the same lifecycle. That is, they are valid until closed, committed, or another statement is executed by the NuoDB_Statement type. A statement that returns a NuoDB_ResultSet defers committing the transaction. This ensures that iteration over the NuoDB_ResultSet is consistent with the data and the transaction isolation level. Each execution of a statement commits any previously deferred transaction, which closes any associated NuoDB_ResultSet.

If autocommit is off, you can have as many NuoDB_ResultSet types as you need. Each NuoDB_ResultSet must come from a unique NuoDB_Statement type. You cannot have multiple open NuoDB_ResultSet types from the same statement. When a statement is executed, any currently associated NuoDB_ResultSet is closed and it cannot be reopened or reused.

Unsupported Workaround for Multiple Result Sets

As mentioned before, NuoDB does not support more than one NuoDB_ResultSet from the same statement. However, some applications may have success accessing multiple NuoDB_ResultSet types from the same statement if the size of the NuoDB_ResultSet is small enough (less than 100KB) for the entire result to be returned to the client in one message. This is possible regardless of the autocommit setting. An application can iterate over the NuoDB_ResultSet safely until the client goes back to the server for more data. This workaround is not recommended, nor supported. Clients should not rely on this behavior.

Thread Safety in NuoDB C Driver Applications

For a client application to use the same type instance in more than one thread, the client must perform its own synchronization, reference counting, and concurrency control. The C driver provides the necessary thread safety only for its internal state and resources.