Table of Contents
DB offers a great deal of support for multi-threaded and multi-process applications even when transactions are not in use. Many of DB's handles are thread-safe, or can be made thread-safe by providing the appropriate flag at handle creation time, and DB provides a flexible locking subsystem for managing databases in a concurrent application. Further, DB provides a robust mechanism for detecting and responding to deadlocks . All of these concepts are explored in this chapter.
Before continuing, it is useful to define a few terms that will appear throughout this chapter:
Thread of control
Refers to a thread that is performing work in your application. Typically, in this book that thread will be performing DB operations.
Note that this term can also be taken to mean a separate process that is performing work — DB supports multi-process operations on your databases.
Locking
When a thread of control obtains access to a shared resource, it is said to be locking that resource. Note that DB supports both exclusive and non-exclusive locks. See Locks for more information.
Free-threaded
Data structures and objects are free-threaded if they can be shared across threads of control without any explicit locking on the part of the application. Some books, libraries, and programming languages may use the term thread-safe for data structures or objects that have this characteristic. The two terms mean the same thing.
For a description of free-threaded DB objects, see Which DB Handles are Free-Threaded.
Blocked
When a thread cannot obtain a lock because some other thread already holds a lock on that object, the lock attempt is said to be blocked. See Blocks for more information.
Deadlock
Occurs when two or more threads of control attempt to access conflicting resource in such a way as none of the threads can any longer make further progress.
For example, if Thread A is blocked waiting for a resource held by Thread B, while at the same time Thread B is blocked waiting for a resource held by Thread A, then neither thread can make any forward progress. In this situation, Thread A and Thread B are said to be deadlocked.
For more information, see Deadlocks.
The following describes to what extent and under what conditions individual handles are free-threaded.
                    
                    
                   Environment 
                   
                           and the DPL
                           EntityStore
                   
                
                    Free-threaded so long as
                        
                        
                            EnvironmentConfig.setThreaded()
                            is set to true.
                        
                
                    
                    
                   Database 
                   
                           and the DPL
                           PrimaryIndex
                   
                
                    Free-threaded so long as
                        
                        
                                the database 
                                
                                        or DPL PrimaryIndex
                                
                                is opened in a free-threaded environment.
                        
                
                   SecondaryDatabase 
                   and DPL SecondaryIndex
                
                    Same conditions apply as for Database
                    and PrimaryIndex handles.
                
                    
                    
                   Cursor 
                   
                           and the DPL
                           EntityCursor
                   
                
Cursors are not free-threaded. However, they can be used by multiple threads of control so long as the application serializes access to the handle.
                   SecondaryCursor 
                
                    Same conditions apply as for Cursor
                    handles.
                
                    
                    
                   Transaction 
                    
                
Access must be serialized by the application across threads of control.
                All other classes found in the DPL
                (com.sleepycat.persist.*) and not
                mentioned above are free-threaded.
            
                All classes found in the bind APIs (com.sleepycat.bind.*) are free-threaded.