Locker (starrocks-bdb-je 18.3.17 API)

java.lang.Object
- com.sleepycat.je.txn.Locker

Direct Known Subclasses:

BasicLocker, Txn
```
public abstract class Locker
extends Object
```
Locker instances are JE's route to locking and transactional support. This class is the abstract base class for BasicLocker, ThreadLocker, Txn, MasterTxn and ReadonlyTxn. Locker instances are in fact only a transaction shell to get to the lock manager, and don't guarantee transactional semantics. Txn (includes Txns marked autoTxn) MasterTxn and ReadonlyTxn instances are truly transactional. They have potentially different transaction begin and end behaviors.

Field Summary

Fields
Modifier and Type	Field and Description
`TestHook<Object>`	`afterWaiterHook` Hook called by lock manager after adding this locker as a waiter.
`protected EnvironmentImpl`	`envImpl`
`protected long`	`id`
`protected LockManager`	`lockManager`
`protected Thread`	`thread` The thread that created this locker.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`Locker(EnvironmentImpl envImpl, boolean readUncommittedDefault, boolean noWait, long mandatedId)` Create a locker id.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract void`	`addDbCleanup(DbCleanup cleanup)` Database operations like remove, truncate and rename require that DatabaseImpls are deleted or updated at transaction commit or abort.
`void`	`addDeleteInfo(BIN bin)` Add delete information, to be added to the inCompressor queue when the transaction ends.
`protected abstract void`	`addLock(Long lsn, LockType type, LockGrantType grantStatus)` Add a lock to set owned by this transaction.
`void`	`addOpenedDatabase(Database dbHandle)`
`boolean`	`allowReleaseLockAfterLsnChange()`
`void`	`checkPreempted(Locker allowPreemptedLocker)` Called when obtaining a lock to cause a LockPreemptedException to be thrown if a lock was preempted earlier.
`protected abstract void`	`checkState(boolean ignoreCalledByAbort)`
`abstract StatGroup`	`collectStats()` Get lock count, for per transaction lock stats, for internal debugging.
`void`	`demoteLock(long lsn)` Revert this lock from a write lock to a read lock.
`void`	`disallowReplicaWrite()` Throws ReplicaWriteException if called for a locker on a Replica.
`void`	`dumpLockTable()` Dump lock table, for debugging
`protected abstract long`	`generateId(TxnManager txnManager, long mandatedId)` A Locker has to generate its next id.
`boolean`	`getDefaultNoWait()`
`EnvironmentImpl`	`getEnvironment()`
`long`	`getId()`
`boolean`	`getImportunate()` Get the state of a transaction's IMPORTUNATE bit.
`protected long`	`getInitialLockTimeout()`
`long`	`getLockTimeout()` Get the lock timeout period for this locker, in milliseconds WARNING: Be sure to always access the timeout with this accessor, since it is overridden in BuddyLocker.
`boolean`	`getPreemptable()` Returns whether my locks can be stolen/preemted.
`Transaction`	`getTransaction()` Returns a Transaction if the locker is transctional, or null otherwise.
`abstract Txn`	`getTxnLocker()` Returns the underlying Txn if the locker is transactional, or null if the locker is non-transactional.
`long`	`getTxnTimeout()` Get the transaction timeout period for this locker, in milliseconds public for jca/ra/JELocalTransaction.
`abstract WriteLockInfo`	`getWriteLockInfo(long lsn)`
`boolean`	`isLocalWrite()` Returns true if writes may only be to non-replicated DBs using this locker, or false if writes may only be to replicated DBs.
`abstract boolean`	`isReadCommittedIsolation()` Returns whether the isolation level of this locker is read-committed.
`boolean`	`isReadOnly()` Returns whether writes are prohibited using this locker.
`boolean`	`isReadUncommittedDefault()`
`boolean`	`isReplicated()` Returns whether a transaction is method indicates whether the txn is part of the rep stream.
`boolean`	`isRolledBack()`
`abstract boolean`	`isSerializableIsolation()` Returns whether the isolation level of this locker is serializable.
`boolean`	`isTimedOut()`
`abstract boolean`	`isTransactional()` Returns whether this locker is transactional.
`boolean`	`isValid()` Used to determine whether the locker is usable.
`LockResult`	`lock(long lsn, LockType lockType, boolean noWait, DatabaseImpl database)` Request a blocking or non-blocking lock of the given type on the given LSN.
`void`	`lockAfterLsnChange(long oldLsn, long newLsn, DatabaseImpl dbImpl)` Called when an LN is logged by an operation that will not hold the lock such as eviction/checkpoint deferred-write logging or cleaner LN migration.
`abstract boolean`	`lockingRequired()` Returns true if locking is required for this Locker.
`abstract Locker`	`newNonTxnLocker()` Creates a fresh non-transactional locker, while retaining any transactional locks held by this locker.
`LockResult`	`nonBlockingLock(long lsn, LockType lockType, boolean jumpAheadOfWaiters, DatabaseImpl database)` Request a non-blocking lock of the given type on the given LSN.
`abstract void`	`nonTxnOperationEnd()` Releases locks and closes the locker at the end of a non-transactional cursor operation.
`void`	`openCursorHook(DatabaseImpl dbImpl)` Overridden to perform actions in a non-transactional cursor when it is opened, for example, ReplicaThreadLocker performs consistency checks.
`void`	`operationEnd()` The equivalent of calling operationEnd(true).
`abstract void`	`operationEnd(boolean operationOK)` Different types of transactions do different things when the operation ends.
`void`	`operationEnd(OperationStatus status)` A SUCCESS status equals operationOk.
`abstract void`	`preLogWithoutLock(DatabaseImpl database)` In the case where logging occurs before locking, allow lockers to reject the operation (e.g., if writing on a replica) and also prepare to undo in the (very unlikely) event that logging succeeds but locking fails.
`abstract void`	`registerCursor(CursorImpl cursor)` Tell this transaction about a cursor.
`boolean`	`releaseLock(long lsn)` Release the lock on this LN and remove from the transaction's owning set.
`abstract void`	`releaseNonTxnLocks()` Releases any non-transactional locks held by this locker.
`void`	`setClosingLocker(Locker closingLocker)` This method is called to set the closingLocker when a cursor has been duplicated prior to being moved.
`void`	`setDefaultNoWait(boolean noWait)`
`void`	`setImportunate(boolean importunate)` Set the state of a transaction's IMPORTUNATE bit.
`void`	`setLockTimeout(long timeout)` Set the lock timeout period for any locks in this transaction, in milliseconds.
`void`	`setOnlyAbortable(OperationFailureException cause)` Set the state of a transaction to abort-only.
`void`	`setPreemptable(boolean preemptable)` Allows/disallows my locks from being stolen/preemted.
`void`	`setPreempted()` Called when a lock is stolen from this locker by the HA replayer.
`void`	`setTxnTimeout(long timeout)` Set the timeout period for this transaction, in milliseconds.
`boolean`	`sharesLocksWith(Locker other)` Returns whether this locker can share locks with the given locker.
`String`	`toString()` This method is safe to call without synchronizing and this fact is relied on by LockManager when creating exception messages.
`abstract void`	`unRegisterCursor(CursorImpl cursor)` Remove a cursor from this txn.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - envImpl
```
protected EnvironmentImpl envImpl
```
  - lockManager
```
protected LockManager lockManager
```
  - id
```
protected long id
```
  - thread
```
protected Thread thread
```
    The thread that created this locker. Used for debugging, and by the ThreadLocker subclass. Note that thread may be null if the Locker is instantiated by reading the log.
  - afterWaiterHook
```
public TestHook<Object> afterWaiterHook
```
    Hook called by lock manager after adding this locker as a waiter.
- Constructor Detail
  - Locker
```
protected Locker(EnvironmentImpl envImpl,
                 boolean readUncommittedDefault,
                 boolean noWait,
                 long mandatedId)
