Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Wei Yang <richard.weiyang@gmail.com>
To:     kuba@kernel.org, gregkh@linuxfoundation.org, neilb@suse.com,
        mojha@codeaurora.org, jkosina@suse.cz
Cc:     linux-kernel@vger.kernel.org, Wei Yang <richard.weiyang@gmail.com>
Subject: [PATCH] hashtable: add documentation for hash_for_each[_xxx]
Date:   Thu,  7 Oct 2021 23:48:07 +0000
Message-Id: <20211007234807.4292-1-richard.weiyang@gmail.com>
Precedence: bulk

hash_for_each[_xxx] introduce a new loop command constructed from 2
nested loops. To make it work like normal loop, 'obj == NULL' is
explicitly put in loop check to break out not only inner loop but also
the outer loop.

This patch adds a documentation to clarify this behavior.

Signed-off-by: Wei Yang <richard.weiyang@gmail.com>
Reviewed-by: NeilBrown <neilb@suse.de>
---
 include/linux/hashtable.h | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/include/linux/hashtable.h b/include/linux/hashtable.h
index f6c666730b8c..355681c632ff 100644
--- a/include/linux/hashtable.h
+++ b/include/linux/hashtable.h
@@ -122,6 +122,10 @@ static inline void hash_del_rcu(struct hlist_node *node)
  * @bkt: integer to use as bucket loop cursor
  * @obj: the type * to use as a loop cursor for each entry
  * @member: the name of the hlist_node within the struct
+ *
+ * Note: It is safe to 'break' out of this loop even though it is a two nested
+ * loops.  The 'obj == NULL' test ensures that when the inner loop is broken,
+ * the outer loop will break too.
  */
 #define hash_for_each(name, bkt, obj, member)				\
 	for ((bkt) = 0, obj = NULL; obj == NULL && (bkt) < HASH_SIZE(name);\
@@ -134,6 +138,8 @@ static inline void hash_del_rcu(struct hlist_node *node)
  * @bkt: integer to use as bucket loop cursor
  * @obj: the type * to use as a loop cursor for each entry
  * @member: the name of the hlist_node within the struct
+ *
+ * Note: It is safe to 'break' out of this loop.
  */
 #define hash_for_each_rcu(name, bkt, obj, member)			\
 	for ((bkt) = 0, obj = NULL; obj == NULL && (bkt) < HASH_SIZE(name);\
@@ -148,6 +154,8 @@ static inline void hash_del_rcu(struct hlist_node *node)
  * @tmp: a &struct hlist_node used for temporary storage
  * @obj: the type * to use as a loop cursor for each entry
  * @member: the name of the hlist_node within the struct
+ *
+ * Note: It is safe to 'break' out of this loop.
  */
 #define hash_for_each_safe(name, bkt, tmp, obj, member)			\
 	for ((bkt) = 0, obj = NULL; obj == NULL && (bkt) < HASH_SIZE(name);\
-- 
2.23.0