update-locking: updating the documentation with extra information and tools

Change-type: patch

docs/update-locking.md

@@ -1,8 +1,8 @@
 ## Update locking
 
-Locking updates means that the Supervisor will not be able to kill your application. This is meant to be used at critical sections of your code where you don't want to be interrupted, or to control that updates are only installed at certain times.
+Locking updates means that the Supervisor will not be able to kill your application. This is meant to be used at critical sections of your code where you don't want to be interrupted, or to ensure that updates are only installed at certain times.
 
-In order to do this, users can create a file called `resin-updates.lock` that will prevent the Supervisor from killing and restarting the app. As any other lockfile, the Supervisor itself will create such file before killing the app, so you should only create it in exclusive mode. This means: only create the lockfile if it doesn't already exist. Several tools exist to simplify this process, for example [npm/lockfile](https://github.com/npm/lockfile).
+In order to do this, users can create a lockfile called `resin-updates.lock` in a way that it has exclusive access, which will prevent the Supervisor from killing and restarting the app. As with any other lockfile, the Supervisor itself will create such a file before killing the app, so you should only create it in exclusive mode. This means that the lockfile should only be created if it doesn't already exist. The exclusive access is achieved by opening the lockfile with the [O_EXCL and O_CREAT flags](https://linux.die.net/man/3/open), and several tools exist to simplify this process with examples given [below](#creating-the-lockfile).
 
 ### Location of the lockfile
 
@@ -16,26 +16,59 @@ assumption that updates are locked (see [issue #20](https://github.com/resin-io/
 
 In supervisors >= v4.0.0 and any OS that is not Resin OS 1.X, the old lock location is completely ignored.
 
-### Taking the lock
+### Creating the lockfile
 
-Using the above-mentioned library, the lock can be acquired like in this CoffeeScript example:
-```coffeescript
-	lockFile = require 'lockfile'
+There are many different tools and libraries to provide proper lockfile functionality and a few common examples are shown below.
 
-	lockFile.lock '/tmp/resin/resin-updates.lock', (err) ->
-		# A non-null err probably means the supervisor is about to kill us
-		throw new Error('Could not acquire lock: ', err) if err?
+__Note:__ Just creating the lockfile, for example by using `touch /tmp/resin/resin-updates.lock`, is not adequate to prevent updates. A file created in this way won't have the exclusive access flag set, and thus does not provide reliable locking.
 
-		# Here we have the lock, so we can do critical stuff:
-		doTheHarlemShake()
+#### Shell
 
-		# Now we release the lock, and we can be killed again
-		lockFile.unlock '/tmp/resin/resin-updates.lock', (err) ->
-			# If err is not null here, something went really wrong
-			throw err if err?
+One simple way to create a lockfile is using [lockfile](https://linux.die.net/man/1/lockfile) (available for example in Debian from the `procmail` package):
+
+```shell
+lockfile /tmp/resin/resin-updates.lock
+# ... (do things)
+rm -f /tmp/resin/resin-updates.lock
 ```
 
-There are other libraries you can use in different languages, for example [this Python library](http://pythonhosted.org/lockfile/lockfile.html#examples).
+Another tool is [flock](https://linux.die.net/man/1/flock) (available for example in Debian from the `linux-utils` package):
+
+```shell
+flock /tmp/resin/resin-updates.lock -c '... (command to run while locked)'
+```
+
+For more examples and explanation of the functionality, check the links to the specific tools above.
+
+#### Javascript and Coffeescript
+
+Using the [`lockfile` library](https://www.npmjs.com/package/lockfile), the lock can be acquired like in this CoffeeScript example:
+```coffeescript
+lockFile = require 'lockfile'
+
+lockFile.lock '/tmp/resin/resin-updates.lock', (err) ->
+	# A non-null err probably means the supervisor is about to kill us
+	throw new Error('Could not acquire lock: ', err) if err?
+
+	# Here we have the lock, so we can do critical stuff:
+	doTheHarlemShake()
+
+	# Now we release the lock, and we can be killed again
+	lockFile.unlock '/tmp/resin/resin-updates.lock', (err) ->
+		# If err is not null here, something went really wrong
+		throw err if err?
+```
+
+#### Python
+
+In Python you can use the [`lockfile` library](http://pythonhosted.org/lockfile/lockfile.html#examples)
+```python
+from lockfile import LockFile
+lock = LockFile("/tmp/resin/resin-updates.lock")
+with lock:
+    print lock.path, 'is locked.'
+```
+Check the link for more examples and other Python libraries that provide locking.
 
 ### Overriding the lock
 
@@ -43,4 +76,4 @@ The update lock can be overriden in case you need to force an update, for instan
 
 The way to do this is hitting the `/v1/update` endpoint of the [supervisor HTTP API](./API.md), with `{ "force": true }` as body.
 
-The lock can also be overriden by setting the app's `RESIN_OVERRIDE_LOCK` environment variable to "1".
+The lock can also be overriden by setting the app's `RESIN_SUPERVISOR_OVERRIDE_LOCK` configuration variable to "1".