Merge branch 'embb609_doxygen_warnings' into development

0fb4c99e · Marcus Winter · bc991d06 · 746e2f18 · 0fb4c99e · 0fb4c99e
Commit 0fb4c99e authored Nov 02, 2016 by Marcus Winter
5 changed files
--- a/mtapi_cpp/include/embb/mtapi/action.h
+++ b/mtapi_cpp/include/embb/mtapi/action.h
@@ -44,23 +44,42 @@ class Action {
  /**
   * Constructs an Action.
   * The Action object will be invalid.
+   *
+   * \waitfree
   */
  Action() {
    handle_.id = 0;
    handle_.tag = 0;
  }
-  Action(Action const & other) : handle_(other.handle_) {
+  /**
+   * Copies an Action.
+   *
+   * \waitfree
+   */
+  Action(
+    Action const & other               /**< Action to copy */
+    ) : handle_(other.handle_) {
    // empty
  }
-  Action & operator=(Action const & other) {
+  /**
+   * Copies an Action.
+   *
+   * \returns Reference to this object.
+   * \waitfree
+   */
+  Action & operator=(
+    Action const & other               /**< Action to copy */
+    ) {
    handle_ = other.handle_;
    return *this;
  }
  /**
   * Deletes an Action.
+   *
+   * \threadsafe
   */
  void Delete() {
    mtapi_action_delete(handle_, MTAPI_INFINITE, MTAPI_NULL);
@@ -82,6 +101,8 @@ class Action {
 private:
  /**
   * Constructs an Action.
+   *
+   * \threadsafe
   */
  Action(
    mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */

--- a/mtapi_cpp/include/embb/mtapi/group.h
+++ b/mtapi_cpp/include/embb/mtapi/group.h
@@ -51,17 +51,34 @@ namespace mtapi {
 */
 class Group {
 public:
-  Group(Group const & other) : handle_(other.handle_) {
+  /**
+   * Copies a Group.
+   *
+   * \waitfree
+   */
+  Group(
+    Group const & other                /**< Group to copy */
+    ) : handle_(other.handle_) {
    // empty
  }
-  Group & operator=(Group const & other) {
+  /**
+   * Copies a Group.
+   *
+   * \returns Reference to this object.
+   * \waitfree
+   */
+  Group & operator=(
+    Group const & other                /**< Group to copy */
+    ) {
    handle_ = other.handle_;
    return *this;
  }
  /**
   * Deletes a Group object.
+   *
+   * \threadsafe
   */
  void Delete() {
    // delete the group, ignore status
@@ -245,6 +262,8 @@ class Group {
  /**
   * Constructs a Group object with given attributes and ID.
   * Requires an initialized Node.
+   *
+   * \threadsafe
   */
  Group(
    mtapi_group_id_t id,               /**< A user defined ID of the Group. */
@@ -256,14 +275,21 @@ class Group {
    internal::CheckStatus(status);
  }
+  /**
+   * Starts a new Task in this Group.
+   *
+   * \returns The handle to the started Task.
+   * \threadsafe
+   */
  Task Start(
-    mtapi_task_id_t task_id,
+    mtapi_task_id_t task_id,           /**< A user defined ID of the Task. */
-    mtapi_job_hndl_t job,
+    mtapi_job_hndl_t job,              /**< The Job to execute. */
-    const void * arguments,
+    const void * arguments,            /**< Pointer to the arguments. */
-    mtapi_size_t arguments_size,
+    mtapi_size_t arguments_size,       /**< Size of the argument buffer. */
-    void * results,
+    void * results,                    /**< Pointer to the results. */
-    mtapi_size_t results_size,
+    mtapi_size_t results_size,         /**< Size of the result buffer. */
    mtapi_task_attributes_t const * attributes
+                                       /**< Attributes of the Task */
    ) {
    mtapi_status_t status;
    mtapi_task_hndl_t task_hndl =

--- a/mtapi_cpp/include/embb/mtapi/node.h
+++ b/mtapi_cpp/include/embb/mtapi/node.h
@@ -68,6 +68,9 @@ namespace mtapi {
 */
 class Node {
 public:
+  /**
+   * Function type for simple SMP interface.
+   */
  typedef embb::base::Function<void, TaskContext &> SMPFunction;
  /**
@@ -285,16 +288,37 @@ class Node {
      MTAPI_DEFAULT_TASK_ATTRIBUTES);
  }
-  Job GetJob(mtapi_job_id_t job_id) {
+  /**
+   * Retrieves a handle to the Job identified by \c job_id within the domain
+   * of the local Node.
+   *
+   * \returns The handle to the requested Job.
+   * \waitfree
+   */
+  Job GetJob(
+    mtapi_job_id_t job_id              /**< [in] The id of the job */
+    ) {
    return Job(job_id, domain_id_);
  }
-  Job GetJob(mtapi_job_id_t job_id, mtapi_domain_t domain_id) {
+  /**
+   * Retrieves a handle to the Job identified by \c job_id and \c domain_id.
+   *
+   * \returns The handle to the requested Job.
+   * \waitfree
+   */
+  Job GetJob(
+    mtapi_job_id_t job_id,             /**< [in] The id of the job */
+    mtapi_domain_t domain_id           /**< [in] The domain id to use */
+    ) {
    return Job(job_id, domain_id);
  }
  /**
   * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \lockfree
   */
  Action CreateAction(
    mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
@@ -303,7 +327,7 @@ class Node {
                                       Tasks using this Action */
    mtapi_size_t node_local_data_size, /**< Size of node local data */
    ActionAttributes const & attributes
-    /**< Attributes of the Action */
+                                       /**< Attributes of the Action */
    ) {
    return Action(job_id, func, node_local_data, node_local_data_size,
      &attributes.GetInternal());
@@ -311,6 +335,9 @@ class Node {
  /**
   * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \lockfree
   */
  Action CreateAction(
    mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
@@ -325,18 +352,24 @@ class Node {
  /**
   * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \lockfree
   */
  Action CreateAction(
    mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
    mtapi_action_function_t func,      /**< The action function */
    ActionAttributes const & attributes
-    /**< Attributes of the Action */
+                                       /**< Attributes of the Action */
    ) {
    return Action(job_id, func, MTAPI_NULL, 0, &attributes.GetInternal());
  }
  /**
   * Constructs an Action.
+   *
+   * \returns The handle to the new Action.
+   * \lockfree
   */
  Action CreateAction(
    mtapi_job_id_t job_id,             /**< Job ID the Action belongs to */
@@ -347,6 +380,9 @@ class Node {
  /**
   * Constructs a Group object with default attributes.
+   *
+   * \returns The handle to the new Group.
+   * \lockfree
   */
  Group CreateGroup() {
    return Group(MTAPI_GROUP_ID_NONE, MTAPI_DEFAULT_GROUP_ATTRIBUTES);
@@ -354,6 +390,9 @@ class Node {
  /**
   * Constructs a Group object with default attributes and the given ID.
+   *
+   * \returns The handle to the new Group.
+   * \lockfree
   */
  Group CreateGroup(
    mtapi_group_id_t id                /**< A user defined ID of the Group. */
@@ -363,14 +402,21 @@ class Node {
  /**
   * Constructs a Group object using the given Attributes.
+   *
+   * \returns The handle to the new Group.
+   * \lockfree
   */
  Group CreateGroup(
-    GroupAttributes const & group_attr) {
+    GroupAttributes const & group_attr /**< The GroupAttributes to use. */
+    ) {
    return Group(MTAPI_GROUP_ID_NONE, &group_attr.GetInternal());
  }
  /**
   * Constructs a Group object with given attributes and ID.
+   *
+   * \returns The handle to the new Group.
+   * \lockfree
   */
  Group CreateGroup(
    mtapi_group_id_t id,               /**< A user defined ID of the Group. */
@@ -381,6 +427,9 @@ class Node {
  /**
   * Constructs a Queue with the given Job and default attributes.
+   *
+   * \returns The handle to the new Queue.
+   * \lockfree
   */
  Queue CreateQueue(
    Job & job                          /**< The Job to use for the Queue. */
@@ -390,6 +439,9 @@ class Node {
  /**
   * Constructs a Queue with the given Job and QueueAttributes.
+   *
+   * \returns The handle to the new Queue.
+   * \lockfree
   */
  Queue CreateQueue(
    Job const & job,                   /**< The Job to use for the Queue. */

--- a/mtapi_cpp/include/embb/mtapi/queue.h
+++ b/mtapi_cpp/include/embb/mtapi/queue.h
@@ -51,17 +51,34 @@ namespace mtapi {
 */
 class Queue {
 public:
-  Queue(Queue const & other) : handle_(other.handle_) {
+  /**
+   * Copies a Queue.
+   *
+   * \waitfree
+   */
+  Queue(
+    Queue const & other                /**< The Queue to copy */
+    ) : handle_(other.handle_) {
    // empty
  }
-  Queue & operator=(Queue const & other) {
+  /**
+   * Copies a Queue.
+   *
+   * \returns Reference to this object.
+   * \waitfree
+   */
+  Queue & operator=(
+    Queue const & other                /**< The Queue to copy */
+    ) {
    handle_ = other.handle_;
    return *this;
  }
  /**
   * Deletes a Queue object.
+   *
+   * \threadsafe
   */
  void Delete() {
    mtapi_queue_delete(handle_, MTAPI_INFINITE, MTAPI_NULL);

--- a/mtapi_cpp/include/embb/mtapi/task_attributes.h
+++ b/mtapi_cpp/include/embb/mtapi/task_attributes.h
@@ -103,8 +103,15 @@ class TaskAttributes {
    return *this;
  }
+  /**
+   * Sets the ExecutionPolicy of a Task.
+   * The ExecutionPolicy determines the affinity and priority of a Task.
+   *
+   * \returns Reference to this object.
+   * \notthreadsafe
+   */
  TaskAttributes & SetPolicy(
-    ExecutionPolicy const & policy
+    ExecutionPolicy const & policy     /**< The ExecutionPolicy to set. */
    ) {
    SetPriority(policy.GetPriority());
    SetAffinity(policy.GetAffinity());