```
    Create a locker id. This constructor is called very often, so it should be as streamlined as possible. It should never be called directly, because the mandatedId mechanism only works if the generateId() method is overridden to use the mandatedId value.
    
    Parameters:
    
    readUncommittedDefault - if true, this transaction does read-uncommitted by default
    
    noWait - if true, non-blocking lock requests are used.
- Method Detail
  - getInitialLockTimeout
```
protected long getInitialLockTimeout()
```
  - getEnvironment
```
public EnvironmentImpl getEnvironment()
```
  - generateId
```
protected abstract long generateId(TxnManager txnManager,
                                   long mandatedId)
```
    A Locker has to generate its next id. Some subtypes, like BasicLocker, have a single id for all instances because they are never used for recovery. Other subtypes ask the txn manager for an id or use a specific, mandated id.
  - getId
```
public long getId()
```
    Returns:
    
    the transaction's id.
  - getDefaultNoWait
```
public boolean getDefaultNoWait()
```
    Returns:
    
    the default no-wait (non-blocking) setting.
  - setDefaultNoWait
```
public void setDefaultNoWait(boolean noWait)
```
  - getLockTimeout
```
public long getLockTimeout()
```
    Get the lock timeout period for this locker, in milliseconds WARNING: Be sure to always access the timeout with this accessor, since it is overridden in BuddyLocker.
  - setLockTimeout
```
public void setLockTimeout(long timeout)
```
    Set the lock timeout period for any locks in this transaction, in milliseconds.
    
    Parameters:
    
    timeout - The timeout value for the transaction lifetime, in milliseconds. A value of 0 disables timeouts for the transaction.
    
    Throws:
    
    IllegalArgumentException - via Transaction.setLockTimeout
  - setTxnTimeout
```
public void setTxnTimeout(long timeout)
```
    Set the timeout period for this transaction, in milliseconds.
    
    Parameters:
    
    timeout - The timeout value for the transaction lifetime, in microseconds. A value of 0 disables timeouts for the transaction.
    
    Throws:
    
    IllegalArgumentException - via Transaction.setLockTimeout
  - isReadUncommittedDefault
```
public boolean isReadUncommittedDefault()
```
    Returns:
    
    true if transaction was created with read-uncommitted as a default.
  - setOnlyAbortable
```
public void setOnlyAbortable(OperationFailureException cause)
```
    Set the state of a transaction to abort-only. Should ONLY be called by OperationFailureException.
  - setImportunate
```
public void setImportunate(boolean importunate)
```
    Set the state of a transaction's IMPORTUNATE bit.
  - getImportunate
```
public boolean getImportunate()
```
    Get the state of a transaction's IMPORTUNATE bit.
  - setPreemptable
```
public void setPreemptable(boolean preemptable)
```
    Allows/disallows my locks from being stolen/preemted.
  - getPreemptable
```
public boolean getPreemptable()
```
    Returns whether my locks can be stolen/preemted.
  - setPreempted
```
public void setPreempted()
```
    Called when a lock is stolen from this locker by the HA replayer.
  - checkPreempted
```
public void checkPreempted(Locker allowPreemptedLocker)
                    throws OperationFailureException
