b.l.LockDir(lock.Lock) : class documentation

Part of bzrlib.lockdir View In Hierarchy

Write-lock guarding access to data.
Method __init__ Create a new LockDir object.
Method __repr__ Undocumented
Method create Create the on-disk lock.
Method unlock Release a held lock
Method break_lock Break a lock not held by this instance of LockDir.
Method force_break Release a lock held by another process.
Method force_break_corrupt Release a lock that has been corrupted.
Method confirm Make sure that the lock is still held by this locker.
Method peek Check if the lock is held by anyone.
Method attempt_lock Take the lock; fail if it's already held.
Method lock_url_for_display Give a nicely-printable representation of the URL of this lock.
Method wait_lock Wait a certain period for a lock.
Method leave_in_place Undocumented
Method dont_leave_in_place Undocumented
Method lock_write Wait for and acquire the lock.
Method lock_read Compatibility-mode shared lock.
Method validate_token Undocumented
Method get_config Get the configuration that governs this lockdir.
Method _attempt_lock Make the pending directory and attempt to rename into place.
Method _handle_lock_contention A lock we want to take is held by someone else.
Method _remove_pending_dir Remove the pending directory
Method _create_pending_dir Undocumented
Method _check_not_locked If the lock is held by this instance, raise an error.
Method _read_info_file Read one given info file.
Method _prepare_info Write information about a pending lock to a temporary file.
Method _trace Undocumented
def __init__(self, transport, path, file_modebits=420, dir_modebits=493, extra_holder_info=None):
Create a new LockDir object.

The LockDir is initially unlocked - this just creates the object.

ParameterstransportTransport which will contain the lock
pathPath to the lock within the base directory of the transport.
extra_holder_infoIf passed, {str:str} dict of extra or updated information to insert into the info file when the lock is taken.
def __repr__(self):
Undocumented
def create(self, mode=None):
Create the on-disk lock.

This is typically only called when the object/directory containing the directory is first created. The lock is not held when it's created.

def _attempt_lock(self):
Make the pending directory and attempt to rename into place.

If the rename succeeds, we read back the info file to check that we really got the lock.

If we fail to acquire the lock, this method is responsible for cleaning up the pending directory if possible. (But it doesn't do that yet.)

ReturnsThe nonce of the lock, if it was successfully acquired.
RaisesLockContentionIf the lock is held by someone else. The exception contains the info of the current holder of the lock.
def _handle_lock_contention(self, other_holder):
A lock we want to take is held by someone else.

This function can: tell the user about it; possibly detect that it's safe or appropriate to steal the lock, or just raise an exception.

If this function returns (without raising an exception) the lock will be attempted again.

Parametersother_holderA LockHeldInfo for the current holder; note that it might be None if the lock can be seen to be held but the info can't be read.
def _remove_pending_dir(self, tmpname):
Remove the pending directory

This is called if we failed to rename into place, so that the pending dirs don't clutter up the lockdir.

def _create_pending_dir(self):
Undocumented
@only_raises(LockNotHeld, LockBroken)
def unlock(self):
Release a held lock
def break_lock(self):
Break a lock not held by this instance of LockDir.

This is a UI centric function: it uses the ui.ui_factory to prompt for input if a lock is detected and there is any doubt about it possibly being still active. force_break is the non-interactive version.

ReturnsLockResult for the broken lock.
def force_break(self, dead_holder_info):
Release a lock held by another process.

WARNING: This should only be used when the other process is dead; if it still thinks it has the lock there will be two concurrent writers. In general the user's approval should be sought for lock breaks.

After the lock is broken it will not be held by any process. It is possible that another process may sneak in and take the lock before the breaking process acquires it.

Parametersdead_holder_infoMust be the result of a previous LockDir.peek() call; this is used to check that it's still held by the same process that the user decided was dead. If this is not the current holder, LockBreakMismatch is raised.
ReturnsLockResult for the broken lock.
def force_break_corrupt(self, corrupt_info_lines):
Release a lock that has been corrupted.

This is very similar to force_break, it except it doesn't assume that self.peek() can work.

Parameterscorrupt_info_linesthe lines of the corrupted info file, used to check that the lock hasn't changed between reading the (corrupt) info file and calling force_break_corrupt.
def _check_not_locked(self):
If the lock is held by this instance, raise an error.
def confirm(self):
Make sure that the lock is still held by this locker.

This should only fail if the lock was broken by user intervention, or if the lock has been affected by a bug.

If the lock is not thought to be held, raises LockNotHeld. If the lock is thought to be held but has been broken, raises LockBroken.

def _read_info_file(self, path):
Read one given info file.

peek() reads the info file of the lock holder, if any.

def peek(self):
Check if the lock is held by anyone.

If it is held, this returns the lock info structure as a dict which contains some information about the current lock holder. Otherwise returns None.

def _prepare_info(self):
Write information about a pending lock to a temporary file.
def attempt_lock(self):
Take the lock; fail if it's already held.

If you wish to block until the lock can be obtained, call wait_lock() instead.

ReturnsThe lock token.
RaisesLockContentionif the lock is held by someone else.
def lock_url_for_display(self):
Give a nicely-printable representation of the URL of this lock.
def wait_lock(self, timeout=None, poll=None, max_attempts=None):
Wait a certain period for a lock.

If the lock can be acquired within the bounded time, it
is taken and this returns.  Otherwise, LockContention
is raised.  Either way, this function should return within
approximately `timeout` seconds.  (It may be a bit more if
a transport operation takes a long time to complete.)

:param timeout: Approximate maximum amount of time to wait for the
lock, in seconds.

:param poll: Delay in seconds between retrying the lock.

:param max_attempts: Maximum number of times to try to lock.

:return: The lock token.
def leave_in_place(self):
Undocumented
def dont_leave_in_place(self):
Undocumented
def lock_write(self, token=None):
Wait for and acquire the lock.

A token should be passed in if you know that you have locked the object some other way, and need to synchronise this object's state with that fact.

XXX: docstring duplicated from LockableFiles.lock_write.

Parameterstokenif this is already locked, then lock_write will fail unless the token matches the existing lock.
Returnsa token if this instance supports tokens, otherwise None.
RaisesTokenLockingNotSupportedwhen a token is given but this instance doesn't support using token locks.
MismatchedTokenif the specified token doesn't match the token of the existing lock.
def lock_read(self):
Compatibility-mode shared lock.

LockDir doesn't support shared read-only locks, so this just pretends that the lock is taken but really does nothing.

def validate_token(self, token):
Undocumented
def _trace(self, format, *args):
Undocumented
def get_config(self):
Get the configuration that governs this lockdir.
API Documentation for Bazaar, generated by pydoctor at 2019-08-17 00:32:45.