oxenstored: comments explaining some variables

It took a while of reading and reasoning to work out what these are
for, so here are comments to make life easier for everyone reading
this code in future.

Reported-by: Juergen Gross <jgross@suse.com>
Signed-off-by: Thomas Sanders <thomas.sanders@citrix.com>
Reviewed-by: Jonathan Davies <jonathan.davies@citrix.com>
Reviewed-by: Ian Jackson <ian.jackson@eu.citrix.com>
Reviewed-by: Christian Lindig <christian.lindig@citrix.com>

diff --git a/tools/ocaml/xenstored/store.ml b/tools/ocaml/xenstored/store.ml
index 223ee21ebb89e915e77bdad1aef83a997c3b563d..9f619b8fd5470a9a8da9f48d7453ae3accdab7f7 100644 (file)
--- a/tools/ocaml/xenstored/store.ml
+++ b/tools/ocaml/xenstored/store.ml
@@ -211,6 +211,7 @@ let apply rnode path fct =
        lookup rnode path fct
 end
 
+(* The Store.t type *)
 type t =
 {
        mutable stat_transaction_coalesce: int;

diff --git a/tools/ocaml/xenstored/transaction.ml b/tools/ocaml/xenstored/transaction.ml
index 6b37fc2ad0a459858aebddba450e91799f7d609e..51d5d6a4049b080539f3be605130aa505098f14a 100644 (file)
--- a/tools/ocaml/xenstored/transaction.ml
+++ b/tools/ocaml/xenstored/transaction.ml
@@ -69,11 +69,15 @@ let can_coalesce oldroot currentroot path =
        else
                false
 
-type ty = No | Full of (int * Store.Node.t * Store.t)
+type ty = No | Full of (
+       int *          (* Transaction id *)
+       Store.Node.t * (* Original root *)
+       Store.t        (* A pointer to the canonical store: its root changes on each transaction-commit *)
+)
 
 type t = {
        ty: ty;
-       store: Store.t;
+       store: Store.t; (* This is the store that we change in write operations. *)
        quota: Quota.t;
        mutable paths: (Xenbus.Xb.Op.operation * Store.Path.t) list;
        mutable operations: (Packet.request * Packet.response) list;
@@ -155,7 +159,7 @@ let commit ~con t =
        let has_commited =
        match t.ty with
        | No                         -> true
-       | Full (id, oldroot, cstore) ->
+       | Full (id, oldroot, cstore) ->       (* "cstore" meaning current canonical store *)
                let commit_partial oldroot cstore store =
                        (* get the lowest path of the query and verify that it hasn't
                           been modified by others transactions. *)