Fawkes API Fawkes Development Version
robot_memory.h
1/***************************************************************************
2 * robot_memory.h - Class for storing and querying information in the RobotMemory
3 *
4 * Created: Aug 23, 2016 1:34:32 PM 2016
5 * Copyright 2016 Frederik Zwilling
6 * 2017 Tim Niemueller [www.niemueller.de]
7 ****************************************************************************/
8
9/* This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Library General Public License for more details.
18 *
19 * Read the full text in the LICENSE.GPL file in the doc directory.
20 */
21#ifndef _PLUGINS_ROBOT_MEMORY_ROBOT_MEMORY_H_
22#define _PLUGINS_ROBOT_MEMORY_ROBOT_MEMORY_H_
23
24#include "computables/computables_manager.h"
25#include "event_trigger_manager.h"
26
27#include <aspect/blackboard.h>
28#include <aspect/clock.h>
29#include <aspect/configurable.h>
30#include <aspect/logging.h>
31#include <core/threading/mutex.h>
32#include <plugins/mongodb/aspect/mongodb_conncreator.h>
33
34#include <bsoncxx/json.hpp>
35#include <memory>
36#include <utility>
37#include <vector>
38
39namespace fawkes {
40class RobotMemoryInterface;
41#ifdef USE_TIMETRACKER
42class TimeTracker;
43#endif
44} // namespace fawkes
45
47{
48 /// Friend the RobotMemoryThread so that only it can access the loop and init functions
49 friend class RobotMemoryThread;
50
51public:
55 fawkes::MongoDBConnCreator *mongo_connection_manager,
57 virtual ~RobotMemory();
58
59 //robot memory functions
60 mongocxx::cursor query(bsoncxx::document::view query,
61 const std::string & collection_name = "",
62 mongocxx::options::find query_options = mongocxx::options::find());
63 // TODO fix int return codes, should be booleans
64 int insert(bsoncxx::document::view, const std::string &collection = "");
65 int insert(std::vector<bsoncxx::document::view> v_obj, const std::string &collection = "");
66 int insert(const std::string &obj_str, const std::string &collection = "");
67 int update(const bsoncxx::document::view &query,
68 const bsoncxx::document::view &update,
69 const std::string & collection = "",
70 bool upsert = false);
71 int update(const bsoncxx::document::view &query,
72 const std::string & update_str,
73 const std::string & collection = "",
74 bool upsert = false);
75 bsoncxx::document::value find_one_and_update(const bsoncxx::document::view &filter,
76 const bsoncxx::document::view &update,
77 const std::string & collection,
78 bool upsert = false,
79 bool return_new = true);
80 int remove(const bsoncxx::document::view &query, const std::string &collection = "");
81 bsoncxx::document::value mapreduce(const bsoncxx::document::view &query,
82 const std::string & collection,
83 const std::string & js_map_fun,
84 const std::string & js_reduce_fun);
85 mongocxx::cursor aggregate(mongocxx::pipeline &pipeline, const std::string &collection = "");
86 int drop_collection(const std::string &collection);
87 int clear_memory();
88 int restore_collection(const std::string &dbcollection,
89 const std::string &directory = "@CONFDIR@/robot-memory",
90 std::string target_dbcollection = "");
91 int dump_collection(const std::string &dbcollection,
92 const std::string &directory = "@CONFDIR@/robot-memory");
93 int create_index(bsoncxx::document::view keys,
94 const std::string & collection = "",
95 bool unique = false);
96
97 //bool semaphore_create(const std::string& name, unsigned int value);
98 //bool semaphore_acquire(const std::string& name, unsigned int v = 1);
99 //bool semaphore_release(const std::string& name, unsigned int v = 1);
100 bool mutex_setup_ttl(float max_age_sec);
101 bool mutex_create(const std::string &name);
102 bool mutex_destroy(const std::string &name);
103 bool mutex_try_lock(const std::string &name, bool force = false);
104 bool mutex_try_lock(const std::string &name, const std::string &identity, bool force = false);
105 bool mutex_unlock(const std::string &name, const std::string &identity);
106 bool mutex_renew_lock(const std::string &name, const std::string &identity);
107 bool mutex_expire_locks(float max_age_sec);
108
109 /**
110 * Register a trigger to be notified when the robot memory is updated and the updated document matches the query
111 * @param query Query the updated document has to match
112 * @param collection db.collection to use
113 * @param callback Callback function (e.g. &Class::callback)
114 * @param _obj Pointer to class the callback is a function of (usaually this)
115 * @return Trigger object pointer, save it to remove the trigger later
116 */
117 template <typename T>
119 register_trigger(const bsoncxx::document::view &query,
120 const std::string & collection,
121 void (T::*callback)(const bsoncxx::document::view &),
122 T *_obj)
123 {
124 return trigger_manager_->register_trigger(query, collection, callback, _obj);
125 }
126 /**
127 * Register a trigger to be notified when the robot memory is updated and the updated document matches the query
128 * @param query_str Query as JSON string
129 * @param collection db.collection to use
130 * @param callback Callback function (e.g. &Class::callback)
131 * @param _obj Pointer to class the callback is a function of (usaually this)
132 * @return Trigger object pointer, save it to remove the trigger later
133 */
134 template <typename T>
136 register_trigger(const std::string &query_str,
137 const std::string &collection,
138 void (T::*callback)(bsoncxx::document::value),
139 T *_obj)
140 {
141 return register_trigger(bsoncxx::from_json(query_str), collection, callback, _obj);
142 }
143 void remove_trigger(EventTrigger *trigger);
144
145 /**
146 * Registers a Computable which provides information in the robot memory that is computed on demand.
147 *
148 * @param query_to_compute Query describing what the function computes. Yor computable is called when an new query matches the key value fields in the identifiyer.
149 * @param collection db.collection to fill with computed information
150 * @param compute_func Callback function that computes the information and retruns a list of computed documents
151 * @param obj Pointer to class the callback is a function of (usaually this)
152 * @param caching_time How long should computed results for a query be cached and be used for identical queries in that time?
153 * @param priority Computable priority ordering the evaluation
154 * @return Computable Object pointer used for removing it
155 */
156 template <typename T>
157 Computable *
158 register_computable(bsoncxx::document::value &&query_to_compute,
159 const std::string & collection,
160 std::list<bsoncxx::document::value> (
161 T::*compute_func)(const bsoncxx::document::view &, const std::string &),
162 T * obj,
163 double caching_time = 0.0,
164 int priority = 0)
165 {
166 return computables_manager_->register_computable(
167 std::move(query_to_compute), collection, compute_func, obj, caching_time, priority);
168 }
169 void remove_computable(Computable *computable);
170
171private:
172 fawkes::MongoDBConnCreator *mongo_connection_manager_;
173 mongocxx::client * mongodb_client_local_;
174 mongocxx::client * mongodb_client_distributed_;
175 bool distributed_;
176 fawkes::Configuration * config_;
177 fawkes::Logger * logger_;
178 fawkes::Clock * clock_;
179 fawkes::BlackBoard * blackboard_;
180
181 const char * name_ = "RobotMemory";
182 std::string database_name_;
183 std::string default_collection_;
184 bool debug_;
185 fawkes::Mutex mutex_;
186 fawkes::RobotMemoryInterface *rm_if_;
187 EventTriggerManager * trigger_manager_;
188 ComputablesManager * computables_manager_;
189 std::vector<std::string> distributed_dbs_;
190
191 std::string cfg_coord_database_;
192 std::string cfg_coord_mutex_collection_;
193
194 void init();
195 void loop();
196
197 // TODO make log level an enum (if we need it at all)
198 void log(const std::string &what, const std::string &level = "info");
199 void log_deb(const std::string &what, const std::string &level = "info");
200 void log(const bsoncxx::document::view &query,
201 const std::string & what,
202 const std::string & level = "info");
203 void log_deb(const bsoncxx::document::view &query,
204 const std::string & what,
205 const std::string & level = "info");
206
207 bool is_distributed_database(const std::string &dbcollection);
208 std::string get_hostport(const std::string &dbcollection);
209 mongocxx::client * get_mongodb_client(const std::string &collection);
210 mongocxx::collection get_collection(const std::string &dbcollection);
211
212#ifdef USE_TIMETRACKER
214 unsigned int tt_loopcount_;
215 unsigned int ttc_events_;
216 unsigned int ttc_cleanup_;
217#endif
218};
219
220#endif /* FAWKES_SRC_PLUGINS_ROBOT_MEMORY_ROBOT_MEMORY_H_ */
Class holding information for a single computable this class also enhances computed documents by addi...
Definition: computable.h:32
This class manages registering computables and can check if any computables are invoced by a query.
Computable * register_computable(bsoncxx::document::value &&query_to_compute, const std::string &collection, std::list< bsoncxx::document::value >(T::*compute_func)(const bsoncxx::document::view &, const std::string &), T *obj, double caching_time=0.0, int priority=0)
Registers a Computable which provides information in the robot memory that is computed on demand.
Manager to realize triggers on events in the robot memory.
EventTrigger * register_trigger(const bsoncxx::document::view &query, std::string dbcollection, void(T::*callback)(const bsoncxx::document::view &), T *obj)
Register a trigger to be notified when the robot memory is updated and the updated document matches t...
Class holding all information about an EventTrigger.
Definition: event_trigger.h:32
Thread that provides a robot memory with MongoDB.
virtual void loop()
Code to execute in the thread.
virtual void init()
Initialize the thread.
Access to the robot memory based on mongodb.
Definition: robot_memory.h:47
bool mutex_create(const std::string &name)
Explicitly create a mutex.
int dump_collection(const std::string &dbcollection, const std::string &directory="@CONFDIR@/robot-memory")
Dump (= save) a collection to the filesystem to restore it later.
bool mutex_destroy(const std::string &name)
Destroy a mutex.
bool mutex_renew_lock(const std::string &name, const std::string &identity)
Renew a mutex.
bool mutex_unlock(const std::string &name, const std::string &identity)
Release lock on mutex.
void remove_trigger(EventTrigger *trigger)
Remove a previously registered trigger.
EventTrigger * register_trigger(const bsoncxx::document::view &query, const std::string &collection, void(T::*callback)(const bsoncxx::document::view &), T *_obj)
Register a trigger to be notified when the robot memory is updated and the updated document matches t...
Definition: robot_memory.h:119
mongocxx::cursor query(bsoncxx::document::view query, const std::string &collection_name="", mongocxx::options::find query_options=mongocxx::options::find())
Query information from the robot memory.
bsoncxx::document::value find_one_and_update(const bsoncxx::document::view &filter, const bsoncxx::document::view &update, const std::string &collection, bool upsert=false, bool return_new=true)
Atomically update and retrieve document.
Computable * register_computable(bsoncxx::document::value &&query_to_compute, const std::string &collection, std::list< bsoncxx::document::value >(T::*compute_func)(const bsoncxx::document::view &, const std::string &), T *obj, double caching_time=0.0, int priority=0)
Registers a Computable which provides information in the robot memory that is computed on demand.
Definition: robot_memory.h:158
bool mutex_setup_ttl(float max_age_sec)
Setup time-to-live index for mutexes.
bsoncxx::document::value mapreduce(const bsoncxx::document::view &query, const std::string &collection, const std::string &js_map_fun, const std::string &js_reduce_fun)
Performs a MapReduce operation on the robot memory (https://docs.mongodb.com/manual/core/map-reduce/)
int remove(const bsoncxx::document::view &query, const std::string &collection="")
Remove documents from the robot memory.
int insert(bsoncxx::document::view, const std::string &collection="")
Inserts a document into the robot memory.
mongocxx::cursor aggregate(mongocxx::pipeline &pipeline, const std::string &collection="")
Performs an aggregation operation on the robot memory (https://docs.mongodb.com/v3....
void remove_computable(Computable *computable)
Remove previously registered computable.
int drop_collection(const std::string &collection)
Drop (= remove) a whole collection and all documents inside it.
int update(const bsoncxx::document::view &query, const bsoncxx::document::view &update, const std::string &collection="", bool upsert=false)
Updates documents in the robot memory.
bool mutex_try_lock(const std::string &name, bool force=false)
Try to acquire a lock for a mutex.
int create_index(bsoncxx::document::view keys, const std::string &collection="", bool unique=false)
Create an index on a collection.
int clear_memory()
Remove the whole database of the robot memory and all documents inside.
RobotMemory(fawkes::Configuration *config, fawkes::Logger *logger, fawkes::Clock *clock, fawkes::MongoDBConnCreator *mongo_connection_manager, fawkes::BlackBoard *blackboard)
Robot Memory Constructor with objects of the thread.
int restore_collection(const std::string &dbcollection, const std::string &directory="@CONFDIR@/robot-memory", std::string target_dbcollection="")
Restore a previously dumped collection from a directory.
bool mutex_expire_locks(float max_age_sec)
Expire old locks on mutexes.
EventTrigger * register_trigger(const std::string &query_str, const std::string &collection, void(T::*callback)(bsoncxx::document::value), T *_obj)
Register a trigger to be notified when the robot memory is updated and the updated document matches t...
Definition: robot_memory.h:136
BlackBoard * blackboard
This is the BlackBoard instance you can use to interact with the BlackBoard.
Definition: blackboard.h:44
The BlackBoard abstract class.
Definition: blackboard.h:46
Clock * clock
By means of this member access to the clock is given.
Definition: clock.h:42
This is supposed to be the central clock in Fawkes.
Definition: clock.h:35
Configuration * config
This is the Configuration member used to access the configuration.
Definition: configurable.h:41
Interface for configuration handling.
Definition: config.h:68
Interface for logging.
Definition: logger.h:42
Logger * logger
This is the Logger member used to access the logger.
Definition: logging.h:41
Interface for a MongoDB connection creator.
Mutex mutual exclusion lock.
Definition: mutex.h:33
const char * name() const
Get name of thread.
Definition: thread.h:100
Time tracking utility.
Definition: tracker.h:37
Fawkes library namespace.