added db mutex code

Author: wesleykendall

.gitignore

@@ -0,0 +1,16 @@
+# Compiled python files
+*.pyc
+
+# Vim files
+*.swp
+*.swo
+
+# Coverage files
+.coverage
+
+# Setuptools distribution folder.
+/dist/
+
+# Python egg metadata, regenerated from source files by setuptools.
+/*.egg-info
+/*.egg

.travis.yml

@@ -0,0 +1,15 @@
+language: python
+python:
+  - '2.7'
+env:
+  - DJANGO=1.6.1 DB=postgres
+install:
+  - pip install -q Django==$DJANGO
+  - pip install -r requirements.txt
+before_script:
+  - find . | grep .py$ | grep -v /migrations | xargs pep8 --max-line-length=120
+  - find . | grep .py$ | grep -v /migrations | grep -v __init__.py | xargs pyflakes
+  - psql -c 'CREATE DATABASE db_mutex;' -U postgres
+script:
+  - coverage run --source='db_mutex' --branch manage.py test
+  - coverage report --fail-under=100

MANIFEST.in

@@ -0,0 +1,3 @@
+include db_mutex/VERSION
+include README.md
+include LICENSE

db_mutex/VERSION

@@ -0,0 +1 @@
+0.1

db_mutex/__init__.py

@@ -0,0 +1 @@
+from .db_mutex import DBMutexError, DBMutexTimeoutError, db_mutex

db_mutex/db_mutex.py

@@ -0,0 +1,129 @@
+from datetime import datetime, timedelta
+import functools
+
+from django.conf import settings
+from django.db import transaction, IntegrityError
+
+from .models import DBMutex
+
+
+class DBMutexError(Exception):
+    """
+    Thrown when a lock cannot be acquired.
+    """
+    pass
+
+
+class DBMutexTimeoutError(Exception):
+    """
+    Thrown when a lock times out before it is released.
+    """
+    pass
+
+
+class db_mutex(object):
+    """
+    An object that acts as a context manager and a function decorator for acquiring a
+    DB mutex lock.
+
+    Args:
+        lock_id: The ID of the lock one is trying to acquire
+
+    Raises:
+        DBMutexError when the lock cannot be obtained
+        DBMutexTimeoutError when the lock was deleted during execution
+
+    Examples:
+        This context manager/function decorator can be used in the following way
+
+        from db_mutex import db_mutex
+
+        # Lock a critical section of code
+        try:
+            with db_mutex('lock_id'):
+                # Run critical code here
+                pass
+        except DBMutexError:
+            print 'Could not obtain lock'
+        except DBMutexTimeoutError:
+            print 'Task completed but the lock timed out'
+
+        # Lock a function
+        @db_mutex('lock_id'):
+        def critical_function():
+            # Critical code goes here
+            pass
+
+        try:
+            critical_function()
+        except DBMutexError:
+            print 'Could not obtain lock'
+        except DBMutexTimeoutError:
+            print 'Task completed but the lock timed out'
+    """
+    mutex_ttl_seconds_settings_key = 'DB_MUTEX_TTL_SECONDS'
+
+    def __init__(self, lock_id):
+        self.lock_id = lock_id
+        self.lock = None
+
+    def get_mutex_ttl_seconds(self):
+        """
+        Returns a TTL for mutex locks. It defaults to 30 minutes. If the user specifies None
+        as the TTL, locks never expire.
+        """
+        if hasattr(settings, self.mutex_ttl_seconds_settings_key):
+            return getattr(settings, self.mutex_ttl_seconds_settings_key)
+        else:
+            return 30 * 60
+
+    def delete_expired_locks(self):
+        """
+        Deletes all expired mutex locks if a ttl is provided.
+        """
+        ttl_seconds = self.get_mutex_ttl_seconds()
+        if ttl_seconds is not None:
+            DBMutex.objects.filter(creation_time__lte=datetime.utcnow() - timedelta(seconds=ttl_seconds)).delete()
+
+    def __call__(self, func):
+        return self.decorate_callable(func)
+
+    def __enter__(self):
+        self.start()
+
+    def __exit__(self, *args):
+        self.stop()
+
+    def start(self):
+        """
+        Acquires the db mutex lock. Takes the necessary steps to delete any stale locks.
+        Throws a DBMutexError if it can't acquire the lock.
+        """
+        # Delete any expired locks first
+        self.delete_expired_locks()
+        try:
+            with transaction.atomic():
+                self.lock = DBMutex.objects.create(lock_id=self.lock_id)
+        except IntegrityError:
+            raise DBMutexError('Could not acquire lock: {0}'.format(self.lock_id))
+
+    def stop(self):
+        """
+        Releases the db mutex lock. Throws an error if the lock was released before the function finished.
+        """
+        if not DBMutex.objects.filter(id=self.lock.id).exists():
+            raise DBMutexTimeoutError('Lock {0} expired before function completed'.format(self.lock_id))
+        else:
+            self.lock.delete()
+
+    def decorate_callable(self, func):
+        """
+        Decorates a function with the db_mutex decorator by using this class as a context manager around
+        it.
+        """
+        def wrapper(*args, **kwargs):
+            with self:
+                result = func(*args, **kwargs)
+            return result
+        functools.update_wrapper(wrapper, func)
+        return wrapper

db_mutex/migrations/0001_initial.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+import datetime
+from south.db import db
+from south.v2 import SchemaMigration
+from django.db import models
+
+
+class Migration(SchemaMigration):
+
+    def forwards(self, orm):
+        # Adding model 'DBMutex'
+        db.create_table(u'db_mutex_dbmutex', (
+            (u'id', self.gf('django.db.models.fields.AutoField')(primary_key=True)),
+            ('lock_id', self.gf('django.db.models.fields.CharField')(unique=True, max_length=256)),
+            ('creation_time', self.gf('django.db.models.fields.DateTimeField')(auto_now_add=True, blank=True)),
+        ))
+        db.send_create_signal(u'db_mutex', ['DBMutex'])
+
+
+    def backwards(self, orm):
+        # Deleting model 'DBMutex'
+        db.delete_table(u'db_mutex_dbmutex')
+
+
+    models = {
+        u'db_mutex.dbmutex': {
+            'Meta': {'object_name': 'DBMutex'},
+            'creation_time': ('django.db.models.fields.DateTimeField', [], {'auto_now_add': 'True', 'blank': 'True'}),
+            u'id': ('django.db.models.fields.AutoField', [], {'primary_key': 'True'}),
+            'lock_id': ('django.db.models.fields.CharField', [], {'unique': 'True', 'max_length': '256'})
+        }
+    }
+
+    complete_apps = ['db_mutex']

db_mutex/migrations/__init__.py

@@ -0,0 +1,9 @@
+from django.db import models
+
+
+class DBMutex(models.Model):
+    """
+    Models a mutex lock with a lock ID and a creation time.
+    """
+    lock_id = models.CharField(max_length=256, unique=True)
+    creation_time = models.DateTimeField(auto_now_add=True)

db_mutex/models.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python
+import os
+import sys
+
+if __name__ == '__main__':
+    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'test_project.settings')
+
+    from django.core.management import execute_from_command_line
+
+    execute_from_command_line(sys.argv)