[2/4] mempool: clarify comments for mempool cache implementation

Message ID 20230309045738.1261000-3-honnappa.nagarahalli@arm.com (mailing list archive)
State Changes Requested, archived
Delegated to: Thomas Monjalon
Headers
Series Small corrections in mempool |

Checks

Context Check Description
ci/checkpatch warning coding style issues

Commit Message

Honnappa Nagarahalli March 9, 2023, 4:57 a.m. UTC
Clarify that the mempool cache create and free API implementations
work on user owned mempool caches.

Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
Reviewed-by: Kamalakshitha Aligeri <kamalakshitha.aligeri@arm.com>
Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
---
 lib/mempool/rte_mempool.c | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
  

Comments

Morten Brørup June 7, 2023, 10:10 a.m. UTC | #1
> From: Honnappa Nagarahalli [mailto:honnappa.nagarahalli@arm.com]
> Sent: Thursday, 9 March 2023 05.58
> 
> Clarify that the mempool cache create and free API implementations
> work on user owned mempool caches.
> 
> Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
> Reviewed-by: Kamalakshitha Aligeri <kamalakshitha.aligeri@arm.com>
> Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
> ---
>  lib/mempool/rte_mempool.c | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/lib/mempool/rte_mempool.c b/lib/mempool/rte_mempool.c
> index cf5dea2304..a46d855dbf 100644
> --- a/lib/mempool/rte_mempool.c
> +++ b/lib/mempool/rte_mempool.c
> @@ -757,9 +757,9 @@ mempool_cache_init(struct rte_mempool_cache *cache,
> uint32_t size)
>  }
> 
>  /*
> - * Create and initialize a cache for objects that are retrieved from and
> - * returned to an underlying mempool. This structure is identical to the
> - * local_cache[lcore_id] pointed to by the mempool structure.
> + * Create and initialize a user owned cache for objects that are retrieved
> + * from and returned to an underlying mempool. This structure is identical
> + * to the local_cache[lcore_id] pointed to by the mempool structure.
>   */
>  struct rte_mempool_cache *
>  rte_mempool_cache_create(uint32_t size, int socket_id)
> @@ -786,9 +786,9 @@ rte_mempool_cache_create(uint32_t size, int socket_id)
>  }
> 
>  /*
> - * Free a cache. It's the responsibility of the user to make sure that any
> - * remaining objects in the cache are flushed to the corresponding
> - * mempool.
> + * Free a user owned cache. It's the responsibility of the user to make
> + * sure that any remaining objects in the cache are flushed to the
> + * corresponding mempool.
>   */
>  void
>  rte_mempool_cache_free(struct rte_mempool_cache *cache)
> --
> 2.25.1
> 

These comments should probably be updated in the function descriptions in rte_mempool.h too, so they go into the auto-generated documentation.
  
Stephen Hemminger Oct. 4, 2024, 9:08 p.m. UTC | #2
On Wed, 7 Jun 2023 12:10:01 +0200
Morten Brørup <mb@smartsharesystems.com> wrote:

> > From: Honnappa Nagarahalli [mailto:honnappa.nagarahalli@arm.com]
> > Sent: Thursday, 9 March 2023 05.58
> > 
> > Clarify that the mempool cache create and free API implementations
> > work on user owned mempool caches.
> > 
> > Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
> > Reviewed-by: Kamalakshitha Aligeri <kamalakshitha.aligeri@arm.com>
> > Reviewed-by: Ruifeng Wang <ruifeng.wang@arm.com>
> > ---
> >  lib/mempool/rte_mempool.c | 12 ++++++------
> >  1 file changed, 6 insertions(+), 6 deletions(-)
> > 
> > diff --git a/lib/mempool/rte_mempool.c b/lib/mempool/rte_mempool.c
> > index cf5dea2304..a46d855dbf 100644
> > --- a/lib/mempool/rte_mempool.c
> > +++ b/lib/mempool/rte_mempool.c
> > @@ -757,9 +757,9 @@ mempool_cache_init(struct rte_mempool_cache *cache,
> > uint32_t size)
> >  }
> > 
> >  /*
> > - * Create and initialize a cache for objects that are retrieved from and
> > - * returned to an underlying mempool. This structure is identical to the
> > - * local_cache[lcore_id] pointed to by the mempool structure.
> > + * Create and initialize a user owned cache for objects that are retrieved
> > + * from and returned to an underlying mempool. This structure is identical
> > + * to the local_cache[lcore_id] pointed to by the mempool structure.
> >   */
> >  struct rte_mempool_cache *
> >  rte_mempool_cache_create(uint32_t size, int socket_id)
> > @@ -786,9 +786,9 @@ rte_mempool_cache_create(uint32_t size, int socket_id)
> >  }
> > 
> >  /*
> > - * Free a cache. It's the responsibility of the user to make sure that any
> > - * remaining objects in the cache are flushed to the corresponding
> > - * mempool.
> > + * Free a user owned cache. It's the responsibility of the user to make
> > + * sure that any remaining objects in the cache are flushed to the
> > + * corresponding mempool.
> >   */
> >  void
> >  rte_mempool_cache_free(struct rte_mempool_cache *cache)
> > --
> > 2.25.1
> >   
> 
> These comments should probably be updated in the function descriptions in rte_mempool.h too, so they go into the auto-generated documentation.
> 

Agree with Morten on this.
The comments in rte_mempool.h should be updated, and the comments in rte_mempool.c are redundant and can be removed.
Best to have docbook comment as the part which describes the function.
  

Patch

diff --git a/lib/mempool/rte_mempool.c b/lib/mempool/rte_mempool.c
index cf5dea2304..a46d855dbf 100644
--- a/lib/mempool/rte_mempool.c
+++ b/lib/mempool/rte_mempool.c
@@ -757,9 +757,9 @@  mempool_cache_init(struct rte_mempool_cache *cache, uint32_t size)
 }
 
 /*
- * Create and initialize a cache for objects that are retrieved from and
- * returned to an underlying mempool. This structure is identical to the
- * local_cache[lcore_id] pointed to by the mempool structure.
+ * Create and initialize a user owned cache for objects that are retrieved
+ * from and returned to an underlying mempool. This structure is identical
+ * to the local_cache[lcore_id] pointed to by the mempool structure.
  */
 struct rte_mempool_cache *
 rte_mempool_cache_create(uint32_t size, int socket_id)
@@ -786,9 +786,9 @@  rte_mempool_cache_create(uint32_t size, int socket_id)
 }
 
 /*
- * Free a cache. It's the responsibility of the user to make sure that any
- * remaining objects in the cache are flushed to the corresponding
- * mempool.
+ * Free a user owned cache. It's the responsibility of the user to make
+ * sure that any remaining objects in the cache are flushed to the
+ * corresponding mempool.
  */
 void
 rte_mempool_cache_free(struct rte_mempool_cache *cache)