Re: [PATCH v3 01/14] btrfs: Introduce btrfs_for_each_slot iterator macro

[David Sterba <dsterba@suse.cz>]

On Wed, Mar 02, 2022 at 05:48:16PM +0100, Gabriel Niebler wrote:
> There is a common pattern when searching for a key in btrfs:
> 
> * Call btrfs_search_slot to find the slot for the key
> * Enter an endless loop:
> 	* If the found slot is larger than the no. of items in the current leaf,
> 	  check the next leaf
> 	* If it's still not found in the next leaf, terminate the loop
> 	* Otherwise do something with the found key
> 	* Increment the current slot and continue
> 
> To reduce code duplication, we can replace this code pattern with an iterator
> macro, similar to the existing for_each_X macros found elsewhere in the kernel.
> This also makes the code easier to understand for newcomers by putting a name
> to the encapsulated functionality.
> 
> Signed-off-by: Marcos Paulo de Souza <mpdesouza@suse.com>
> Signed-off-by: Gabriel Niebler <gniebler@suse.com>
> ---
>  fs/btrfs/ctree.c | 33 +++++++++++++++++++++++++++++++++
>  fs/btrfs/ctree.h | 24 ++++++++++++++++++++++++
>  2 files changed, 57 insertions(+)
> 
> diff --git a/fs/btrfs/ctree.c b/fs/btrfs/ctree.c
> index a7db3f6f1b7b..d735bd472616 100644
> --- a/fs/btrfs/ctree.c
> +++ b/fs/btrfs/ctree.c
> @@ -2277,6 +2277,39 @@ int btrfs_search_backwards(struct btrfs_root *root, struct btrfs_key *key,
>  	return ret;
>  }
>  
> +/* Search for a valid slot for the given path.

Multi-line comments should start with
/*
 * Text ...
 * ...
 */

> + *
> + * @root: The root node of the tree.
> + * @key: Will contain a valid item if found.
> + * @path: The starting point to validate the slot.

Please align the descriptions, an example is here
https://btrfs.wiki.kernel.org/index.php/Development_notes#Comments

> + *
> + * Return 0 if the item is valid, 1 if not found and < 0 if error.
> + */
> +int btrfs_get_next_valid_item(struct btrfs_root *root, struct btrfs_key *key,
> +			      struct btrfs_path *path)
> +{
> +	while (1) {
> +		int ret;
> +		const int slot = path->slots[0];
> +		const struct extent_buffer *leaf = path->nodes[0];

Newline between declarations and statements.

> +		/* this is where we start walking through the path */

The comments should read like a sentence, so the first letter should be
uppercase unless it's an identifier.

> +		if (slot >= btrfs_header_nritems(leaf)) {
> +			/*
> +			 * if we've reached the last slot in this leaf we need
> +			 * to go to the next leaf and reset the path
> +			 */
> +			ret = btrfs_next_leaf(root, path);
> +			if (ret)
> +				return ret;
> +			continue;
> +		}
> +		/* store the found, valid item in key */
> +		btrfs_item_key_to_cpu(leaf, key, slot);
> +		break;
> +	}
> +	return 0;
> +}
> +
>  /*
>   * adjust the pointers going up the tree, starting at level
>   * making sure the right key of each node is points to 'key'.
> diff --git a/fs/btrfs/ctree.h b/fs/btrfs/ctree.h
> index 947f04789389..98091334b749 100644
> --- a/fs/btrfs/ctree.h
> +++ b/fs/btrfs/ctree.h
> @@ -2976,6 +2976,30 @@ int btrfs_next_old_leaf(struct btrfs_root *root, struct btrfs_path *path,
>  int btrfs_search_backwards(struct btrfs_root *root, struct btrfs_key *key,
>  			   struct btrfs_path *path);
>  
> +int btrfs_get_next_valid_item(struct btrfs_root *root, struct btrfs_key *key,
> +			      struct btrfs_path *path);
> +
> +/* Search in @root for a given @key, and store the slot found in @found_key.
> + *
> + * @root: The root node of the tree.
> + * @key: The key we are looking for.
> + * @found_key: Will hold the found item.
> + * @path: Holds the current slot/leaf.
> + * @iter_ret: Contains the value returned from btrfs_search_slot or
> + *            btrfs_get_next_valid_item, whichever was executed last.
> + *
> + * The iter_ret is an output variable that will contain the return value of
> + * btrfs_search_slot, if it encountered an error, or the value returned from
> + * btrfs_get_next_valid_item, otherwise. That return value can be 0, if a valid
> + * slot was found, 1 if there were no more leaves, and <0 if there was an error.
> + */
> +#define btrfs_for_each_slot(root, key, found_key, path, iter_ret)		\
> +	for (iter_ret = btrfs_search_slot(NULL, root, key, path, 0, 0);		\
> +		iter_ret >= 0 &&						\
> +		(iter_ret = btrfs_get_next_valid_item(root, found_key, path)) == 0; \
> +		path->slots[0]++						  \

As the arguments can be more than just an identifier it's safer to put
them in ( ) in the definition, ie root/key/found_key/path/iter_ret
shouls be all (root) etc