> -----Original Message-----
> From: lng-odp [mailto:lng-odp-boun...@lists.linaro.org] On Behalf Of Maxim
> Uvarov
> Sent: Friday, October 14, 2016 12:53 PM
> To: lng-odp@lists.linaro.org
> Subject: Re: [lng-odp] [API-NEXT PATCH 1/5] api: improve name argument
> definitions in *_create() functions
> 
> On 10/14/16 11:49, Matias Elo wrote:
> > The current APIs don't always define valid name argument values. Fix this
> > by stating when NULL is a valid value and when the name string doesn't have
> > to be unique.
> >
> > Signed-off-by: Matias Elo <matias....@nokia.com>
> > ---
> >   include/odp/api/spec/classification.h | 10 ++++++----
> >   include/odp/api/spec/pool.h           | 17 ++++++-----------
> >   include/odp/api/spec/queue.h          |  9 ++++++---
> >   include/odp/api/spec/schedule.h       | 12 ++++++------
> >   include/odp/api/spec/timer.h          |  5 ++++-
> >   5 files changed, 28 insertions(+), 25 deletions(-)
> >
> > diff --git a/include/odp/api/spec/classification.h
> b/include/odp/api/spec/classification.h
> > index 189c91f..0e442c7 100644
> > --- a/include/odp/api/spec/classification.h
> > +++ b/include/odp/api/spec/classification.h
> > @@ -193,12 +193,14 @@ int odp_cls_capability(odp_cls_capability_t
> *capability);
> >   /**
> >    * Create a class-of-service
> >    *
> > - * @param  name    String intended for debugging purposes.
> > + * The use of class-of-service name is optional. Unique names are not
> required.
> >    *
> > - * @param  param   class of service parameters
> > + * @param       name    Name of the class-of-service or NULL. Maximum 
> > string
> > + *                      length is ODP_COS_NAME_LEN.
> > + * @param       param   Class-of-service parameters
> >    *
> > - * @retval         class of service handle
> > - * @retval         ODP_COS_INVALID on failure.
> > + * @retval              Class-of-service handle
> > + * @retval              ODP_COS_INVALID on failure.
> >    *
> >    * @note ODP_QUEUE_INVALID and ODP_POOL_INVALID are valid values for
> queue
> >    * and pool associated with a class of service and when any one of these 
> > values
> > diff --git a/include/odp/api/spec/pool.h b/include/odp/api/spec/pool.h
> > index c80c98a..a1331e3 100644
> > --- a/include/odp/api/spec/pool.h
> > +++ b/include/odp/api/spec/pool.h
> > @@ -220,14 +220,12 @@ typedef struct odp_pool_param_t {
> >   /**
> >    * Create a pool
> >    *
> > - * This routine is used to create a pool. It take two arguments: the 
> > optional
> > - * name of the pool to be created and a parameter struct that describes the
> > - * pool to be created. If a name is not specified the result is an 
> > anonymous
> > - * pool that cannot be referenced by odp_pool_lookup().
> > - *
> > - * @param name     Name of the pool, max ODP_POOL_NAME_LEN-1 chars.
> > - *                 May be specified as NULL for anonymous pools.
> > + * This routine is used to create a pool. The use of pool name is optional.
> > + * Unique names are not required. However, odp_pool_lookup() returns only
> a
> > + * single matching pool.
> >    *
> > + * @param name     Name of the pool or NULL. Maximum string length is
> > + *                 ODP_POOL_NAME_LEN.
> >    * @param params   Pool parameters.
> >    *
> >    * @return Handle of the created pool
> > @@ -256,11 +254,8 @@ int odp_pool_destroy(odp_pool_t pool);
> >    *
> >    * @param name      Name of the pool
> >    *
> > - * @return Handle of found pool
> > + * @return Handle of the first matching pool
> >    * @retval ODP_POOL_INVALID  Pool could not be found
> > - *
> > - * @note This routine cannot be used to look up an anonymous pool (one
> created
> > - * with no name).
> >    */
> >   odp_pool_t odp_pool_lookup(const char *name);
> >
> > diff --git a/include/odp/api/spec/queue.h b/include/odp/api/spec/queue.h
> > index 31dc9f5..b0c5e31 100644
> > --- a/include/odp/api/spec/queue.h
> > +++ b/include/odp/api/spec/queue.h
> > @@ -173,9 +173,12 @@ typedef struct odp_queue_param_t {
> >    * Create a queue according to the queue parameters. Queue type is 
> > specified
> by
> >    * queue parameter 'type'. Use odp_queue_param_init() to initialize
> parameters
> >    * into their default values. Default values are also used when 'param' 
> > pointer
> > - * is NULL. The default queue type is ODP_QUEUE_TYPE_PLAIN.
> > + * is NULL. The default queue type is ODP_QUEUE_TYPE_PLAIN. The use of
> queue
> > + * name is optional. Unique names are not required. However,
> odp_queue_lookup()
> > + * returns only a single matching queue.
> >    *
> > - * @param name    Queue name
> > + * @param name    Name of the queue or NULL. Maximum string length is
> > + *                ODP_QUEUE_NAME_LEN.
> >    * @param param   Queue parameters. Uses defaults if NULL.
> >    *
> >    * @return Queue handle
> > @@ -203,7 +206,7 @@ int odp_queue_destroy(odp_queue_t queue);
> >    *
> >    * @param name    Queue name
> >    *
> > - * @return Queue handle
> > + * @return Handle of the first matching queue
> >    * @retval ODP_QUEUE_INVALID on failure
> >    */
> >   odp_queue_t odp_queue_lookup(const char *name);
> > diff --git a/include/odp/api/spec/schedule.h
> b/include/odp/api/spec/schedule.h
> > index d924da2..f976a4c 100644
> > --- a/include/odp/api/spec/schedule.h
> > +++ b/include/odp/api/spec/schedule.h
> > @@ -214,10 +214,12 @@ int odp_schedule_num_prio(void);
> >    * mask will receive events from a queue that belongs to the schedule 
> > group.
> >    * Thread masks of various schedule groups may overlap. There are
> predefined
> >    * groups such as ODP_SCHED_GROUP_ALL and
> ODP_SCHED_GROUP_WORKER, which are
> > - * always present and automatically updated. Group name is optional
> > - * (may be NULL) and can have ODP_SCHED_GROUP_NAME_LEN characters in
> maximum.
> > + * always present and automatically updated. The use of group name is
> optional.
> > + * Unique names are not required. However, odp_schedule_group_lookup()
> returns
> > + * only a single matching group.
> >    *
> > - * @param name    Schedule group name
> > + * @param name    Name of the schedule group or NULL. Maximum string
> length is
> > + *                ODP_SCHED_GROUP_NAME_LEN.
> >    * @param mask    Thread mask
> >    *
> >    * @return Schedule group handle
> > @@ -245,11 +247,9 @@ int
> odp_schedule_group_destroy(odp_schedule_group_t group);
> >   /**
> >    * Look up a schedule group by name
> >    *
> > - * Return the handle of a schedule group from its name
> > - *
> >    * @param name   Name of schedule group
> >    *
> > - * @return Handle of schedule group for specified name
> > + * @return Handle of the first matching schedule group
> >    * @retval ODP_SCHEDULE_GROUP_INVALID No matching schedule group
> found
> >    */
> >   odp_schedule_group_t odp_schedule_group_lookup(const char *name);
> > diff --git a/include/odp/api/spec/timer.h b/include/odp/api/spec/timer.h
> > index df37189..49221c4 100644
> > --- a/include/odp/api/spec/timer.h
> > +++ b/include/odp/api/spec/timer.h
> > @@ -108,7 +108,10 @@ typedef struct {
> >   /**
> >    * Create a timer pool
> >    *
> > - * @param name       Name of the timer pool. The string will be copied.
> > + * The use of pool name is optional. Unique names are not required.
> 
> Unique name should be required to do lookup. Or lookup will not work at all.

The *_lookup() function definitions are also modified. 
E.g.
 - * @return Handle of found pool
 + * @return Handle of the first matching pool

It is the responsibility of the application to use unique names if it wants to
lookup a particular object.

-Matias

> 
> Maxim.
> 
> > + *
> > + * @param name       Name of the timer pool or NULL. Maximum string length
> is
> > + *                   ODP_TIMER_POOL_NAME_LEN.
> >    * @param params     Timer pool parameters. The content will be copied.
> >    *
> >    * @return Timer pool handle on success

Reply via email to