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.
+ *
+ * @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
--
2.7.4
