From 6421f2c6d90032d76314c4c084238172c10d23b8 Mon Sep 17 00:00:00 2001
From: David Lamparter <equinox@diac24.net>
Date: Tue, 6 Aug 2019 12:05:09 +0200
Subject: [PATCH] doc: add developer docs for frr_with_mutex

Signed-off-by: David Lamparter <equinox@opensourcerouting.org>
---
 doc/developer/library.rst |  1 +
 doc/developer/locking.rst | 73 +++++++++++++++++++++++++++++++++++++++
 doc/developer/subdir.am   |  1 +
 3 files changed, 75 insertions(+)
 create mode 100644 doc/developer/locking.rst

diff --git a/doc/developer/library.rst b/doc/developer/library.rst
index 7cd493ccc4..a904a4e778 100644
--- a/doc/developer/library.rst
+++ b/doc/developer/library.rst
@@ -11,6 +11,7 @@ Library Facilities (libfrr)
    rcu
    lists
    logging
+   locking
    hooks
    cli
    modules
diff --git a/doc/developer/locking.rst b/doc/developer/locking.rst
new file mode 100644
index 0000000000..aee05aae06
--- /dev/null
+++ b/doc/developer/locking.rst
@@ -0,0 +1,73 @@
+Locking
+=======
+
+FRR ships two small wrappers around ``pthread_mutex_lock()`` /
+``pthread_mutex_unlock``.  Use ``#include "frr_pthread.h"`` to get these
+macros.
+
+.. c:function:: frr_with_mutex(pthread_mutex_t *mutex)
+
+   Begin a C statement block that is executed with the mutex locked.  Any
+   exit from the block (``break``, ``return``, ``goto``, end of block) will
+   cause the mutex to be unlocked::
+
+      int somefunction(int option)
+      {
+          frr_with_mutex(&my_mutex) {
+              /* mutex will be locked */
+
+              if (!option)
+                  /* mutex will be unlocked before return */
+                  return -1;
+
+              if (something(option))
+                  /* mutex will be unlocked before goto */
+                  goto out_err;
+
+              somethingelse();
+
+              /* mutex will be unlocked at end of block */
+          }
+
+          return 0;
+
+      out_err:
+          somecleanup();
+          return -1;
+      }
+
+   This is a macro that internally uses a ``for`` loop.  It is explicitly
+   acceptable to use ``break`` to get out of the block.  Even though a single
+   statement works correctly, FRR coding style requires that this macro always
+   be used with a ``{ ... }`` block.
+
+.. c:function:: frr_mutex_lock_autounlock(pthread_mutex_t *mutex)
+
+   Lock mutex and unlock at the end of the current C statement block::
+
+      int somefunction(int option)
+      {
+          frr_mutex_lock_autounlock(&my_mutex);
+          /* mutex will be locked */
+
+          ...
+          if (error)
+            /* mutex will be unlocked before return */
+            return -1;
+          ...
+
+          /* mutex will be unlocked before return */
+          return 0;
+      }
+
+   This is a macro that internally creates a variable with a destructor.
+   When the variable goes out of scope (i.e. the block ends), the mutex is
+   released.
+
+   .. warning::
+
+      This macro should only used when :c:func:`frr_with_mutex` would
+      result in excessively/weirdly nested code.  This generally is an
+      indicator that the code might be trying to do too many things with
+      the lock held.  Try any possible venues to reduce the amount of
+      code covered by the lock and move to :c:func:`frr_with_mutex`.
diff --git a/doc/developer/subdir.am b/doc/developer/subdir.am
index 1fc593e566..557a41c51f 100644
--- a/doc/developer/subdir.am
+++ b/doc/developer/subdir.am
@@ -31,6 +31,7 @@ dev_RSTFILES = \
 	doc/developer/index.rst \
 	doc/developer/library.rst \
 	doc/developer/lists.rst \
+	doc/developer/locking.rst \
 	doc/developer/logging.rst \
 	doc/developer/maintainer-release-build.rst \
 	doc/developer/memtypes.rst \
-- 
2.39.5