linux-kernel - [PATCH] hashtable: add documentation for hash_for_each[

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-Id: <20211007234807.4292-1-richard.weiyang@gmail.com>
Date:   Thu,  7 Oct 2021 23:48:07 +0000
From:   Wei Yang <richard.weiyang@...il.com>
To:     kuba@...nel.org, gregkh@...uxfoundation.org, neilb@...e.com,
        mojha@...eaurora.org, jkosina@...e.cz
Cc:     linux-kernel@...r.kernel.org, Wei Yang <richard.weiyang@...il.com>
Subject: [PATCH] hashtable: add documentation for hash_for_each[_xxx]

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@...il.com>
Reviewed-by: NeilBrown <neilb@...e.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