group.h 3.89 KB
Newer Older
1
/*
2
 * Copyright (c) 2014-2015, Siemens AG. All rights reserved.
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

27 28
#ifndef EMBB_TASKS_GROUP_H_
#define EMBB_TASKS_GROUP_H_
29 30

#include <embb/mtapi/c/mtapi.h>
31 32
#include <embb/tasks/action.h>
#include <embb/tasks/task.h>
33 34 35 36 37 38 39 40 41

namespace embb {

namespace base {

class Allocation;

} // namespace base

42
namespace tasks {
43 44 45 46 47

/**
  * Represents a facility to wait for multiple related
  * \link Task Tasks\endlink.
  *
48
  * \ingroup CPP_TASKS
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
  */
class Group {
 public:
  /**
    * Runs an Action within the Group.
    * \return A Task identifying the Action to run
    * \throws ErrorException if the Task object could not be constructed.
    * \threadsafe
    */
  Task Spawn(
    Action action                      /**< [in] The Action to run */
    );

  /**
    * Runs an Action within the Group. The \c id is returned by WaitAny().
    * \return A Task identifying the Action to run
    * \throws ErrorException if the Task object could not be constructed.
    * \threadsafe
    */
  Task Spawn(
    mtapi_task_id_t id,                /**< [in] The id to return by
                                            WaitAny() */
    Action action                      /**< [in] The Action to run */
    );

  /**
    * Waits for any Task in the Group to finish for \c timeout milliseconds.
    * \return The status of the Task that finished execution
    * \threadsafe
    */
  mtapi_status_t WaitAny(
    mtapi_timeout_t timeout            /**< [in] Timeout duration in
                                            milliseconds */
    );

  /**
    * Waits for any Task in the Group to finish for \c timeout milliseconds and
    * retrieves the id given in Spawn().
    * \return The status of the Task that finished execution, \c MTAPI_TIMEOUT
    *         or \c MTAPI_ERR_*
    * \threadsafe
    */
  mtapi_status_t WaitAny(
    mtapi_timeout_t timeout,           /**< [in] Timeout duration in
                                            milliseconds */
    mtapi_task_id_t & id               /**< [out] The id given to Spawn() */
    );

  /**
    * Waits for all Task in the Group to finish for \c timeout milliseconds.
    * \return \c MTAPI_SUCCESS, \c MTAPI_TIMEOUT, \c MTAPI_ERR_* or the status
    *         of any failed Task
    * \threadsafe
    */
  mtapi_status_t WaitAll(
    mtapi_timeout_t timeout            /**< [in] Timeout duration in
                                            milliseconds */
    );

  friend class embb::base::Allocation;
  friend class Node;
  friend class Queue;

 private:
  Group(Group const & group);
  Group();
  ~Group();

  void Create();

  mtapi_group_hndl_t handle_;
};

122
} // namespace tasks
123 124
} // namespace embb

125
#endif // EMBB_TASKS_GROUP_H_