replicode
module.h
Go to the documentation of this file.
1 /*
2 * HUMANOBS - mBrane
3 *
4 * Eric Nivel
5 * Center for Analysis and Design of Intelligent Agents
6 * Reykjavik University, Menntavegur 1, 101 Reykjavik, Iceland
7 * http://cadia.ru.is
8 * Copyright(c)2012
9 *
10 * This software was developed by the above copyright holder as part of
11 * the HUMANOBS EU research project, in collaboration with the
12 * following parties:
13 *
14 * Autonomous Systems Laboratory
15 * Technical University of Madrid, Spain
16 * http://www.aslab.org/
17 *
18 * Communicative Machines
19 * Edinburgh, United Kingdom
20 * http://www.cmlabs.com/
21 *
22 * Istituto Dalle Molle di Studi sull'Intelligenza Artificiale
23 * University of Lugano and SUPSI, Switzerland
24 * http://www.idsia.ch/
25 *
26 * Institute of Cognitive Sciences and Technologies
27 * Consiglio Nazionale delle Ricerche, Italy
28 * http://www.istc.cnr.it/
29 *
30 * Dipartimento di Ingegneria Informatica
31 * University of Palermo, Italy
32 * http://roboticslab.dinfo.unipa.it/index.php/Main/HomePage
33 *
34 *
35 * --- HUMANOBS Open-Source BSD License, with CADIA Clause v 1.0 ---
36 *
37 * Redistribution and use in source and binary forms, with or without
38 * modification, is permitted provided that the following conditions
39 * are met:
40 *
41 * - Redistributions of source code must retain the above copyright
42 * and collaboration notice, this list of conditions and the
43 * following disclaimer.
44 *
45 * - Redistributions in binary form must reproduce the above copyright
46 * notice, this list of conditions and the following
47 * disclaimer in the documentation and/or other materials provided
48 * with the distribution.
49 *
50 * - Neither the name of its copyright holders nor the names of its
51 * contributors may be used to endorse or promote products
52 * derived from this software without specific prior written permission.
53 *
54 * - CADIA Clause: The license granted in and to the software under this
55 * agreement is a limited-use license. The software may not be used in
56 * furtherance of:
57 * (i) intentionally causing bodily injury or severe emotional distress
58 * to any person;
59 * (ii) invading the personal privacy or violating the human rights of
60 * any person; or
61 * (iii) committing or preparing for any act of war.
62 *
63 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
64 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
65 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
66 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
67 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
68 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
69 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
70 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
71 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
72 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
73 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
74 */
75 
76 #ifndef mBrane_sdk_module_h
77 #define mBrane_sdk_module_h
78 
79 #include "../CoreLibrary/utils.h"
80 #include "message.h"
81 #include <thread>
82 #include <mutex>
83 
84 using namespace mBrane::sdk::payloads;
85 
86 namespace mBrane
87 {
88 class XThread;
89 class ModuleDescriptor;
90 class Node;
91 namespace sdk
92 {
93 namespace module
94 {
95 
96 // Root class for all modules.
97 // The actual base class for user-defined modules is defined in application.h and respectively, in library.h for module library vendors
98 // Migration sequence: migrateOut->dump->payload->send-/ /-receive->load->migrateIn; modules can then launch their own internal threads if any
99 class mBrane_dll _Module:
100  public _Object
101 {
102  friend class mBrane::Node;
103  friend class mBrane::XThread;
105 private:
107  std::mutex mutex;
109 protected:
114  bool _ready; // set to false after stop and migrateOut, set to true after start and migrateIn
115  _Module();
116  void sleep(int64_t d);
117  void wait(std::thread *threads[], uint32_t threadCount);
118  void wait(std::thread *_thread);
119 public:
120  typedef enum {
121  DISCARD = 0,
122  WAIT = 1,
123  PREEMPT = 2
124  } Decision;
125  virtual ~_Module();
126  virtual void loadParameters(const std::vector<int32_t> &numbers, const std::vector<std::string> &strings) {} // parameters is deallocated after the call; called only upon local construction - in other ints, will not be called upon remote construction (using the CreateModule message)
127  uint8_t &priority();
128  bool canMigrate(); // on another node; dynamic
129  bool isReady(); // if not, messages will be lost
130  virtual uint32_t dumpSize(); // dynamic
131  virtual _Payload *dump(); // dumps the current state; can be called anytime
132  virtual void load(_Payload *chunk); // initializes itself from a previously saved state
133  virtual void _start() = 0; // called when the module is loaded in a thread for the first time, i.e. at node starting time
134  virtual void _stop() = 0; // called just before the module is unloaded from the thread for the last time, i.e. at node shutdown time
135  virtual void migrateOut(); // called when the module is unloaded from its current thread for migration
136  virtual void migrateIn(); // called when the module is loaded in a new thread after having migrated
137  virtual void notify(_Payload *p) = 0; // called when the module receives a message
138  virtual void notify(uint16_t sid, _Payload *p) = 0; // called when the module receives data from a stream
139  virtual Decision dispatch(_Payload *p) = 0; // called when the module code is already processed by an XThread and a new message comes in
140 }; //class object
141 } //namespace module
142 } //namespace sdk
143 } //namespace mbrane
144 
145 
146 #endif
Definition: executing.h:93
uint16_t _cid
Definition: module.h:110
Definition: base.h:121
uint16_t _id
Definition: module.h:111
std::thread thread
Definition: RR.h:320
bool _canMigrate
Definition: module.h:112
Definition: array.h:84
Definition: module_descriptor.h:150
Definition: payload.h:122
uint8_t _priority
Definition: module.h:113
Definition: control_messages.cpp:83
ModuleDescriptor * descriptor
Definition: module.h:108
Definition: node.h:96
XThread * processor
Definition: module.h:106
Definition: module.h:99
virtual void loadParameters(const std::vector< int32_t > &numbers, const std::vector< std::string > &strings)
Definition: module.h:126
std::mutex mutex
Definition: module.h:107
bool _ready
Definition: module.h:114