You initialize the locking subsystem by specifying DB_INIT_LOCK to the DB_ENV->open() method.

Before opening your environment, you can configure various values for your locking subsystem. Note that these limits can only be configured before the environment is opened. Also, these methods configure the entire environment, not just a specific environment handle.

Finally, each bullet below identifies the DB_CONFIG file parameter that can be used to specify the specific locking limit. If used, these DB_CONFIG file parameters override any value that you might specify using the environment handle.

The limits that you can configure are as follows:

For a definition of lockers, locks, and locked objects, see Lock Resources.

For example, to configure the number of locks that your environment can use:

#include "DbXml.hpp"
...

using namespace DbXml;
int main(void)
{
    u_int32_t env_flags = DB_CREATE     |  // If the environment does not
                                           // exist, create it.
                          DB_INIT_LOCK  |  // Initialize locking
                          DB_INIT_LOG   |  // Initialize logging
                          DB_INIT_MPOOL |  // Initialize the cache
                          DB_THREAD     |  // Free-thread the env handle
                          DB_INIT_TXN;     // Initialize transactions

    char *envHome = "/export1/testEnv";
    DB_ENV *myEnv = NULL;
    int dberr;

    XmlManager *myManager = NULL;

    dberr = db_env_create(&myEnv, 0);
    if (dberr) {
        std::cout << "Unable to create environment: " <<
            db_strerror(dberr) << std::endl;
        if (myEnv)
            myEnv->close(myEnv, 0);
        return (EXIT_FAILURE);
    }

    // Configure max locks
    myEnv->set_lk_max_locks(envp, 5000);

    myEnv->open(myEnv, envHome, env_flags, 0);
    myManager = new XmlManager(myEnv, 0);

    // Do work here. Clean up when all done.

    if (myManager != NULL) {
        delete myManager;
    }
    myEnv->close(myEnv, 0);

    return (EXIT_SUCCESS);
} 

In order for BDB XML to know that a deadlock has occurred, some mechanism must be used to perform deadlock detection. There are three ways that deadlock detection can occur:

For example, to configure your application such that BDB XML checks the lock table for deadlocks every time a lock request is blocked:

#include "DbXml.hpp"
...

using namespace DbXml;
int main(void)
{
    u_int32_t env_flags = DB_CREATE     |  // If the environment does not
                                           // exist, create it.
                          DB_INIT_LOCK  |  // Initialize locking
                          DB_INIT_LOG   |  // Initialize logging
                          DB_INIT_MPOOL |  // Initialize the cache
                          DB_THREAD     |  // Free-thread the env handle
                          DB_INIT_TXN;     // Initialize transactions

    DB_ENV *myEnv = NULL;
    XmlManager *myManager = NULL;
    char *envHome = "/export1/testEnv";
    int dberr;

    dberr = db_env_create(&myEnv, 0);
    if (dberr) {
        std::cout << "Unable to create environment: " <<
            db_strerror(dberr) << std::endl;
        if (myEnv)
            myEnv->close(myEnv, 0);
        return (EXIT_FAILURE);
    }

    // Configure db to perform deadlock detection internally, and to
    // choose the transaction that has performed the least amount 
    // of writing to break the deadlock in the event that one 
    // is detected.
    myEnv->set_lk_detect(DB_LOCK_MINWRITE);

    myEnv->open(myEnv, envHome, env_flags, 0);
    myManager = new XmlManager(myEnv, 0);
        
    // From here, you open your containers, proceed with your 
    // container operations,  and respond to deadlocks as 
    // is normal (omitted for brevity).
        
    ...

Finally, the following command line call causes deadlock detection to be run against the environment contained in /export/dbenv. The transaction with the youngest lock is chosen to break the deadlock:

> /usr/local/db_install/bin/db_deadlock -h /export/dbenv -a y

For more information, see the db_deadlock reference documentation.

When BDB XML determines that a deadlock has occurred, it will select a thread of control to resolve the deadlock and then throws XmlException in that thread. You must then test this exception to see if it is caused by a deadlock situation. Do this by checking whether XmlException.getDbErrno() is equal to DB_LOCK_DEADLOCK. If a deadlock is detected, the thread must:

For example:

// Environment, Manager and Container opens are omitted for brevity

XmlTransaction txn;

// retry_count is a counter used to identify how many times we've 
// retried this operation. To avoid the potential
// for endless looping, we won't retry more than 
// MAX_DEADLOCK_RETRIES times.

while (retry_count < MAX_DEADLOCK_RETRIES) {
    try {
        txn = myManager.createTransaction();
        
        // Need an update context for the put.
        XmlUpdateContext theContext = myManager.createUpdateContext();

        // Get the first input stream.
        XmlInputStream *theStream = 
            myManager.createLocalFileInputStream("/export/file.xml");

        // Put the first document
        myContainer.putDocument(txn,         // the transaction object
                                "file.xml",  // The document's name
                                theStream,   // The actual document. 
                                theContext,  // The update context 
                                             // (required).
                                0); 
        txn.commit();
        return (EXIT_SUCCESS);
    } catch (XmlException &e) { 
        if (e.getDbErrno() == DB_LOCK_DEADLOCK) {
            try {
                // Abort the transaction and increment the 
                // retry counter
                txn.abort();
                // Increment the retry count
                retry_count++;
                // If we've retried too many times, log it
                // and exit
                if (retry_count >= MAX_DEADLOCK_RETRIES) {
                    std::cerr << "Exceeded retry limit. Giving up."
                              << std::endl;
                    return (EXIT_FAILURE);
                }
            } catch (DbException &ae) {
                envp->err(ae.getErrorCode(), "txn abort failed.");
                return (EXIT_FAILURE);    
            }
        } else {
            try {
                // For a generic error, log it and abort.
                std::cerr << "Error in transaction: "
                          << e.what() << "\n"
                          << "Aborting." << std::endl;
                txn.abort();
            } catch (DbException &ae) {
                envp->err(ae.get_errno(), "txn abort failed.");
                return (EXIT_FAILURE);    
            }
        }
    }
} 

Normally when a thread of control must be selected to resolve a deadlock, BDB XML decides which thread will perform the resolution; you have no way of knowing in advance which thread will be selected to resolve the deadlock.

However, there may be situations where you know it is better for one thread to resolve a deadlock over another thread. As an example, if you have a background thread running data management activities, and another thread responding to user requests, you might want deadlock resolution to occur in the background thread because you can better afford the throughput costs there. Under these circumstances, you can identify which thread of control will be selected for resolved deadlocks by setting a transaction priorities.

When two transactions are deadlocked, BDB XML will abort the transaction with the lowest priority. By default, every transaction is given a priority of 100. However, you can set a different priority on a transaction-by-transaction basis by using the method.

When two or more transactions are tied for the lowest priority, the tie is broken based on the policy provided to

A transaction's priority can be changed at any time after the transaction handle has been created and before the transaction has been resolved (committed or aborted). For example: