Re: [PATCH] mempolicy: Clarify what RECLAIM_ZONE means

[Joshua Hahn]

On Fri, 25 Jul 2025 14:44:26 -0700 SeongJae Park <sj@xxxxxxxxxx> wrote:

> Hi Joshua,
> 
> On Fri, 25 Jul 2025 10:35:45 -0700 Joshua Hahn <joshua.hahnjy@xxxxxxxxx> wrote:
> 
> > The zone_reclaim_mode API controls reclaim behavior when a node runs out of
> > memory. Contrary to its user-facing name, it is internally referred to as
> > "node_reclaim_mode". This is slightly confusing but there is not much we can
> > do given that it has already been exposed to userspace (since at least 2.6).
> > 
> > However, what we can do is to make sure the internal description of what the
> > bits inside zone_reclaim_mode aligns with what it does in practice.
> > Setting RECLAIM_ZONE does indeed run shrink_inactive_list, but a more holistic
> > description would be to explain that zone reclaim modulates whether page
> > allocation (and khugepaged collapsing) prefers reclaiming & attempting to
> > allocate locally or should fall back to the next node in the zonelist.
> > 
> > Change the description to clarify what zone reclaim entails.
> > 
> > Signed-off-by: Joshua Hahn <joshua.hahnjy@xxxxxxxxx>
> > ---
> >  include/uapi/linux/mempolicy.h | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/include/uapi/linux/mempolicy.h b/include/uapi/linux/mempolicy.h
> > index 1f9bb10d1a47..24083809d920 100644
> > --- a/include/uapi/linux/mempolicy.h
> > +++ b/include/uapi/linux/mempolicy.h
> > @@ -69,7 +69,7 @@ enum {
> >   * These bit locations are exposed in the vm.zone_reclaim_mode sysctl
> >   * ABI.  New bits are OK, but existing bits can never change.
> >   */
> > -#define RECLAIM_ZONE	(1<<0)	/* Run shrink_inactive_list on the zone */
> > +#define RECLAIM_ZONE	(1<<0)	/* Prefer reclaiming & allocating locally */
> >  #define RECLAIM_WRITE	(1<<1)	/* Writeout pages during reclaim */
> >  #define RECLAIM_UNMAP	(1<<2)	/* Unmap pages during reclaim */
> 
> I agree the new comment is more holistic.  It explains general
> zone_reclaim_mode behavior (how the system works if the mode is turned on by
> having any of rightmost three bits is set) well.  But, I think the old
> description is for the specific mode of it (when the rightmost bit is set), and
> the place is appropriate for that purpose.
> 
> What about keeping the old comment but adding the holistic description on the
> upper multi-lines comments block?

Hi SJ,

Thank you for your kind review as always : -)
On second thought, I think you may be right. To be completely honest, the reason
I submitted this patch is because I was looking into zone_reclaim and got
a bit confused, and thought there was a possibility that others might be
confused as well. It might only have been confusing for me, though ;)

> And the behavior is also well described in zone_reclaim_mode section of
> Documentation/admin-guide/sysctl/vm.rst document in my opinion.  Maybe putting
> a reference to the doc together for readers who curious about more details
> could also be useful?

Yes, I think this is a very good point. The comment block above the #defines
were added because in the past, RECLAIM_ZONE was actually removed by a developer
because there were no explicit users (although this has changed since).
Perhaps pointing users to the admin-guide can help explain more about the
context of the first bit, as well as explain what I am trying to do with the
comment change. 

> 
> Thanks,
> SJ
> 
> [...]

Thanks again SJ! I hope you enjoy your weekend : -)
Joshua

Sent using hkml (https://github.com/sjp38/hackermail)