bzrlib.lockdir.LockDir : API documentation

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.

Parameters	transport	Transport which will contain the lock
	path	Path to the lock within the base directory of the transport.
	extra_holder_info	If 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.)

Returns	The nonce of the lock, if it was successfully acquired.
Raises	LockContention	If 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.

Parameters other_holder A 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.

Returns LockResult 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.

Parameters	dead_holder_info	Must 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.
Returns	LockResult 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.

Parameters corrupt_info_lines the 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.

Returns	The lock token.
Raises	LockContention	if 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.

Parameters	token	if this is already locked, then lock_write will fail unless the token matches the existing lock.
Returns	a token if this instance supports tokens, otherwise None.
Raises	TokenLockingNotSupported	when a token is given but this instance doesn't support using token locks.
	MismatchedToken	if 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.

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

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