From: Alan T. DeKok <aland@freeradius.org>
Date: Wed, 20 Jul 2022 13:45:52 +0000 (-0400)
Subject: comments and docs
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d80b803ff1cc0f490d7ca5b38a1a2c4c70aef3ea;p=thirdparty%2Ffreeradius-server.git

comments and docs
---

diff --git a/src/lib/util/edit.c b/src/lib/util/edit.c
index bc21cb6b7ac..faf5efe1897 100644
--- a/src/lib/util/edit.c
+++ b/src/lib/util/edit.c
@@ -20,6 +20,28 @@
  * @file src/lib/util/edit.c
  * @brief Functions to edit pair lists, and track undo operations
  *
+ *  This file implements an "edit list" for changing values of
+ *  #fr_pair_t.  After some investigation, it turns out that it's much
+ *  easier to have an "undo list" than to track partially applied
+ *  transactions.  Tracking partial transactions means that none of
+ *  the fr_pair_foo() functions will work, as some pairs are in the
+ *  "old" list and some in the "new" list.  Also, a transaction may
+ *  still fail when we finalize it by moving the pairs around.
+ *
+ *  In contrast, an "undo" list means that all of the fr_pair_foo()
+ *  functions will work, as any list contains only "active" pairs.
+ *  And we never need to "finalize" a transaction, as the lists are
+ *  already in their final form.  The only thing needed for
+ *  finalization is to free the undo list.  Which can never fail.
+ *
+ *  Note that the functions here require the input VPs to already have
+ *  the correct talloc parent!  The only thing the edit list does is
+ *  to record "undo" actions.
+ *
+ *  The only exception to this is fr_edit_list_apply_list_assignment().
+ *  Which does call talloc_steal, and then also frees any pairs which
+ *  weren't applied to the LHS.
+ *
  * @copyright 2021 Network RADIUS SAS (legal@networkradius.com)
  */