libxl: Formally document libxl__xs_transaction

Provide a more formal description of the semantics of
libxl__xs_transaction_start, _commit and _abort, in addition to the
usage pattern example.

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>

diff --git a/tools/libxl/libxl_internal.h b/tools/libxl/libxl_internal.h
index 9e02861dadb33dc9cba534fd95d7055d77b8f21d..60a39eda2a7aa6849b79cac1375f3cccda05e52e 100644 (file)
--- a/tools/libxl/libxl_internal.h
+++ b/tools/libxl/libxl_internal.h
@@ -626,6 +626,26 @@ int libxl__xs_rm_checked(libxl__gc *gc, xs_transaction_t t, const char *path);
  *        // other cleanups
  *        return rc;
  *    }
+ *
+ * Formally the states of *t are:
+ *
+ *  name     value of *t  description
+ *   Idle         0         no transaction exists
+ *   Ready        non-0     ready for work, nothing done yet
+ *   Busy         non-0     writes have been made but we are not finished
+ *   Uncommitted  non-0     writes have been made and should be committed
+ *
+ * libxl__xs_transaction_start:  Idle -> Ready (on error: Idle)
+ *
+ * The transaction goes from Ready to Busy, and from Busy to
+ * Uncommitted, by the use of xenstore read and write operations
+ * (libxl__xs_..., xs_...) made by libxl__xs_transaction's caller.
+ *
+ * libxl__xs_transaction_commit:  Ready/Uncommitted -> Idle
+ *     on success (returns 0): xenstore has been updated
+ *     on error (<0) or conflict (+1): updates discarded
+ *
+ * libxl__xs_transaction_abort:  Any -> Idle  (any updates discarded)
  */
 int libxl__xs_transaction_start(libxl__gc *gc, xs_transaction_t *t);
 int libxl__xs_transaction_commit(libxl__gc *gc, xs_transaction_t *t);