```
    Called when obtaining a lock to cause a LockPreemptedException to be thrown if a lock was preempted earlier. This operation is split into two methods, checkPreempted and throwIfPreempted, so that Txn.checkPreempted can call throwIfPreempted for all its BuddyLockers without causing an infinite recursion. This method is overridden by BuddyLocker to forward the call to its parent buddy (the Txn), and by Txn to check all its child buddies.
    
    Parameters:
    
    allowPreemptedLocker - is a locker that is being closed as the result of a cursor move operation. If the operation is successful then allowPreemptedLocker will be closed, and the fact that a lock has been stolen from allowPreemptedLocker can be ignored.
    
    Throws:
    
    OperationFailureException
  - setClosingLocker
```
public void setClosingLocker(Locker closingLocker)
```
    This method is called to set the closingLocker when a cursor has been duplicated prior to being moved. The new locker is informed of the old locker, so that a preempted lock taken by the old locker can be ignored. When the operation is complete, this method is called to clear the closingLocker so that a reference to the old closed locker is not held by this object. [#16513]
    
    Parameters:
    
    closingLocker - the old locker that will be closed if the new cursor (using this locker) is moved successfully.
  - checkState
```
protected abstract void checkState(boolean ignoreCalledByAbort)
                            throws DatabaseException
