Re: [PATCH 1/9] mempool: update kerneldoc comments

Eric Biggers
2025-11-07T03:28:28Z

On Fri, Oct 31, 2025 at 10:34:31AM +0100, Christoph Hellwig wrote:
> diff --git a/mm/mempool.c b/mm/mempool.c
> index 1c38e873e546..d7c55a98c2be 100644
> --- a/mm/mempool.c
> +++ b/mm/mempool.c
> @@ -372,18 +372,15 @@ int mempool_resize(mempool_t *pool, int new_min_nr)
> EXPORT_SYMBOL(mempool_resize);
>
> /**
> - * mempool_alloc - allocate an element from a specific memory pool
> - * @pool: pointer to the memory pool which was allocated via
> - * mempool_create().
> - * @gfp_mask: the usual allocation bitmask.
> + * mempool_alloc - allocate an element from a memory pool
> + * @pool: pointer to the memory pool
> + * @gfp_mask: GFP_* flags.
> *
> - * this function only sleeps if the alloc_fn() function sleeps or
> - * returns NULL. Note that due to preallocation, this function
> - * *never* fails when called from process contexts. (it might
> - * fail if called from an IRQ context.)
> - * Note: using __GFP_ZERO is not supported.
> + * Note: This function only sleeps if the alloc_fn callback sleeps or returns
> + * %NULL. Using __GFP_ZERO is not supported.

Maybe put the note about __GFP_ZERO being unsupported directly in the
description of @gfp_mask.

> *
> - * Return: pointer to the allocated element or %NULL on error.
> + * Return: pointer to the allocated element or %NULL on error. This function
> + * never returns %NULL when @gfp_mask allows sleeping.

Is "allows sleeping" exactly the same as "__GFP_DIRECT_RECLAIM is set"?
The latter is what the code actually checks for.

> /**
> - * mempool_free - return an element to the pool.
> - * @element: pool element pointer.
> - * @pool: pointer to the memory pool which was allocated via
> - * mempool_create().
> + * mempool_free - return an element to a mempool
> + * @element: pointer to element
> + * @pool: pointer to the memory pool
> + *
> + * Returns @elem to @pool if its needs replenishing, else free it using
> + * the free_fn callback in @pool.
> *
> - * this function only sleeps if the free_fn() function sleeps.
> + * This function only sleeps if the free_fn callback sleeps.
> */
> void mempool_free(void *element, mempool_t *pool)

"if its needs" => "if it needs" and "@elem" => "@element"

- Eric