__GFP_NOFAIL is documented both in gfp.h and memory-allocation.rst.
The details are not entirely consistent.
This patch ensures both places state that:
- there is a cost potentially imposed on other subsystems
- it should only be used when there is no real alternative
- it is preferable to an endless loop
- it is strongly discourages for costly-order allocations.
Signed-off-by: NeilBrown <[email protected]>
---
Documentation/core-api/memory-allocation.rst | 9 ++++++++-
include/linux/gfp.h | 4 ++++
2 files changed, 12 insertions(+), 1 deletion(-)
diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
index 5954ddf6ee13..9458ce72d31c 100644
--- a/Documentation/core-api/memory-allocation.rst
+++ b/Documentation/core-api/memory-allocation.rst
@@ -126,7 +126,14 @@ or another request.
* ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior
and all allocation requests will loop endlessly until they succeed.
- This might be really dangerous especially for larger orders.
+ The allocator may provide access to memory that would otherwise be
+ reserved in order to satisfy this allocation which might adversely
+ affect other subsystems. So it should only be used when there is no
+ reasonable failure policy and when the memory is likely to be freed
+ again in the near future. Its use is strong discourage (via a
+ WARN_ON) for allocations larger than ``PAGE_ALLOC_COSTLY_ORDER``.
+ While this flag is best avoided, it is still preferable to endless
+ loops around the allocator.
Selecting memory allocator
==========================
diff --git a/include/linux/gfp.h b/include/linux/gfp.h
index 55b2ec1f965a..101479373738 100644
--- a/include/linux/gfp.h
+++ b/include/linux/gfp.h
@@ -209,6 +209,10 @@ struct vm_area_struct;
* used only when there is no reasonable failure policy) but it is
* definitely preferable to use the flag rather than opencode endless
* loop around allocator.
+ * Use of this flag may provide access to memory which would otherwise be
+ * reserved. As such it must be understood that there can be a cost imposed
+ * on other subsystems as well as the obvious cost of placing the calling
+ * thread in an uninterruptible indefinite wait.
* Using this flag for costly allocations is _highly_ discouraged.
*/
#define __GFP_IO ((__force gfp_t)___GFP_IO)
On Tue 14-09-21 10:13:04, Neil Brown wrote:
> __GFP_NOFAIL is documented both in gfp.h and memory-allocation.rst.
> The details are not entirely consistent.
>
> This patch ensures both places state that:
> - there is a cost potentially imposed on other subsystems
> - it should only be used when there is no real alternative
> - it is preferable to an endless loop
> - it is strongly discourages for costly-order allocations.
>
Yes this is a useful addition to the documentation. Thanks!
> Signed-off-by: NeilBrown <[email protected]>
Acked-by: Michal Hocko <[email protected]>
> ---
> Documentation/core-api/memory-allocation.rst | 9 ++++++++-
> include/linux/gfp.h | 4 ++++
> 2 files changed, 12 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst
> index 5954ddf6ee13..9458ce72d31c 100644
> --- a/Documentation/core-api/memory-allocation.rst
> +++ b/Documentation/core-api/memory-allocation.rst
> @@ -126,7 +126,14 @@ or another request.
>
> * ``GFP_KERNEL | __GFP_NOFAIL`` - overrides the default allocator behavior
> and all allocation requests will loop endlessly until they succeed.
> - This might be really dangerous especially for larger orders.
> + The allocator may provide access to memory that would otherwise be
> + reserved in order to satisfy this allocation which might adversely
> + affect other subsystems. So it should only be used when there is no
> + reasonable failure policy and when the memory is likely to be freed
> + again in the near future. Its use is strong discourage (via a
> + WARN_ON) for allocations larger than ``PAGE_ALLOC_COSTLY_ORDER``.
> + While this flag is best avoided, it is still preferable to endless
> + loops around the allocator.
>
> Selecting memory allocator
> ==========================
> diff --git a/include/linux/gfp.h b/include/linux/gfp.h
> index 55b2ec1f965a..101479373738 100644
> --- a/include/linux/gfp.h
> +++ b/include/linux/gfp.h
> @@ -209,6 +209,10 @@ struct vm_area_struct;
> * used only when there is no reasonable failure policy) but it is
> * definitely preferable to use the flag rather than opencode endless
> * loop around allocator.
> + * Use of this flag may provide access to memory which would otherwise be
> + * reserved. As such it must be understood that there can be a cost imposed
> + * on other subsystems as well as the obvious cost of placing the calling
> + * thread in an uninterruptible indefinite wait.
> * Using this flag for costly allocations is _highly_ discouraged.
> */
> #define __GFP_IO ((__force gfp_t)___GFP_IO)
>
--
Michal Hocko
SUSE Labs