Fawkes API
Fawkes Development Version
|
Access to the robot memory based on mongodb. More...
#include "robot_memory.h"
Public Member Functions | |
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. More... | |
QResCursor | query (mongo::Query query, const std::string &collection="") |
Query information from the robot memory. More... | |
mongo::BSONObj | aggregate (const std::vector< mongo::BSONObj > &pipeline, const std::string &collection="") |
Aggregation call on the robot memory. More... | |
int | insert (mongo::BSONObj obj, const std::string &collection="") |
Inserts a document into the robot memory. More... | |
int | insert (std::vector< mongo::BSONObj > v_obj, const std::string &collection="") |
Inserts all document of a vector into the robot memory. More... | |
int | insert (const std::string &obj_str, const std::string &collection="") |
Inserts a document into the robot memory. More... | |
int | update (mongo::Query query, mongo::BSONObj update, const std::string &collection="", bool upsert=false) |
Updates documents in the robot memory. More... | |
int | update (mongo::Query query, const std::string &update_str, const std::string &collection="", bool upsert=false) |
Updates documents in the robot memory. More... | |
mongo::BSONObj | find_one_and_update (const mongo::BSONObj &filter, const mongo::BSONObj &update, const std::string &collection, bool upsert=false, bool return_new=true) |
Atomically update and retrieve document. More... | |
int | remove (mongo::Query query, const std::string &collection="") |
Remove documents from the robot memory. More... | |
mongo::BSONObj | mapreduce (mongo::Query 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/) More... | |
QResCursor | aggregate (mongo::BSONObj pipeline, const std::string &collection="") |
Performs an aggregation operation on the robot memory (https://docs.mongodb.com/v3.2/reference/method/db.collection.aggregate/) More... | |
int | drop_collection (const std::string &collection) |
Drop (= remove) a whole collection and all documents inside it. More... | |
int | clear_memory () |
Remove the whole database of the robot memory and all documents inside. More... | |
int | restore_collection (const std::string &collection, const std::string &directory="@CONFDIR@/robot-memory") |
Restore a previously dumped collection from a directory. More... | |
int | dump_collection (const std::string &collection, const std::string &directory="@CONFDIR@/robot-memory") |
Dump (= save) a collection to the filesystem to restore it later. More... | |
int | create_index (mongo::BSONObj keys, const std::string &collection="", bool unique=false) |
Create an index on a collection. More... | |
bool | mutex_setup_ttl (float max_age_sec) |
Setup time-to-live index for mutexes. More... | |
bool | mutex_create (const std::string &name) |
Explicitly create a mutex. More... | |
bool | mutex_destroy (const std::string &name) |
Destroy a mutex. More... | |
bool | mutex_try_lock (const std::string &name, bool force=false) |
Try to acquire a lock for a mutex. More... | |
bool | mutex_try_lock (const std::string &name, const std::string &identity, bool force=false) |
Try to acquire a lock for a mutex. More... | |
bool | mutex_unlock (const std::string &name, const std::string &identity) |
Release lock on mutex. More... | |
bool | mutex_renew_lock (const std::string &name, const std::string &identity) |
Renew a mutex. More... | |
bool | mutex_expire_locks (float max_age_sec) |
Expire old locks on mutexes. More... | |
template<typename T > | |
EventTrigger * | register_trigger (mongo::Query query, const std::string &collection, void(T::*callback)(mongo::BSONObj), T *_obj) |
Register a trigger to be notified when the robot memory is updated and the updated document matches the query. More... | |
template<typename T > | |
EventTrigger * | register_trigger (const std::string &query_str, const std::string &collection, void(T::*callback)(mongo::BSONObj), T *_obj) |
Register a trigger to be notified when the robot memory is updated and the updated document matches the query. More... | |
void | remove_trigger (EventTrigger *trigger) |
Remove a previously registered trigger. More... | |
template<typename T > | |
Computable * | register_computable (const mongo::Query &query_to_compute, const std::string &collection, std::list< mongo::BSONObj >(T::*compute_func)(const mongo::BSONObj &, 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. More... | |
void | remove_computable (Computable *computable) |
Remove previously registered computable. More... | |
Friends | |
class | RobotMemoryThread |
Friend the RobotMemoryThread so that only it can access the loop and init functions. More... | |
Access to the robot memory based on mongodb.
Using this class, you can query/insert/remove/update information in the robot memory. Furthermore, you can register trigger to get notified when something was changed in the robot memory matching your query and you can access computables, which are on demand computed information, by registering the computables and then querying as if the information would already be in the database.
Definition at line 48 of file robot_memory.h.
RobotMemory::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.
config | Fawkes config |
logger | Fawkes logger |
clock | Fawkes clock |
mongo_connection_manager | MongoDBConnCreator to create client connections to the shared and local db |
blackboard | Fawkes blackboard |
Definition at line 60 of file robot_memory.cpp.
mongo::BSONObj RobotMemory::aggregate | ( | const std::vector< mongo::BSONObj > & | pipeline, |
const std::string & | collection = "" |
||
) |
Aggregation call on the robot memory.
pipeline | Series of commands defining the aggregation |
collection | The database and collection to query as string (e.g. robmem.worldmodel) |
Definition at line 211 of file robot_memory.cpp.
Referenced by PddlRobotMemoryThread::loop().
QResCursor RobotMemory::aggregate | ( | mongo::BSONObj | pipeline, |
const std::string & | collection = "" |
||
) |
Performs an aggregation operation on the robot memory (https://docs.mongodb.com/v3.2/reference/method/db.collection.aggregate/)
pipeline | A sequence of data aggregation operations or stages. See the https://docs.mongodb.com/v3.2/reference/operator/aggregation-pipeline/ for details |
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
Definition at line 488 of file robot_memory.cpp.
int RobotMemory::clear_memory | ( | ) |
Remove the whole database of the robot memory and all documents inside.
Definition at line 526 of file robot_memory.cpp.
int RobotMemory::create_index | ( | mongo::BSONObj | obj, |
const std::string & | collection = "" , |
||
bool | unique = false |
||
) |
Create an index on a collection.
obj | The keys document as BSONObj |
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
unique | true to create unique index |
Definition at line 278 of file robot_memory.cpp.
int RobotMemory::drop_collection | ( | const std::string & | collection | ) |
Drop (= remove) a whole collection and all documents inside it.
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
Definition at line 513 of file robot_memory.cpp.
Referenced by ComputablesManager::check_and_compute(), and restore_collection().
int RobotMemory::dump_collection | ( | const std::string & | collection, |
const std::string & | directory = "@CONFDIR@/robot-memory" |
||
) |
Dump (= save) a collection to the filesystem to restore it later.
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
directory | Directory to dump the collection to |
Definition at line 595 of file robot_memory.cpp.
mongo::BSONObj RobotMemory::find_one_and_update | ( | const mongo::BSONObj & | filter, |
const mongo::BSONObj & | update, | ||
const std::string & | collection, | ||
bool | upsert = false , |
||
bool | return_new = true |
||
) |
Atomically update and retrieve document.
filter | The filter defining the document to update. If multiple match takes the first one. |
update | Update statement. May only contain update operators! |
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
upsert | Should the update document be inserted if the query returns no documents? |
return_new | return the document before (false) or after (true) the update has been applied? |
return_new
either before or after the udpate has been applied. Definition at line 408 of file robot_memory.cpp.
References update().
int RobotMemory::insert | ( | mongo::BSONObj | obj, |
const std::string & | collection = "" |
||
) |
Inserts a document into the robot memory.
obj | The document as BSONObj |
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
Definition at line 250 of file robot_memory.cpp.
Referenced by ComputablesManager::check_and_compute(), insert(), StnGeneratorThread::loop(), and RobotMemoryThread::loop().
int RobotMemory::insert | ( | std::vector< mongo::BSONObj > | v_obj, |
const std::string & | collection = "" |
||
) |
Inserts all document of a vector into the robot memory.
v_obj | The vector of BSONObj document |
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
Definition at line 307 of file robot_memory.cpp.
int RobotMemory::insert | ( | const std::string & | obj_str, |
const std::string & | collection = "" |
||
) |
Inserts a document into the robot memory.
obj_str | The document as json string |
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
Definition at line 342 of file robot_memory.cpp.
References insert().
mongo::BSONObj RobotMemory::mapreduce | ( | mongo::Query | 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/)
query | Which documents to use for the map step |
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
js_map_fun | Map function in JavaScript as string |
js_reduce_fun | Reduce function in JavaScript as string |
Definition at line 469 of file robot_memory.cpp.
References query().
bool RobotMemory::mutex_create | ( | const std::string & | name | ) |
Explicitly create a mutex.
This is an optional step, a mutex is also created automatically when trying to acquire the lock for the first time. Adding it explicitly may increase visibility, e.g., in the database. Use it for mutexes which are locked only very infrequently.
name | mutex name |
Definition at line 785 of file robot_memory.cpp.
bool RobotMemory::mutex_destroy | ( | const std::string & | name | ) |
Destroy a mutex.
The mutex is erased from the database. This is done disregarding it's current lock state.
name | mutex name |
Definition at line 813 of file robot_memory.cpp.
bool RobotMemory::mutex_expire_locks | ( | float | max_age_sec | ) |
Expire old locks on mutexes.
This will update the database and set all mutexes to unlocked for which the lock-time is older than the given maximum age.
max_age_sec | maximum age of locks in seconds |
Definition at line 1052 of file robot_memory.cpp.
bool RobotMemory::mutex_renew_lock | ( | const std::string & | name, |
const std::string & | identity | ||
) |
Renew a mutex.
Renewing means updating the lock timestamp to the current time to avoid expiration. Note that the lock must currently be held by the given identity.
name | mutex name |
identity | string to set as lock-holder (defaults to hostname if empty) |
Definition at line 975 of file robot_memory.cpp.
References fawkes::HostInfo::name().
bool RobotMemory::mutex_setup_ttl | ( | float | max_age_sec | ) |
Setup time-to-live index for mutexes.
Setting up a time-to-live index for mutexes enables automatic expiration through the database. Note, however, that the documents are expired only every 60 seconds. This has two consequences:
max_age_sec | maximum age of locks in seconds |
Definition at line 1027 of file robot_memory.cpp.
bool RobotMemory::mutex_try_lock | ( | const std::string & | name, |
bool | force = false |
||
) |
Try to acquire a lock for a mutex.
This will access the database and atomically find and update (or insert) a mutex lock. If the mutex has not been created it is added automatically. If the lock cannot be acquired the function also returns immediately. There is no blocked waiting for the lock.
name | mutex name |
force | true to force acquisition of the lock, i.e., even if the lock has already been acquired take ownership (steal the lock). |
Definition at line 921 of file robot_memory.cpp.
bool RobotMemory::mutex_try_lock | ( | const std::string & | name, |
const std::string & | identity, | ||
bool | force = false |
||
) |
Try to acquire a lock for a mutex.
This will access the database and atomically find and update (or insert) a mutex lock. If the mutex has not been created it is added automatically. If the lock cannot be acquired the function also returns immediately. There is no blocked waiting for the lock.
name | mutex name |
identity | string to set as lock-holder |
force | true to force acquisition of the lock, i.e., even if the lock has already been acquired take ownership (steal the lock). |
Definition at line 840 of file robot_memory.cpp.
References fawkes::HostInfo::name().
bool RobotMemory::mutex_unlock | ( | const std::string & | name, |
const std::string & | identity | ||
) |
Release lock on mutex.
name | mutex name |
identity | string to set as lock-holder |
Definition at line 932 of file robot_memory.cpp.
References fawkes::HostInfo::name().
QResCursor RobotMemory::query | ( | mongo::Query | query, |
const std::string & | collection = "" |
||
) |
Query information from the robot memory.
query | The query returned documents have to match (essentially a BSONObj) |
collection | The database and collection to query as string (e.g. robmem.worldmodel) |
Definition at line 174 of file robot_memory.cpp.
Referenced by ComputablesManager::check_and_compute(), StnGeneratorThread::loop(), RobotMemoryThread::loop(), mapreduce(), EventTriggerManager::register_trigger(), register_trigger(), remove(), and update().
|
inline |
Registers a Computable which provides information in the robot memory that is computed on demand.
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. |
collection | db.collection to fill with computed information |
compute_func | Callback function that computes the information and retruns a list of computed documents |
obj | Pointer to class the callback is a function of (usaually this) |
caching_time | How long should computed results for a query be cached and be used for identical queries in that time? |
priority | Computable priority ordering the evaluation |
Definition at line 156 of file robot_memory.h.
References ComputablesManager::register_computable().
|
inline |
Register a trigger to be notified when the robot memory is updated and the updated document matches the query.
query | Query the updated document has to match |
collection | db.collection to use |
callback | Callback function (e.g. &Class::callback) |
_obj | Pointer to class the callback is a function of (usaually this) |
Definition at line 117 of file robot_memory.h.
References query(), and EventTriggerManager::register_trigger().
Referenced by register_trigger().
|
inline |
Register a trigger to be notified when the robot memory is updated and the updated document matches the query.
query_str | Query as JSON string |
collection | db.collection to use |
callback | Callback function (e.g. &Class::callback) |
_obj | Pointer to class the callback is a function of (usaually this) |
Definition at line 134 of file robot_memory.h.
References register_trigger().
int RobotMemory::remove | ( | mongo::Query | query, |
const std::string & | collection = "" |
||
) |
Remove documents from the robot memory.
query | Which documents to remove |
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
Definition at line 440 of file robot_memory.cpp.
References query().
Referenced by ComputablesManager::cleanup_computed_docs(), and RobotMemoryThread::loop().
void RobotMemory::remove_computable | ( | Computable * | computable | ) |
Remove previously registered computable.
computable | The computable to remove |
Definition at line 771 of file robot_memory.cpp.
void RobotMemory::remove_trigger | ( | EventTrigger * | trigger | ) |
Remove a previously registered trigger.
trigger | Pointer to the trigger to remove |
Definition at line 761 of file robot_memory.cpp.
int RobotMemory::restore_collection | ( | const std::string & | collection, |
const std::string & | directory = "@CONFDIR@/robot-memory" |
||
) |
Restore a previously dumped collection from a directory.
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
directory | Directory of the dump |
Definition at line 543 of file robot_memory.cpp.
References drop_collection().
int RobotMemory::update | ( | mongo::Query | query, |
mongo::BSONObj | update, | ||
const std::string & | collection = "" , |
||
bool | upsert = false |
||
) |
Updates documents in the robot memory.
query | The query defining which documents to update |
update | What to change in these documents |
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
upsert | Should the update document be inserted if the query returns no documents? |
Definition at line 356 of file robot_memory.cpp.
References query().
Referenced by find_one_and_update(), PddlPlannerThread::loop(), RobotMemoryThread::loop(), and update().
int RobotMemory::update | ( | mongo::Query | query, |
const std::string & | update_str, | ||
const std::string & | collection = "" , |
||
bool | upsert = false |
||
) |
Updates documents in the robot memory.
query | The query defining which documents to update |
update_str | What to change in these documents as json string |
collection | The database and collection to use as string (e.g. robmem.worldmodel) |
upsert | Should the update document be inserted if the query returns no documents? |
Definition at line 390 of file robot_memory.cpp.
|
friend |
Friend the RobotMemoryThread so that only it can access the loop and init functions.
Definition at line 51 of file robot_memory.h.