```
    Throws:
    
    DatabaseException
  - openCursorHook
```
public void openCursorHook(DatabaseImpl dbImpl)
```
    Overridden to perform actions in a non-transactional cursor when it is opened, for example, ReplicaThreadLocker performs consistency checks.
  - isReplicated
```
public boolean isReplicated()
```
    Returns whether a transaction is method indicates whether the txn is part of the rep stream. A replicated txn must be used for writing to a replicated DB, and a non-replicated txn must be used for writing to a non-replicated DB. This is critical for avoiding corruption when HA failovers occur [#23234] [#23330]. See guard in LN.logInternal.
  - isLocalWrite
```
public boolean isLocalWrite()
```
    Returns true if writes may only be to non-replicated DBs using this locker, or false if writes may only be to replicated DBs. By default (this implementation) local-write is true, since it is allowed for all non-txnal lockers and for all lockers in a standalone environment. This method is overridden and returns false for for user transactions in a replicated environment that are not explicitly configured for local-write. This method is used to describe a locker's configured usage for checking the validity of an API write operation. This is checked by Cursor methods at the beginning of each write operation.
  - isReadOnly
```
public boolean isReadOnly()
```
    Returns whether writes are prohibited using this locker.
  - lock
```
public LockResult lock(long lsn,
                       LockType lockType,
                       boolean noWait,
                       DatabaseImpl database)
                throws LockNotAvailableException,
                       LockConflictException
```
    Request a blocking or non-blocking lock of the given type on the given LSN.
    
    Parameters:
    
    lsn - is the node to lock.
    
    lockType - is the type of lock to request.
    
    noWait - is true to override the defaultNoWait setting. If true, or if defaultNoWait is true, throws LockNotAvailableException if the lock cannot be granted without waiting.
    
    database - is the database containing lsn.
    
    Throws:
    
    LockNotAvailableException - if a non-blocking lock was denied.
    
    LockConflictException - if a blocking lock could not be acquired.
  - nonBlockingLock
```
public LockResult nonBlockingLock(long lsn,
                                  LockType lockType,
                                  boolean jumpAheadOfWaiters,
                                  DatabaseImpl database)
```
    Request a non-blocking lock of the given type on the given LSN.
    Unlike lock(), this method returns LockGrantType.DENIED if the lock is denied rather than throwing LockNotAvailableException. This method should therefore not be used as the final lock for a user operation, since in that case LockNotAvailableException should be thrown for a denied lock. It is normally used only to probe for a lock internally, and other recourse is taken if the lock is denied.
    
    Parameters:
    
    lsn - is the node to lock.
    
    lockType - is the type of lock to request.
    
    jumpAheadOfWaiters - grant the lock before other waiters, if any.
    
    database - is the database containing LSN.
  - releaseLock
```
public boolean releaseLock(long lsn)
                    throws DatabaseException
```
    Release the lock on this LN and remove from the transaction's owning set.
    
    Throws:
    
    DatabaseException
  - demoteLock
```
public void demoteLock(long lsn)
                throws DatabaseException
```
    Revert this lock from a write lock to a read lock.
    
    Throws:
    
    DatabaseException
  - lockAfterLsnChange
```
public void lockAfterLsnChange(long oldLsn,
                               long newLsn,
                               DatabaseImpl dbImpl)
