pgsql-uavc-comments-update.patch

diff --git a/contrib/sepgsql/uavc.c b/contrib/sepgsql/uavc.c
index bcf0d4c..f28c398 100644
--- a/contrib/sepgsql/uavc.c
+++ b/contrib/sepgsql/uavc.c
@@ -133,10 +133,33 @@ sepgsql_avc_reclaim(void)
 /*
  * sepgsql_avc_check_valid
  *
- * It checks whether the cached entries are still valid, or not.
- * If security policy has been reloaded since last reference of access
- * vector cache, we have to release all the entries, because they are
- * not valid yet.
+ * It checks whether the cached entries still hold valid access control
+ * decision, or not. If the security policy has been reloaded (or any
+ * other events that requires to reset userspace caches) since last
+ * reference of access vector cache, we have to release all the entries
+ * being invalid.
+ *
+ * An access control decision must be done in atomic; from concurrent
+ * reloading of the security policy in kernel side, although it takes
+ * a few system call invocation for an access control decision; as we
+ * implemented in sepgsql_compute_avd().
+ * So, a typical implementation to reference avc should be enclosed by
+ * do { ... } while() loop, as follows:
+ *
+ *   sepgsql_avc_check_valid();
+ *   do {
+ *           :
+ *       <reference to uavc>
+ *           :
+ *   } while (!sepgsql_avc_check_valid())
+ *
+ * The first sepgsql_avc_check_valid() reset cached entries, if the
+ * security policy had been reloaded since the last call.
+ * The second call after references to uavc checks reload of the policy
+ * during reference to uavc, although it is quite rare.
+ * In this case, we retry the reference to uavc; it always invokes
+ * system call towards the new policy because sepgsql_avc_checl_valid()
+ * also takes sepgsql_avc_reset() when it returns false.
  */
 static bool
 sepgsql_avc_check_valid(void)
@@ -221,9 +244,15 @@ sepgsql_avc_compute(const char *scontext, const char *tcontext, uint16 tclass)
 		sepgsql_compute_avd(scontext, ucontext, tclass, &avd);
 
 	/*
-	 * To boost up trusted procedure checks on db_procedure object
-	 * class, we also confirm the decision when user calls a procedure
-	 * labeled as 'tcontext'.
+	 * It also caches a security label to be switched when a client
+	 * labeled as 'scontext' executes a procedure labeled as 'tcontext',
+	 * not only access control decision on the procedure.
+	 * The security label to be switched shall be computed uniquely on
+	 * a pair of 'scontext' and 'tcontext', thus, it is reasonable to
+	 * cache the new label on avc, and enables to reduce unnecessary
+	 * system calls.
+	 * It shall be referenced at sepgsql_needs_fmgr_hook to check whether
+	 * the supplied function is a trusted procedure, or not.
 	 */
 	if (tclass == SEPG_CLASS_DB_PROCEDURE)
 	{