Skip to contentSkip to conversation

mm/damon: explain "effective quota" on kernel-doc comment

RFC PATCH In review SeongJae Park 2 participants 6 messages Nov 26, 2024 – Nov 29, 2024

Subsystems (2)
lore
Share & tools
lore

SeongJae Park

author maintainer
#0 lore raw

RFC PATCH 1/1 mm/damon: explain "effective quota" on kernel-doc comment

The kernel-doc comment for 'struct damos_quota' describes how "effective quota" is calculated, but does not explain what it is. Actually there was an input[1] about it. Add the explanation on the comment.

[1] https://github.com/damonitor/damo/issues/17#issuecomment-2497525043

Cc Yunjeong Mun <[email protected]>
Cc Honggyu Kim <[email protected]>
---
 include/linux/damon.h | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
include/linux/damon.h +7 -3
index a67f2c4940e9..a01bfe2ff616 100644
@@ -193,9 +193,13 @@ struct damos_quota_goal {
  * size quota is set, DAMON tries to apply the action only up to &sz bytes
  * within &reset_interval.
  *
- * Internally, the time quota is transformed to a size quota using estimated
- * throughput of the scheme's action.  DAMON then compares it against &sz and
- * uses smaller one as the effective quota.
+ * To convince the different types of quotas and goals, DAMON internally
+ * converts those into one single size quota called "effective quota".  DAMON
+ * internally uses it as only one real quota.  The convert is made as follows.
+ *
+ * The time quota is transformed to a size quota using estimated throughput of
+ * the scheme's action.  DAMON then compares it against &sz and uses smaller
+ * one as the effective quota.
  *
  * If @goals is not empt, DAMON calculates yet another size quota based on the
  * goals using its internal feedback loop algorithm, for every @reset_interval.
Signature · 1 line
2.39.5
#1 lore raw

Hi SeongJae,

Thanks very much for the quick response. I think it looks great but I have some minor comments so please see my inline comments below.

Thanks,
Honggyu

Quoted 18 lines · On Mon, 25 Nov 2024 16:29:21 -0800 SeongJae Park <[email protected]> wrote:

The kernel-doc comment for 'struct damos_quota' describes how "effective quota" is calculated, but does not explain what it is. Actually there was an input[1] about it. Add the explanation on the comment.

[1] https://github.com/damonitor/damo/issues/17#issuecomment-2497525043

Cc Yunjeong Mun <[email protected]>
Cc Honggyu Kim <[email protected]>
---
 include/linux/damon.h | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
include/linux/damon.h +0 -0
index a67f2c4940e9..a01bfe2ff616 100644

include/linux/damon.h struct damos_quota_goal { · line 197

Quoted 8 lines
include/linux/damon.h +2 -3
@@ -193,9 +193,13 @@ struct damos_quota_goal {
  * size quota is set, DAMON tries to apply the action only up to &sz bytes
  * within &reset_interval.
  *
- * Internally, the time quota is transformed to a size quota using estimated
- * throughput of the scheme's action.  DAMON then compares it against &sz and
- * uses smaller one as the effective quota.
+ * To convince the different types of quotas and goals, DAMON internally
+ * converts those into one single size quota called "effective quota".  DAMON

Could we use "effective size quota" instead of "effective quota"? IMHO, it will better give an idea this is related to "esz" in the code, which means effective size.

include/linux/damon.h struct damos_quota_goal { · line 198

Quoted 1 line
include/linux/damon.h +1 -0
+ * internally uses it as only one real quota.  The convert is made as follows.

(nit) "as only one" can be "as the only one".
(another nit) "The convert is made" can be "The conversion is made".

include/linux/damon.h struct damos_quota_goal { · line 204

Quoted 6 lines
include/linux/damon.h +4 -0
+ *
+ * The time quota is transformed to a size quota using estimated throughput of
+ * the scheme's action.  DAMON then compares it against &sz and uses smaller
+ * one as the effective quota.
  *
  * If @goals is not empt, DAMON calculates yet another size quota based on the

We better fix "empt" to "empty" together.

Quoted 4 lines
include/linux/damon.h +0 -0
  * goals using its internal feedback loop algorithm, for every @reset_interval.
Signature · 1 line
2.39.5
author maintainer
#2 lore raw
Quoted 3 lines · On Tue, 26 Nov 2024 17:24:33 +0900 Honggyu Kim <[email protected]> wrote:

Hi SeongJae,

Thanks very much for the quick response.

No problem, all owing to your kind report!

Quoted 29 lines

I think it looks great but I
have some minor comments so please see my inline comments below.

Thanks,
Honggyu

Quoted 22 lines · On Mon, 25 Nov 2024 16:29:21 -0800 SeongJae Park <[email protected]> wrote:

The kernel-doc comment for 'struct damos_quota' describes how "effective quota" is calculated, but does not explain what it is. Actually there was an input[1] about it. Add the explanation on the comment.

[1] https://github.com/damonitor/damo/issues/17#issuecomment-2497525043

Cc Yunjeong Mun <[email protected]>
Cc Honggyu Kim <[email protected]>
---
 include/linux/damon.h | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
include/linux/damon.h +0 -1
index a67f2c4940e9..a01bfe2ff616 100644
@@ -193,9 +193,13 @@ struct damos_quota_goal {
  * size quota is set, DAMON tries to apply the action only up to &sz bytes
  * within &reset_interval.
  *
- * Internally, the time quota is transformed to a size quota using estimated
Quoted 8 lines

include/linux/damon.h struct damos_quota_goal { · line 197

Quoted 4 lines
include/linux/damon.h +2 -2
- * throughput of the scheme's action.  DAMON then compares it against &sz and
- * uses smaller one as the effective quota.
+ * To convince the different types of quotas and goals, DAMON internally
+ * converts those into one single size quota called "effective quota".  DAMON

Could we use "effective size quota" instead of "effective quota"? IMHO, it will better give an idea this is related to "esz" in the code, which means effective size.

The above sentence is saying it as one single "size" quota, so calling it "effective size quota" here feels like unnecessary duplicates of the word ("size") to me. I'd like to keep this sentence as is if you don't really mind.

Quoted 5 lines

include/linux/damon.h struct damos_quota_goal { · line 198

Quoted 2 lines
include/linux/damon.h +1 -0
+ * internally uses it as only one real quota.  The convert is made as follows.

(nit) "as only one" can be "as the only one".
(another nit) "The convert is made" can be "The conversion is made".

Nice eyes! I will fix those.

Quoted 9 lines

include/linux/damon.h struct damos_quota_goal { · line 204

Quoted 7 lines
include/linux/damon.h +4 -0
+ *
+ * The time quota is transformed to a size quota using estimated throughput of
+ * the scheme's action.  DAMON then compares it against &sz and uses smaller
+ * one as the effective quota.
  *
  * If @goals is not empt, DAMON calculates yet another size quota based on the

We better fix "empt" to "empty" together.

Nice catch! I will fix so.

Quoted 5 lines
Quoted 5 lines
include/linux/damon.h +0 -0
  * goals using its internal feedback loop algorithm, for every @reset_interval.
Signature · 1 line
2.39.5

Thanks,
SJ

#3 lore raw
Quoted 46 lines · On Tue, 26 Nov 2024 11:43:47 -0800 SeongJae Park <[email protected]> wrote:
Quoted 3 lines · On Tue, 26 Nov 2024 17:24:33 +0900 Honggyu Kim <[email protected]> wrote:

Hi SeongJae,

Thanks very much for the quick response.

No problem, all owing to your kind report!

Quoted 29 lines

I think it looks great but I
have some minor comments so please see my inline comments below.

Thanks,
Honggyu

Quoted 22 lines · On Mon, 25 Nov 2024 16:29:21 -0800 SeongJae Park <[email protected]> wrote:

The kernel-doc comment for 'struct damos_quota' describes how "effective quota" is calculated, but does not explain what it is. Actually there was an input[1] about it. Add the explanation on the comment.

[1] https://github.com/damonitor/damo/issues/17#issuecomment-2497525043

Cc Yunjeong Mun <[email protected]>
Cc Honggyu Kim <[email protected]>
---
 include/linux/damon.h | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
include/linux/damon.h +0 -1
index a67f2c4940e9..a01bfe2ff616 100644
@@ -193,9 +193,13 @@ struct damos_quota_goal {
  * size quota is set, DAMON tries to apply the action only up to &sz bytes
  * within &reset_interval.
  *
- * Internally, the time quota is transformed to a size quota using estimated
Quoted 8 lines

include/linux/damon.h struct damos_quota_goal { · line 197

Quoted 4 lines
include/linux/damon.h +2 -2
- * throughput of the scheme's action.  DAMON then compares it against &sz and
- * uses smaller one as the effective quota.
+ * To convince the different types of quotas and goals, DAMON internally
+ * converts those into one single size quota called "effective quota".  DAMON

Could we use "effective size quota" instead of "effective quota"? IMHO, it will better give an idea this is related to "esz" in the code, which means effective size.

Quoted 3 lines

The above sentence is saying it as one single "size" quota, so calling it "effective size quota" here feels like unnecessary duplicates of the word ("size") to me. I'd like to keep this sentence as is if you don't really mind.

Since the time or other goals are eventually transformed into a size quota, I thought the "effective size quota" makes sense but I won't stick to my term here.

We originally asked this question about the term "effective" itself as we didn't find an explanation what "effective" means actually in the doc. It'd be better to have more explicit explanation as well.

Quoted 7 lines
Quoted 5 lines

include/linux/damon.h struct damos_quota_goal { · line 198

Quoted 2 lines
include/linux/damon.h +1 -0
+ * internally uses it as only one real quota.  The convert is made as follows.

(nit) "as only one" can be "as the only one".
(another nit) "The convert is made" can be "The conversion is made".

Nice eyes! I will fix those.

Thanks, please do!

Quoted 11 lines
Quoted 9 lines

include/linux/damon.h struct damos_quota_goal { · line 204

Quoted 7 lines
include/linux/damon.h +4 -0
+ *
+ * The time quota is transformed to a size quota using estimated throughput of
+ * the scheme's action.  DAMON then compares it against &sz and uses smaller
+ * one as the effective quota.
  *
  * If @goals is not empt, DAMON calculates yet another size quota based on the

We better fix "empt" to "empty" together.

Nice catch! I will fix so.

Ditto.

Thanks,
Honggyu

Quoted 9 lines
Quoted 5 lines
Quoted 5 lines
include/linux/damon.h +0 -0
  * goals using its internal feedback loop algorithm, for every @reset_interval.
Signature · 1 line
2.39.5

Thanks,
SJ

author maintainer
#4 lore raw
Quoted 47 lines · On Thu, 28 Nov 2024 18:53:55 +0900 Honggyu Kim <[email protected]> wrote:
Quoted 46 lines · On Tue, 26 Nov 2024 11:43:47 -0800 SeongJae Park <[email protected]> wrote:
Quoted 3 lines · On Tue, 26 Nov 2024 17:24:33 +0900 Honggyu Kim <[email protected]> wrote:

Hi SeongJae,

Thanks very much for the quick response.

No problem, all owing to your kind report!

Quoted 37 lines

I think it looks great but I
have some minor comments so please see my inline comments below.

Thanks,
Honggyu

Quoted 18 lines · On Mon, 25 Nov 2024 16:29:21 -0800 SeongJae Park <[email protected]> wrote:

The kernel-doc comment for 'struct damos_quota' describes how "effective quota" is calculated, but does not explain what it is. Actually there was an input[1] about it. Add the explanation on the comment.

[1] https://github.com/damonitor/damo/issues/17#issuecomment-2497525043

Cc Yunjeong Mun <[email protected]>
Cc Honggyu Kim <[email protected]>
---
 include/linux/damon.h | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
include/linux/damon.h +0 -0
index a67f2c4940e9..a01bfe2ff616 100644

include/linux/damon.h struct damos_quota_goal { · line 197

Quoted 8 lines
include/linux/damon.h +2 -3
@@ -193,9 +193,13 @@ struct damos_quota_goal {
  * size quota is set, DAMON tries to apply the action only up to &sz bytes
  * within &reset_interval.
  *
- * Internally, the time quota is transformed to a size quota using estimated
- * throughput of the scheme's action.  DAMON then compares it against &sz and
- * uses smaller one as the effective quota.
+ * To convince the different types of quotas and goals, DAMON internally
+ * converts those into one single size quota called "effective quota".  DAMON

Could we use "effective size quota" instead of "effective quota"? IMHO, it will better give an idea this is related to "esz" in the code, which means effective size.

Quoted 7 lines
Quoted 3 lines

The above sentence is saying it as one single "size" quota, so calling it "effective size quota" here feels like unnecessary duplicates of the word ("size") to me. I'd like to keep this sentence as is if you don't really mind.

Since the time or other goals are eventually transformed into a size quota, I thought the "effective size quota" makes sense but I won't stick to my term here.

I understand your concern. But I want to make it not very strictly fixed and well-defined term, but just somewhat understandable with common sense and given context, for flexibility and conciseness. So unless this is really makes it difficult to understand what it means even with common senses and the context I'd like to keep current form.

I believe your answer to the above question is "no" since you mentioned you won't stick to your term. Please let me know if I'm misreading you.

Quoted 4 lines

We originally asked this question about the term "effective" itself as we didn't find an explanation what "effective" means actually in the doc. It'd be better to have more explicit explanation as well.

I think this patch makes the point pretty explicit, so my humble brain is bit confused what "more explicit" really means. Could you please clarify what changes you want to be added?

Thanks,
SJ

[...]

#5 lore raw
Quoted 57 lines · On Thu, 28 Nov 2024 09:50:46 -0800 SeongJae Park <[email protected]> wrote:
Quoted 47 lines · On Thu, 28 Nov 2024 18:53:55 +0900 Honggyu Kim <[email protected]> wrote:
Quoted 46 lines · On Tue, 26 Nov 2024 11:43:47 -0800 SeongJae Park <[email protected]> wrote:
Quoted 3 lines · On Tue, 26 Nov 2024 17:24:33 +0900 Honggyu Kim <[email protected]> wrote:

Hi SeongJae,

Thanks very much for the quick response.

No problem, all owing to your kind report!

Quoted 37 lines

I think it looks great but I
have some minor comments so please see my inline comments below.

Thanks,
Honggyu

Quoted 18 lines · On Mon, 25 Nov 2024 16:29:21 -0800 SeongJae Park <[email protected]> wrote:

The kernel-doc comment for 'struct damos_quota' describes how "effective quota" is calculated, but does not explain what it is. Actually there was an input[1] about it. Add the explanation on the comment.

[1] https://github.com/damonitor/damo/issues/17#issuecomment-2497525043

Cc Yunjeong Mun <[email protected]>
Cc Honggyu Kim <[email protected]>
---
 include/linux/damon.h | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
include/linux/damon.h +0 -0
index a67f2c4940e9..a01bfe2ff616 100644

include/linux/damon.h struct damos_quota_goal { · line 197

Quoted 8 lines
include/linux/damon.h +2 -3
@@ -193,9 +193,13 @@ struct damos_quota_goal {
  * size quota is set, DAMON tries to apply the action only up to &sz bytes
  * within &reset_interval.
  *
- * Internally, the time quota is transformed to a size quota using estimated
- * throughput of the scheme's action.  DAMON then compares it against &sz and
- * uses smaller one as the effective quota.
+ * To convince the different types of quotas and goals, DAMON internally
+ * converts those into one single size quota called "effective quota".  DAMON

Could we use "effective size quota" instead of "effective quota"? IMHO, it will better give an idea this is related to "esz" in the code, which means effective size.

Quoted 7 lines
Quoted 3 lines

The above sentence is saying it as one single "size" quota, so calling it "effective size quota" here feels like unnecessary duplicates of the word ("size") to me. I'd like to keep this sentence as is if you don't really mind.

Since the time or other goals are eventually transformed into a size quota, I thought the "effective size quota" makes sense but I won't stick to my term here.

Quoted 8 lines

I understand your concern. But I want to make it not very strictly fixed and well-defined term, but just somewhat understandable with common sense and given context, for flexibility and conciseness. So unless this is really makes it difficult to understand what it means even with common senses and the context I'd like to keep current form.

I believe your answer to the above question is "no" since you mentioned you won't stick to your term. Please let me know if I'm misreading you.

OK. I'm fine with the changes with this patch. I won't ask more changes.

Quoted 8 lines
Quoted 4 lines

We originally asked this question about the term "effective" itself as we didn't find an explanation what "effective" means actually in the doc. It'd be better to have more explicit explanation as well.

I think this patch makes the point pretty explicit, so my humble brain is bit confused what "more explicit" really means. Could you please clarify what changes you want to be added?

Nevermind, your changes here with some grammar and typo fixes are enough for this patch.

Thanks,
Honggyu

Quoted 5 lines

Thanks,
SJ

[...]