Creating a locked resource

Any mutable shared resource must be locked.

Example: using a resource

from MoinMoin import lock
resource = lock.sharedResource('resource_name', writeTimeout=None, 
                               updateTimeout=None, readTimeout=None)

This will create the directory wiki/data/lock/resource_name, which will hold the locks for this resourse.

Only one instance can be created for a 'resource_name'. Calling again will return the same instance.

Clients can shoot themselves into the foot by using two SharedResoruces instances with different names for the same physical resource. See also WYGIWYD

Questions

Do we need to enable changing the timeouts after creation?
Do we need to enable removing a resource?
- They should be automatically removed when there lifetime has ended
  - What it the lifetime of a resource?
What should happen if you call sharedResource on the second time with different timeouts than the first call?
- The timeouts will be updated to the new values affecting all the current locks that access the timeouts from the shared instance?

Options:

Create a resource with lock.addSharedResource(key, *timeouts)
- You can call this only once per resource
Access with lock.sharedResource(key), or directly from the object to be locked, object.sharedResource()

Creating a ReadLock

When you want to use the resource, you must acquire a ReadLock. This will prevent other processes or threads from acquiring a WriteLock and changing the data while you read it.

Example: using a read lock:

readLock = resource.readLock()
if readlock.acquire(timeout):
    try:
        # read the resource
    finally:
        readLock.release()

You can create many ReadLocks as you need for one resource, in the same process or in many processes or threads.

A read lock will create wiki/data/lock/resource_name/read_XXXXX. XXXX is a unique name created with tempfile.mkdtemp. Each lock will have a new unique directory in the resource directory.

Creating a WriteLock

When you want to replace the resource, you must acquire a WriteLock. This will prevent others from acquiring new ReadLocks or UpdateLocks. This lock must be used for the shortest time possible.

Only one WriteLock can be acquired.

Exmaple: using a WriteLock

writeLock = resource. writeLock()
if writeLock.acquire(timeout):
    try:
        # write the resource
    finally:
        writeLock.release()

A write lock will create wiki/data/lock/resource_name/write.

A WriteLock will be acquired only if there are no active ReadLocks or UpdateLock in the lock directory.

Creating an UpdateLock

When you want to replace the resource, but making the replacement will take long time and you don't want to make the resource unreadable, you create an UpdateLock. This will prevent others from acquiring a WriteLock and changing the resource while you read it. This will let other to create ReadLocks, and use the current state of the resource, while you update it to a new state in a temporary location.

Only one UpdateLock can be acquired.

Exmaple: using an UpdateLock

lock = resource.updateLock()
if lock.acquire(timeout):
    try:
        # copy the resource to temporary location
        # change the copy
        if lock.upgrade(WriteLock, timeout):
            # replace the old resource with the updated copy
    finally:
        lock.release()

An update lock will create wiki/data/lock/resource_name/update.

Expiring locks

Any expired locks in the directory will be removed when trying to acquire a new WriteLock or UpdateLock. The timeouts are the timeouts used in the constructor: writeTimeout, updateTimeout, readTimeout.

Any lock with age bigger then the timeout for that lock kind will be removed.

Converting a lock

To convert a read lock or an update lock to a write lock, call convert(LockClass, timeout). The lock will try to acquire a LockClass and remove the original lock directory.

Typical use:

lock = resource.updateLock()
if lock.acquire(timeout):
    try:
        # do the update
        if lock.convert(WriteLock, timeout):
            # write
    finally:
        lock.release()

Possible implementation:

    def convert(lockClass, timeout=None):
        if lockClass == self.__class__:
            raise LockConvertError('same class')
        delegate = lockClass(self.dir)
        if delegate.acquire(timeout):
            self._removeLockDir()
            self.delegate = delegate
            # from now on, everything should be delegated to self.delegate
            return True
        return False

Making a resource lockable

To make other developers life easier and prevent locking errors, each lockable class should supply a sharedResource method, with good default timeouts.

class Page:

    def sharedResource(writeTimeout=60, updateTimeout=3600, readTimeout=60):
        return lock.sharedResource(self.getPagePath('lock'), writeTimeout, updateTimeout, 
                                   readTimeout)

Now to lock a page, the client work directly with the page object:

lock = page.sharedResource().readLock()
if lock.acquire(timeout):
    try:
        # read page
    finally:
        lock.release()

Todo

Create a stress tests for locking, take stuff from AlexanderSchremmer/FileLocking

MoinMoin: LockingSpecification