Create a maintenance mutex skeleton within luci-go

maintenancemutex/README.md

Index: maintenancemutex/README.md
diff --git a/maintenancemutex/README.md b/maintenancemutex/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..4b3b8843ee3558d458e69d3409e16e8b39f9ceb3
--- /dev/null
+++ b/maintenancemutex/README.md
@@ -0,0 +1,29 @@
+maintenancemutex

[iannucci, 2017/07/10 19:40:23]

rename the folder to 'mmutex' and have the README title look like

  Maintenance Mutex (mmutex)

[charliea (OOO until 10-5), 2017/07/10 19:56:50]

Done.

+================
+
+maintenancemutex is a command line tool that helps prevent maintenance tasks
+from running during performance sensitive tasks.

[iannucci, 2017/07/10 19:40:23]

s/performance sensitive/user everywhere

[charliea (OOO until 10-5), 2017/07/10 19:56:50]

Done.

+
+The command line tool uses a global lock file to prevent performance sensitive
+tasks from being run while potentially expensive system maintenance tasks are

[iannucci, 2017/07/10 19:40:22]

s/potentially expensive//

The point of the tool is to make all user and maintenance tasks mutually
exclusive (regardless of performance).

[charliea (OOO until 10-5), 2017/07/10 19:56:50]

Done.

+also being run.
+
+Clients can use this tool to request that their task be scheduled with one of

[iannucci, 2017/07/10 19:40:23]

s/scheduled/run

There's no 'deferral' happening in the tool, so 'run' is more direct than
'schedule'

[charliea (OOO until 10-5), 2017/07/10 19:56:50]

Done.

+two types of access to the system:
+
+  * **Exclusive access** guarantees that no other callers have any access
+    exclusive or shared) to the resource while the specified command is run.
+  * **Shared access** guarantees that only other callers with shared access
+    will have access to the resource while the specified command is run.
+
+In short, exclusive access guarantees a task is run alone, while shared access
+tasks may be run alongside other shared access tasks.
+
+Because an exclusive access task may wait indefinitely if shared access tasks
+continue to arrive before the previous one finishes, we use a second mechanism
+to prevent starvation of exclusive access tasks: a global drain file. This drain
+file is created before requesting exclusive access and signals that no shared
+access tasks should be run until the exclusive access task has had an
+opportunity to do so, at which point the global drain file is deleted.

[iannucci, 2017/07/10 19:40:23]

this paragraph might be a bit too detailed for a README, but not detailed enough
for an implementation doc. Consider having a separate md which details the
protocol.

[charliea (OOO until 10-5), 2017/07/10 19:56:50]

SGTM. I deleted it for now and will revisit whether it's necessary again in the
future.

+
+TODO(charliea): Document actual command line usage here.