am_conv.so

berkeley db 4.6.21的源码。berkeley db是一个简单的数据库管理系统

m4_comment([$Id: am_conv.so,v 10.24 2003/04/02 16:15:32 bostic Exp $])

m4_ref_title(Locking Subsystem, m4_tam locking conventions,
    m4_tam @locking conventions, lock/cam_conv, lock/nondb)

m4_p([dnl
All m4_db access methods follow the same conventions for locking
database objects.  Applications that do their own locking and also do
locking via the access methods must be careful to adhere to these
conventions.])

m4_p([dnl
Whenever a m4_db database is opened, the m4_ref(Db) handle is assigned
a unique locker ID.  Unless transactions are specified, that ID is used
as the locker for all calls that the m4_db methods make to the lock
subsystem.  In order to lock a file,  pages in the file, or records in
the file, we must create a unique ID that can be used as the object to
be locked in calls to the lock manager.  Under normal operation, that
object is a 28-byte value created by the concatenation of a unique file
identifier, a page or record number, and an object type (page or record).])

m4_p([dnl
In a transaction-protected environment, database create and delete
operations are recoverable and single-threaded.  This single-threading
is achieved using a single lock for the entire environment that must be
acquired before beginning a create or delete operation.  In this case,
the object on which m4_db will lock is a 4-byte unsigned integer with
a value of 0.])

m4_p([dnl
If applications are using the lock subsystem directly while they are
also using locking via the access methods, they must take care not to
inadvertently lock objects that happen to be equal to the unique file
IDs used to lock files.  This is most easily accomplished by using a
lock object with a length different from the values used by m4_db.])

m4_p([dnl
All the access methods other than Queue use standard read/write locks
in a simple multiple-reader/single writer page-locking scheme.  An
operation that returns data (for example, m4_ref(dbh_get) or
m4_ref(dbc_get)) obtains a read lock on all the pages accessed while
locating the requested record.   When an update operation is requested
(for example, m4_ref(dbh_put) or m4_ref(dbc_del)), the page containing
the updated (or new) data is write-locked.  As read-modify-write cycles
are quite common and are deadlock-prone under normal circumstances, the
m4_db interfaces allow the application to specify the m4_ref(DB_RMW)
flag, which causes operations to immediately obtain a write lock, even
though they are only reading the data.  Although this may reduce
concurrency somewhat, it reduces the probability of deadlock.  In the
presence of transactions, page locks are held until transaction commit.])

m4_p([dnl
The Queue access method does not hold long-term page locks.  Instead,
page locks are held only long enough to locate records or to change
metadata on a page, and record locks are held for the appropriate
duration.  In the presence of transactions, record locks are held until
transaction commit.  For m4_db operations, record locks are held until
operation completion; for m4_ref(Dbc) operations, record locks are held
until subsequent records are returned or the cursor is closed.])

m4_p([dnl
Under non-transaction operations, the access methods do not normally
hold locks across calls to the m4_db interfaces.  The one exception to
this rule is when cursors are used.  Because cursors maintain a position
in a file, they must hold locks across calls; in fact, they will hold
a lock until the cursor is closed.])

m4_p([dnl
In this mode, the assignment of locker IDs to m4_ref(Db) and cursor
handles is complicated.  If the m4_ref(DB_THREAD) option was specified
when the m4_ref(Db) handle was opened, each use of a m4_ref(Db) has its
own unique locker ID, and each cursor is assigned its own unique locker
ID when it is created, so m4_ref(Db) handle and cursor operations can
all conflict with one another.  (This is because when  m4_db handles
may be shared by multiple threads of control the m4_db library cannot
identify which operations are performed by which threads of control,
and it must ensure that two different threads of control are not
simultaneously modifying the same data structure.  By assigning each
m4_ref(Db) handle and cursor its own locker, two threads of control
sharing a handle cannot inadvertently interfere with each other.)])

m4_p([dnl
This has important implications.  If a single thread of control opens
two cursors, uses a combination of cursor and non-cursor operations, or
begins two separate transactions, the operations are performed on behalf
of different lockers.  Conflicts that arise between these different
lockers may not cause actual deadlocks, but can, in fact, permanently
block the thread of control.  For example, assume that an application
creates a cursor and uses it to read record A.  Now, assume a second
cursor is opened, and the application attempts to write record A using
the second cursor.  Unfortunately, the first cursor has a read lock, so
the second cursor cannot obtain its write lock.  However, that read lock
is held by the same thread of control, so the read lock can never be
released if we block waiting for the write lock.  This might appear to
be a deadlock from the application's perspective, but m4_db cannot
identify it as such because it has no knowledge of which lockers belong
to which threads of control.  For this reason, application designers
are encouraged to close cursors as soon as they are done with them.])

m4_p([dnl
If the m4_ref(DB_THREAD) option was not specified when the m4_ref(Db)
handle was opened, all uses of the m4_ref(Db) handle and all cursors
created using that handle will use the same locker ID for all
operations.  In this case, if a single thread of control opens two
cursors or uses a combination of cursor and non-cursor operations, these
operations are performed on behalf of the same locker, and so cannot
deadlock or block the thread of control.])

m4_p([dnl
Complicated operations that require multiple cursors (or combinations
of cursor and non-cursor operations) can be performed in two ways.
First, they may be performed within a transaction, in which case all
operations lock on behalf of the designated transaction.  Second, they
may be performed using a local m4_ref(Db) handle, although, as
m4_ref(dbh_open) operations are relatively slow, this may not be a good
idea.  Finally, the m4_ref(dbc_dup) function duplicates a cursor, using
the same locker ID as the originating cursor.  There is no way to
achieve this duplication functionality through the m4_ref(Db) handle
calls, but any m4_ref(Db) call can be implemented by one or more calls
through a cursor.])

m4_p([dnl
When the access methods use transactions, many of these problems disappear.
The transaction ID is used as the locker ID for all operations performed
on behalf of the transaction.  This means that the application may open
multiple cursors on behalf of the same transaction and these cursors will
all share a common locker ID.  This is safe because transactions cannot
span threads of control, so the library knows that two cursors in the same
transaction cannot modify the database concurrently.])

m4_page_footer