```
    Called when an LN is logged by an operation that will not hold the lock such as eviction/checkpoint deferred-write logging or cleaner LN migration. We must acquire a lock on the new LSN on behalf of every locker that currently holds a lock on the old LSN. Lock is non-blocking because no contention is possible on the new LSN. Because this locker is being used by multiple threads, this method may be called for a locker that has been closed or for which the lock on the old LSN has been released. Unlike other locking methods, in this case we simply return rather than report an error.
  - preLogWithoutLock
```
public abstract void preLogWithoutLock(DatabaseImpl database)
```
    In the case where logging occurs before locking, allow lockers to reject the operation (e.g., if writing on a replica) and also prepare to undo in the (very unlikely) event that logging succeeds but locking fails.
  - disallowReplicaWrite
```
public void disallowReplicaWrite()
```
    Throws ReplicaWriteException if called for a locker on a Replica. This implementation does nothing but is overridden by replication lockers. [#20543]
  - isTransactional
```
public abstract boolean isTransactional()
```
    Returns whether this locker is transactional.
  - isSerializableIsolation
```
public abstract boolean isSerializableIsolation()
```
    Returns whether the isolation level of this locker is serializable.
  - isReadCommittedIsolation
```
public abstract boolean isReadCommittedIsolation()
```
    Returns whether the isolation level of this locker is read-committed.
  - getTxnLocker
```
public abstract Txn getTxnLocker()
```
    Returns the underlying Txn if the locker is transactional, or null if the locker is non-transactional. For a Txn-based locker, this method returns 'this'. For a BuddyLocker, this method may return the buddy.
  - getTransaction
```
public Transaction getTransaction()
```
    Returns a Transaction if the locker is transctional, or null otherwise.
  - newNonTxnLocker
```
public abstract Locker newNonTxnLocker()
                                throws DatabaseException
```
    Creates a fresh non-transactional locker, while retaining any transactional locks held by this locker. This method is called when the cursor for this locker is cloned.
    This method must return a locker that shares locks with this locker, e.g., a ThreadLocker.
    
    In general, transactional lockers return 'this' when this method is called, while non-transactional lockers return a new instance.
    
    Throws:
    
    DatabaseException
  - releaseNonTxnLocks
```
public abstract void releaseNonTxnLocks()
                                 throws DatabaseException
```
    Releases any non-transactional locks held by this locker. This method is called when the cursor moves to a new position or is closed.
    In general, transactional lockers do nothing when this method is called, while non-transactional lockers release all locks as if operationEnd were called.
    
    Throws:
    
    DatabaseException
  - nonTxnOperationEnd
```
public abstract void nonTxnOperationEnd()
                                 throws DatabaseException
```
    Releases locks and closes the locker at the end of a non-transactional cursor operation. For a transctional cursor this method should do nothing, since locks must be held until transaction end.
    
    Throws:
    
    DatabaseException
  - sharesLocksWith
```
public boolean sharesLocksWith(Locker other)
```
    Returns whether this locker can share locks with the given locker.
  - operationEnd
```
public final void operationEnd()
                        throws DatabaseException
```
    The equivalent of calling operationEnd(true).
    
    Throws:
    
    DatabaseException
  - operationEnd
```
public final void operationEnd(OperationStatus status)
                        throws DatabaseException
```
    A SUCCESS status equals operationOk.
    
    Throws:
    
    DatabaseException
  - operationEnd
```
public abstract void operationEnd(boolean operationOK)
                           throws DatabaseException
