Repository files navigation

Sherlock is a library that provides easy-to-use distributed inter-processlocks and also allows you to choose a backend of your choice for locksynchronization.

When you are working with resources which are accessed by multiple services ordistributed services, more than often you need some kind of locking mechanismto make it possible to access some resources at a time.

Distributed Locks or Mutexes can help you with this. Sherlock providesthe exact same facility, with some extra goodies. It provides an easy-to-use APIthat resembles standard library's threading.Lock semantics.

Apart from this, Sherlock gives you the flexibility of using a backend ofyour choice for managing locks.

Sherlock also makes it simple for you to extend Sherlock to usebackends that are not supported.

• API similar to standard library's threading.Lock.
• Support for With statement, to cleanly acquire and release locks.
• Backend agnostic: supports File,Redis,Memcached,Etcd, andKubernetes as choice ofbackends.
• Extendable: can be easily extended to work with any other of backend ofchoice by extending base lock class. Readextending.

Following client libraries are supported for every supported backend:

• File:filelock
• Redis:redis-py
• Memcached:pylibmc
• Etcd:python-etcd
• Kubernetes:kubernetes

As of now, only the above mentioned libraries are supported. AlthoughSherlock takes custom client objects so that you can easily providesettings that you want to use for that backend store, but Sherlock alsochecks if the provided client object is an instance of the supported clientsand accepts client objects which pass this check, even if the APIs are thesame. Sherlock might get rid of this issue later, if need be and ifthere is a demand for that.

Installation is simple.

pip install sherlock[all]

Sherlock is simple to use as at the API and semantics level, it tries toconform to standard library'sthreading.Lock APIs.

importsherlockfromsherlockimportLock# Configure Sherlock's locks to use Redis as the backend,# never expire locks and retry acquiring an acquired lock after an# interval of 0.1 second.sherlock.configure(backend=sherlock.backends.REDIS,expire=None,retry_interval=0.1)# Note: configuring sherlock to use a backend does not limit you# another backend at the same time. You can import backend specific locks# like RedisLock, MCLock and EtcdLock and use them just the same way you# use a generic lock (see below). In fact, the generic Lock provided by# sherlock is just a proxy that uses these specific locks under the hood.# acquire a lock called my_locklock=Lock('my_lock')# acquire a blocking locklock.acquire()# check if the lock has been acquired or notlock.locked()==True# attempt to renew the locklock.renew()# release the locklock.release()

# using with statementwithLock('my_lock')aslock:# do something constructive with your locked resource herepass

# acquire non-blocking locklock1=Lock('my_lock')lock2=Lock('my_lock')# successfully acquire lock1lock1.acquire()# try to acquire lock in a non-blocking waylock2.acquire(False)==True# returns False# try to acquire lock in a blocking waylock2.acquire()# blocks until lock is acquired to timeout happens

Configuring Sherlock to use a backend does not limit you from usinganother backend at the same time. You can import backend specific locks likeRedisLock, MCLock and EtcdLock and use them just the same way you use a genericlock (see below). In fact, the generic Lock provided by Sherlock is justa proxy that uses these specific locks under the hood.

importsherlockfromsherlockimportLock# Configure Sherlock's locks to use Redis as the backendsherlock.configure(backend=sherlock.backends.REDIS)# Acquire a lock called my_lock, this lock uses Redislock=Lock('my_lock')# Now acquire locks in MemcachedfromsherlockimportMCLockmclock=MCLock('my_mc_lock')mclock.acquire()

To run all the tests (including integration), you have to make sure that allthe databases are running. Make sure all the services are running:

# memcachedmemcached# redis-serverredis-server# etcd (etcd is probably not available as package, here is the simplest way# to run it).wget https://github.com/coreos/etcd/releases/download/<version>/etcd-<version>-<platform>.tar.gztar -zxvf etcd-<version>-<platform>.gz./etcd-<version>-<platform>/etcd

Run tests like so:

python setup.pytest

Availablehere.

SeeLICENSE.

In short: This is an open-source project and exists for anyone to use itand/or modify it for personal use. Just be nice and attribute the creditswherever you can. :)

You are encouraged to ask questions usingissues as that helps everyone andmyself when people with better know-how contribute to the discussion. However,if you wish to get in touch with me personally, then I can be contacted atkapoor.vaidik++github+sherlock@gmail.com.

• NodeJS -https://github.com/thedeveloper/warlock