Embedded Multicore Building Blocks V1.0.0
group.h
1 /*
2  * Copyright (c) 2014-2017, Siemens AG. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *
7  * 1. Redistributions of source code must retain the above copyright notice,
8  * this list of conditions and the following disclaimer.
9  *
10  * 2. Redistributions in binary form must reproduce the above copyright notice,
11  * this list of conditions and the following disclaimer in the documentation
12  * and/or other materials provided with the distribution.
13  *
14  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
15  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
18  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
19  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
20  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
21  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
22  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
23  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
24  * POSSIBILITY OF SUCH DAMAGE.
25  */
26 
27 #ifndef EMBB_MTAPI_GROUP_H_
28 #define EMBB_MTAPI_GROUP_H_
29 
30 #include <embb/mtapi/c/mtapi.h>
31 #include <embb/mtapi/job.h>
32 #include <embb/mtapi/task.h>
33 #include <embb/mtapi/task_attributes.h>
34 #include <embb/mtapi/group_attributes.h>
35 
36 namespace embb {
37 
38 namespace base {
39 
40 class Allocation;
41 
42 } // namespace base
43 
44 namespace mtapi {
45 
52 class Group {
53  public:
58  Group() {
59  handle_.id = 0;
60  handle_.tag = 0;
61  }
62 
68  Group const & other
69  ) : handle_(other.handle_) {
70  // empty
71  }
72 
79  Group const & other
80  ) {
81  handle_ = other.handle_;
82  return *this;
83  }
84 
89  void Delete() {
90  // delete the group, ignore status
91  mtapi_group_delete(handle_, MTAPI_NULL);
92  }
93 
100  template <typename ARGS, typename RES>
102  mtapi_task_id_t task_id,
103  Job const & job,
104  const ARGS * arguments,
105  RES * results,
106  TaskAttributes const & attributes
107  ) {
108  return Start(task_id,
109  job.GetInternal(),
110  arguments, internal::SizeOfType<ARGS>(),
111  results, internal::SizeOfType<RES>(),
112  &attributes.GetInternal());
113  }
114 
121  template <typename ARGS, typename RES>
123  mtapi_task_id_t task_id,
124  Job const & job,
125  const ARGS * arguments,
126  RES * results
127  ) {
128  return Start(task_id,
129  job.GetInternal(),
130  arguments, internal::SizeOfType<ARGS>(),
131  results, internal::SizeOfType<RES>(),
132  MTAPI_DEFAULT_TASK_ATTRIBUTES);
133  }
134 
141  template <typename ARGS, typename RES>
143  Job const & job,
144  const ARGS * arguments,
145  RES * results,
146  TaskAttributes const & attributes
147  ) {
148  return Start(MTAPI_TASK_ID_NONE,
149  job.GetInternal(),
150  arguments, internal::SizeOfType<ARGS>(),
151  results, internal::SizeOfType<RES>(),
152  &attributes.GetInternal());
153  }
154 
161  template <typename ARGS, typename RES>
163  Job const & job,
164  const ARGS * arguments,
165  RES * results
166  ) {
167  return Start(MTAPI_TASK_ID_NONE,
168  job.GetInternal(),
169  arguments, internal::SizeOfType<ARGS>(),
170  results, internal::SizeOfType<RES>(),
171  MTAPI_DEFAULT_TASK_ATTRIBUTES);
172  }
173 
181  mtapi_status_t WaitAny(
182  mtapi_timeout_t timeout,
184  void ** result
187  ) {
188  mtapi_status_t status;
189  mtapi_group_wait_any(handle_, result, timeout, &status);
190  return status;
191  }
192 
199  mtapi_status_t WaitAny(
200  void ** result
203  ) {
204  return WaitAny(MTAPI_INFINITE, result);
205  }
206 
212  mtapi_status_t WaitAny(
213  mtapi_timeout_t timeout
215  ) {
216  return WaitAny(timeout, MTAPI_NULL);
217  }
218 
224  mtapi_status_t WaitAny() {
225  return WaitAny(MTAPI_INFINITE, MTAPI_NULL);
226  }
227 
234  mtapi_status_t WaitAll(
235  mtapi_timeout_t timeout
237  ) {
238  mtapi_status_t status;
239  mtapi_group_wait_all(handle_, timeout, &status);
240  return status;
241  }
242 
249  mtapi_status_t WaitAll() {
250  return WaitAll(MTAPI_INFINITE);
251  }
252 
260  mtapi_group_hndl_t GetInternal() const {
261  return handle_;
262  }
263 
264  friend class embb::base::Allocation;
265  friend class Node;
266 
267  private:
273  Group(
274  mtapi_group_id_t id,
275  mtapi_group_attributes_t const * attributes
277  ) {
278  mtapi_status_t status;
279  handle_ = mtapi_group_create(id, attributes, &status);
280  internal::CheckStatus(status);
281  }
282 
289  Task Start(
290  mtapi_task_id_t task_id,
291  mtapi_job_hndl_t job,
292  const void * arguments,
293  mtapi_size_t arguments_size,
294  void * results,
295  mtapi_size_t results_size,
296  mtapi_task_attributes_t const * attributes
298  ) {
299  mtapi_status_t status;
300  mtapi_task_hndl_t task_hndl =
301  mtapi_task_start(task_id, job, arguments, arguments_size,
302  results, results_size, attributes, handle_,
303  &status);
304  internal::CheckStatus(status);
305  return Task(task_hndl);
306  }
307 
308  mtapi_group_hndl_t handle_;
309 };
310 
311 } // namespace mtapi
312 } // namespace embb
313 
314 #endif // EMBB_MTAPI_GROUP_H_
Definition: lock_free_mpmc_queue.h:40
mtapi_status_t WaitAll(mtapi_timeout_t timeout)
Waits for all Task in the Group to finish for timeout milliseconds.
Definition: group.h:234
A singleton representing the MTAPI runtime.
Definition: node.h:70
mtapi_status_t WaitAny(void **result)
Waits for any Task in the Group to finish and retrieves the result buffer given in Start()...
Definition: group.h:199
mtapi_status_t WaitAny(mtapi_timeout_t timeout, void **result)
Waits for any Task in the Group to finish for timeout milliseconds and retrieves the result buffer gi...
Definition: group.h:181
mtapi_group_hndl_t GetInternal() const
Returns the internal representation of this object.
Definition: group.h:260
mtapi_status_t WaitAll()
Waits for all Task in the Group to finish.
Definition: group.h:249
void mtapi_group_wait_all(const mtapi_group_hndl_t group, const mtapi_timeout_t timeout, mtapi_status_t *status)
This function waits for the completion of a task group.
mtapi_status_t WaitAny(mtapi_timeout_t timeout)
Waits for any Task in the Group to finish for timeout milliseconds.
Definition: group.h:212
mtapi_status_t WaitAny()
Waits for any Task in the Group to finish.
Definition: group.h:224
mtapi_group_hndl_t mtapi_group_create(const mtapi_group_id_t group_id, const mtapi_group_attributes_t *attributes, mtapi_status_t *status)
This function creates a task group and returns a handle to the group.
mtapi_task_attributes_t const & GetInternal() const
Returns the internal representation of this object.
Definition: task_attributes.h:148
Represents a collection of Actions.
Definition: job.h:41
Task Start(Job const &job, const ARGS *arguments, RES *results)
Starts a new Task in this Group.
Definition: group.h:162
Group & operator=(Group const &other)
Copies a Group.
Definition: group.h:78
Contains attributes of a Task.
Definition: task_attributes.h:42
void Delete()
Deletes a Group object.
Definition: group.h:89
mtapi_task_hndl_t mtapi_task_start(const mtapi_task_id_t task_id, const mtapi_job_hndl_t job, const void *arguments, const mtapi_size_t arguments_size, void *result_buffer, const mtapi_size_t result_size, const mtapi_task_attributes_t *attributes, const mtapi_group_hndl_t group, mtapi_status_t *status)
This function schedules a task for execution.
Task Start(Job const &job, const ARGS *arguments, RES *results, TaskAttributes const &attributes)
Starts a new Task in this Group.
Definition: group.h:142
Group()
Constructs an invalid Group.
Definition: group.h:58
Group(Group const &other)
Copies a Group.
Definition: group.h:67
void mtapi_group_delete(const mtapi_group_hndl_t group, mtapi_status_t *status)
This function deletes a task group.
Represents a facility to wait for multiple related Tasks.
Definition: group.h:52
Task Start(mtapi_task_id_t task_id, Job const &job, const ARGS *arguments, RES *results, TaskAttributes const &attributes)
Starts a new Task in this Group.
Definition: group.h:101
void mtapi_group_wait_any(const mtapi_group_hndl_t group, void **result, const mtapi_timeout_t timeout, mtapi_status_t *status)
This function waits for the completion of any task in a task group.
Task Start(mtapi_task_id_t task_id, Job const &job, const ARGS *arguments, RES *results)
Starts a new Task in this Group.
Definition: group.h:122
Common (static) functionality for unaligned and aligned memory allocation.
Definition: memory_allocation.h:55
A Task represents a running Action of a specific Job.
Definition: task.h:41
mtapi_job_hndl_t GetInternal() const
Returns the internal representation of this object.
Definition: job.h:80