Embedded Multicore Building Blocks V1.0.0
queue.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_QUEUE_H_
28 #define EMBB_MTAPI_QUEUE_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/group.h>
34 #include <embb/mtapi/queue_attributes.h>
35 #include <embb/mtapi/task_attributes.h>
36 
37 namespace embb {
38 
39 namespace base {
40 
41 class Allocation;
42 
43 } // namespace base
44 
45 namespace mtapi {
46 
52 class Queue {
53  public:
58  Queue() {
59  handle_.id = 0;
60  handle_.tag = 0;
61  }
62 
68  Queue const & other
69  ) : handle_(other.handle_) {
70  // empty
71  }
72 
80  Queue const & other
81  ) {
82  handle_ = other.handle_;
83  return *this;
84  }
85 
90  void Delete() {
91  mtapi_queue_delete(handle_, MTAPI_INFINITE, MTAPI_NULL);
92  }
93 
99  void Enable() {
100  mtapi_status_t status;
101  mtapi_queue_enable(handle_, &status);
102  internal::CheckStatus(status);
103  }
104 
110  void Disable(
111  mtapi_timeout_t timeout
112  ) {
113  mtapi_status_t status;
114  mtapi_queue_disable(handle_, timeout, &status);
115  internal::CheckStatus(status);
116  }
117 
123  void Disable() {
124  Disable(MTAPI_INFINITE);
125  }
126 
133  template <typename ARGS, typename RES>
135  mtapi_task_id_t task_id,
136  const ARGS * arguments,
137  RES * results,
138  TaskAttributes const & attributes,
139  Group const & group
140  ) {
141  return Enqueue(task_id,
142  arguments, internal::SizeOfType<ARGS>(),
143  results, internal::SizeOfType<RES>(),
144  &attributes.GetInternal(), group.GetInternal());
145  }
146 
153  template <typename ARGS, typename RES>
155  mtapi_task_id_t task_id,
156  const ARGS * arguments,
157  RES * results,
158  Group const & group
159  ) {
160  return Enqueue(task_id,
161  arguments, internal::SizeOfType<ARGS>(),
162  results, internal::SizeOfType<RES>(),
163  MTAPI_DEFAULT_TASK_ATTRIBUTES, group.GetInternal());
164  }
165 
172  template <typename ARGS, typename RES>
174  mtapi_task_id_t task_id,
175  const ARGS * arguments,
176  RES * results,
177  TaskAttributes const & attributes
178  ) {
179  return Enqueue(task_id,
180  arguments, internal::SizeOfType<ARGS>(),
181  results, internal::SizeOfType<RES>(),
182  &attributes.GetInternal(), MTAPI_GROUP_NONE);
183  }
184 
191  template <typename ARGS, typename RES>
193  mtapi_task_id_t task_id,
194  const ARGS * arguments,
195  RES * results
196  ) {
197  return Enqueue(task_id,
198  arguments, internal::SizeOfType<ARGS>(),
199  results, internal::SizeOfType<RES>(),
200  MTAPI_DEFAULT_TASK_ATTRIBUTES, MTAPI_GROUP_NONE);
201  }
202 
209  template <typename ARGS, typename RES>
211  const ARGS * arguments,
212  RES * results,
213  TaskAttributes const & attributes,
214  Group const & group
215  ) {
216  return Enqueue(MTAPI_TASK_ID_NONE,
217  arguments, internal::SizeOfType<ARGS>(),
218  results, internal::SizeOfType<RES>(),
219  &attributes.GetInternal(), group.GetInternal());
220  }
221 
228  template <typename ARGS, typename RES>
230  const ARGS * arguments,
231  RES * results,
232  Group const & group
233  ) {
234  return Enqueue(MTAPI_TASK_ID_NONE,
235  arguments, internal::SizeOfType<ARGS>(),
236  results, internal::SizeOfType<RES>(),
237  MTAPI_DEFAULT_TASK_ATTRIBUTES, group.GetInternal());
238  }
239 
246  template <typename ARGS, typename RES>
248  const ARGS * arguments,
249  RES * results,
250  TaskAttributes const & attributes
251  ) {
252  return Enqueue(MTAPI_TASK_ID_NONE,
253  arguments, internal::SizeOfType<ARGS>(),
254  results, internal::SizeOfType<RES>(),
255  &attributes.GetInternal(), MTAPI_GROUP_NONE);
256  }
257 
264  template <typename ARGS, typename RES>
266  const ARGS * arguments,
267  RES * results
268  ) {
269  return Enqueue(MTAPI_TASK_ID_NONE,
270  arguments, internal::SizeOfType<ARGS>(),
271  results, internal::SizeOfType<RES>(),
272  MTAPI_DEFAULT_TASK_ATTRIBUTES, MTAPI_GROUP_NONE);
273  }
274 
282  mtapi_queue_hndl_t GetInternal() const {
283  return handle_;
284  }
285 
286  friend class embb::base::Allocation;
287  friend class Node;
288 
289  private:
290  Queue(
291  mtapi_queue_id_t queue_id,
292  Job const & job,
293  mtapi_queue_attributes_t const * attributes
294  ) {
295  mtapi_status_t status;
296  handle_ = mtapi_queue_create(queue_id, job.GetInternal(),
297  attributes, &status);
298  internal::CheckStatus(status);
299  }
300 
301  Task Enqueue(
302  mtapi_task_id_t task_id,
303  const void * arguments,
304  mtapi_size_t arguments_size,
305  void * results,
306  mtapi_size_t results_size,
307  mtapi_task_attributes_t const * attributes,
308  mtapi_group_hndl_t group
309  ) {
310  mtapi_status_t status;
311  mtapi_task_hndl_t task_hndl =
312  mtapi_task_enqueue(task_id, handle_, arguments, arguments_size,
313  results, results_size, attributes, group,
314  &status);
315  internal::CheckStatus(status);
316  return Task(task_hndl);
317  }
318 
319  mtapi_queue_hndl_t handle_;
320 };
321 
322 } // namespace mtapi
323 } // namespace embb
324 
325 #endif // EMBB_MTAPI_QUEUE_H_
Definition: lock_free_mpmc_queue.h:40
A singleton representing the MTAPI runtime.
Definition: node.h:70
Task Enqueue(const ARGS *arguments, RES *results)
Enqueues a new Task.
Definition: queue.h:265
mtapi_group_hndl_t GetInternal() const
Returns the internal representation of this object.
Definition: group.h:260
void mtapi_queue_enable(const mtapi_queue_hndl_t queue, mtapi_status_t *status)
This function may be called from any node with a valid queue handle to re-enable a queue previously d...
Task Enqueue(mtapi_task_id_t task_id, const ARGS *arguments, RES *results, TaskAttributes const &attributes)
Enqueues a new Task.
Definition: queue.h:173
mtapi_queue_hndl_t mtapi_queue_create(const mtapi_queue_id_t queue_id, const mtapi_job_hndl_t job, const mtapi_queue_attributes_t *attributes, mtapi_status_t *status)
This function creates a software queue object and associates it with the specified job...
void Delete()
Deletes a Queue object.
Definition: queue.h:90
void mtapi_queue_disable(const mtapi_queue_hndl_t queue, const mtapi_timeout_t timeout, mtapi_status_t *status)
This function disables the specified queue in such a way that it can be resumed later.
void mtapi_queue_delete(const mtapi_queue_hndl_t queue, const mtapi_timeout_t timeout, mtapi_status_t *status)
This function deletes the specified software queue.
Task Enqueue(const ARGS *arguments, RES *results, TaskAttributes const &attributes, Group const &group)
Enqueues a new Task.
Definition: queue.h:210
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 Enqueue(const ARGS *arguments, RES *results, Group const &group)
Enqueues a new Task.
Definition: queue.h:229
Allows for stream processing, either ordered or unordered.
Definition: queue.h:52
Contains attributes of a Task.
Definition: task_attributes.h:42
mtapi_queue_hndl_t GetInternal() const
Returns the internal representation of this object.
Definition: queue.h:282
Queue & operator=(Queue const &other)
Copies a Queue.
Definition: queue.h:79
Queue()
Constructs an invalid Queue.
Definition: queue.h:58
Task Enqueue(mtapi_task_id_t task_id, const ARGS *arguments, RES *results, Group const &group)
Enqueues a new Task.
Definition: queue.h:154
Queue(Queue const &other)
Copies a Queue.
Definition: queue.h:67
void Disable(mtapi_timeout_t timeout)
Disables the Queue.
Definition: queue.h:110
void Enable()
Enables the Queue.
Definition: queue.h:99
Task Enqueue(const ARGS *arguments, RES *results, TaskAttributes const &attributes)
Enqueues a new Task.
Definition: queue.h:247
Represents a facility to wait for multiple related Tasks.
Definition: group.h:52
Task Enqueue(mtapi_task_id_t task_id, const ARGS *arguments, RES *results, TaskAttributes const &attributes, Group const &group)
Enqueues a new Task.
Definition: queue.h:134
mtapi_task_hndl_t mtapi_task_enqueue(const mtapi_task_id_t task_id, const mtapi_queue_hndl_t queue, 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 using a queue.
Task Enqueue(mtapi_task_id_t task_id, const ARGS *arguments, RES *results)
Enqueues a new Task.
Definition: queue.h:192
Common (static) functionality for unaligned and aligned memory allocation.
Definition: memory_allocation.h:55
void Disable()
Disables the Queue.
Definition: queue.h:123
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