| Message ID | 1476434952-8282-2-git-send-email-matias.elo@nokia.com |
|---|---|
| State | Accepted |
| Commit | ad7f8f4ea11a8e40d853cd9b2b0bc3e6f7876a8b |
| Headers | show |
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.elo@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. 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
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. + * + * @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
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.elo@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(-) -- 2.7.4