diff --git a/mtapi_cpp/include/embb/mtapi/action.h b/mtapi_cpp/include/embb/mtapi/action.h index 28ef3c7..fad2235 100644 --- 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 */ diff --git a/mtapi_cpp/include/embb/mtapi/group.h b/mtapi_cpp/include/embb/mtapi/group.h index 8810d5f..ea61ec2 100644 --- 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_job_hndl_t job, - const void * arguments, - mtapi_size_t arguments_size, - void * results, - mtapi_size_t results_size, + mtapi_task_id_t task_id, /**< A user defined ID of the Task. */ + mtapi_job_hndl_t job, /**< The Job to execute. */ + const void * arguments, /**< Pointer to the arguments. */ + mtapi_size_t arguments_size, /**< Size of the argument buffer. */ + void * results, /**< Pointer to the results. */ + 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 = diff --git a/mtapi_cpp/include/embb/mtapi/node.h b/mtapi_cpp/include/embb/mtapi/node.h index 75ead82..8b61d1d 100644 --- 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 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. */ diff --git a/mtapi_cpp/include/embb/mtapi/queue.h b/mtapi_cpp/include/embb/mtapi/queue.h index 5f372b2..4ccdff9 100644 --- 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); diff --git a/mtapi_cpp/include/embb/mtapi/task_attributes.h b/mtapi_cpp/include/embb/mtapi/task_attributes.h index 2e7a305..228d3f5 100644 --- 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());