```
    Different types of transactions do different things when the operation ends. Txn does nothing, auto Txn commits or aborts, and BasicLocker (and its subclasses) just releases locks.
    
    Parameters:
    
    operationOK - is whether the operation succeeded, since that may impact ending behavior. (i.e for an auto Txn)
    
    Throws:
    
    DatabaseException
  - isValid
```
public boolean isValid()
```
    Used to determine whether the locker is usable. FUTURE: Note that this method is overridden by Txn, and Txn.abort sets the state to closed when it begins rather than when it ends, but calls close() (the method above) when it ends. This is not ideal and deserves attention in the future.
  - addOpenedDatabase
```
public void addOpenedDatabase(Database dbHandle)
```
    See Also:
    
    Txn.addOpenedDatabase(com.sleepycat.je.Database)
  - allowReleaseLockAfterLsnChange
```
public boolean allowReleaseLockAfterLsnChange()
```
    See Also:
    
    HandleLocker.allowReleaseLockAfterLsnChange()
  - registerCursor
```
public abstract void registerCursor(CursorImpl cursor)
```
    Tell this transaction about a cursor.
  - unRegisterCursor
```
public abstract void unRegisterCursor(CursorImpl cursor)
```
    Remove a cursor from this txn.
  - lockingRequired
```
public abstract boolean lockingRequired()
```
    Returns true if locking is required for this Locker. All Txnal lockers require it; most BasicLockers do not, but BasicLockers on internal dbs do.
  - getWriteLockInfo
```
public abstract WriteLockInfo getWriteLockInfo(long lsn)
```
    Returns:
    
    the WriteLockInfo for this node.
  - addDbCleanup
```
public abstract void addDbCleanup(DbCleanup cleanup)
```
    Database operations like remove, truncate and rename require that DatabaseImpls are deleted or updated at transaction commit or abort.
  - addDeleteInfo
```
public void addDeleteInfo(BIN bin)
```
    Add delete information, to be added to the inCompressor queue when the transaction ends.
  - addLock
```
protected abstract void addLock(Long lsn,
                                LockType type,
                                LockGrantType grantStatus)
                         throws DatabaseException
```
    Add a lock to set owned by this transaction.
    
    Throws:
    
    DatabaseException
  - collectStats
```
public abstract StatGroup collectStats()
                                throws DatabaseException
```
    Get lock count, for per transaction lock stats, for internal debugging.
    
    Throws:
    
    DatabaseException
  - isTimedOut
```
public boolean isTimedOut()
```
  - getTxnTimeout
```
public long getTxnTimeout()
```
    Get the transaction timeout period for this locker, in milliseconds public for jca/ra/JELocalTransaction. WARNING: Be sure to always access the timeout with this accessor, since it is overridden in BuddyLocker.
  - isRolledBack
```
public boolean isRolledBack()
```
    Returns:
    
    if this locker has ever been rolled back.
  - toString
```
public String toString()
```
    This method is safe to call without synchronizing and this fact is relied on by LockManager when creating exception messages.
    
    Overrides:
    
    toString in class Object
  - dumpLockTable
```
public void dumpLockTable()
                   throws DatabaseException
```
    Dump lock table, for debugging
    
    Throws:
    
    DatabaseException

Class Locker

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

envImpl

lockManager

id

thread

afterWaiterHook

Constructor Detail

Locker

Method Detail

getInitialLockTimeout

getEnvironment

generateId

getId

getDefaultNoWait

setDefaultNoWait

getLockTimeout

setLockTimeout

setTxnTimeout

isReadUncommittedDefault

setOnlyAbortable

setImportunate

getImportunate

setPreemptable

getPreemptable

setPreempted

checkPreempted

setClosingLocker

checkState

openCursorHook

isReplicated

isLocalWrite

isReadOnly

lock

nonBlockingLock

releaseLock

demoteLock

lockAfterLsnChange

preLogWithoutLock

disallowReplicaWrite

isTransactional

isSerializableIsolation

isReadCommittedIsolation

getTxnLocker

getTransaction

newNonTxnLocker

releaseNonTxnLocks

nonTxnOperationEnd

sharesLocksWith

operationEnd

operationEnd

operationEnd

isValid

addOpenedDatabase

allowReleaseLockAfterLsnChange

registerCursor

unRegisterCursor

lockingRequired

getWriteLockInfo

addDbCleanup

addDeleteInfo

addLock

collectStats

isTimedOut

getTxnTimeout

isRolledBack

toString

dumpLockTable