Fawkes API  Fawkes Development Version
RobotMemory Class Reference

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 >
EventTriggerregister_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 >
EventTriggerregister_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 >
Computableregister_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...
 

Detailed Description

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.

Author
Frederik Zwilling

Definition at line 48 of file robot_memory.h.

Constructor & Destructor Documentation

◆ RobotMemory()

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.

Parameters
configFawkes config
loggerFawkes logger
clockFawkes clock
mongo_connection_managerMongoDBConnCreator to create client connections to the shared and local db
blackboardFawkes blackboard

Definition at line 60 of file robot_memory.cpp.

Member Function Documentation

◆ aggregate() [1/2]

mongo::BSONObj RobotMemory::aggregate ( const std::vector< mongo::BSONObj > &  pipeline,
const std::string &  collection = "" 
)

Aggregation call on the robot memory.

Parameters
pipelineSeries of commands defining the aggregation
collectionThe database and collection to query as string (e.g. robmem.worldmodel)
Returns
Result object

Definition at line 211 of file robot_memory.cpp.

Referenced by PddlRobotMemoryThread::loop().

◆ aggregate() [2/2]

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/)

Parameters
pipelineA sequence of data aggregation operations or stages. See the https://docs.mongodb.com/v3.2/reference/operator/aggregation-pipeline/ for details
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
Returns
Cursor to get the documents from, NULL for invalid pipeline

Definition at line 488 of file robot_memory.cpp.

◆ clear_memory()

int RobotMemory::clear_memory ( )

Remove the whole database of the robot memory and all documents inside.

Returns
1: Success 0: Error

Definition at line 526 of file robot_memory.cpp.

◆ create_index()

int RobotMemory::create_index ( mongo::BSONObj  obj,
const std::string &  collection = "",
bool  unique = false 
)

Create an index on a collection.

Parameters
objThe keys document as BSONObj
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
uniquetrue to create unique index
Returns
1: Success 0: Error

Definition at line 278 of file robot_memory.cpp.

◆ drop_collection()

int RobotMemory::drop_collection ( const std::string &  collection)

Drop (= remove) a whole collection and all documents inside it.

Parameters
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
Returns
1: Success 0: Error

Definition at line 513 of file robot_memory.cpp.

Referenced by ComputablesManager::check_and_compute(), and restore_collection().

◆ dump_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.

Parameters
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
directoryDirectory to dump the collection to
Returns
1: Success 0: Error

Definition at line 595 of file robot_memory.cpp.

◆ find_one_and_update()

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.

Parameters
filterThe filter defining the document to update. If multiple match takes the first one.
updateUpdate statement. May only contain update operators!
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
upsertShould the update document be inserted if the query returns no documents?
return_newreturn the document before (false) or after (true) the update has been applied?
Returns
document, depending on return_new either before or after the udpate has been applied.

Definition at line 408 of file robot_memory.cpp.

References update().

◆ insert() [1/3]

int RobotMemory::insert ( mongo::BSONObj  obj,
const std::string &  collection = "" 
)

Inserts a document into the robot memory.

Parameters
objThe document as BSONObj
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
Returns
1: Success 0: Error

Definition at line 250 of file robot_memory.cpp.

Referenced by ComputablesManager::check_and_compute(), insert(), StnGeneratorThread::loop(), and RobotMemoryThread::loop().

◆ insert() [2/3]

int RobotMemory::insert ( std::vector< mongo::BSONObj >  v_obj,
const std::string &  collection = "" 
)

Inserts all document of a vector into the robot memory.

Parameters
v_objThe vector of BSONObj document
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
Returns
1: Success 0: Error

Definition at line 307 of file robot_memory.cpp.

◆ insert() [3/3]

int RobotMemory::insert ( const std::string &  obj_str,
const std::string &  collection = "" 
)

Inserts a document into the robot memory.

Parameters
obj_strThe document as json string
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
Returns
1: Success 0: Error

Definition at line 342 of file robot_memory.cpp.

References insert().

◆ mapreduce()

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/)

Parameters
queryWhich documents to use for the map step
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
js_map_funMap function in JavaScript as string
js_reduce_funReduce function in JavaScript as string
Returns
BSONObj containing the result

Definition at line 469 of file robot_memory.cpp.

References query().

◆ mutex_create()

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.

Parameters
namemutex name
Returns
true if operation was successful, false on failure

Definition at line 785 of file robot_memory.cpp.

◆ mutex_destroy()

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.

Parameters
namemutex name
Returns
true if operation was successful, false on failure

Definition at line 813 of file robot_memory.cpp.

◆ mutex_expire_locks()

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.

Parameters
max_age_secmaximum age of locks in seconds
Returns
true if operation was successful, false on failure

Definition at line 1052 of file robot_memory.cpp.

◆ mutex_renew_lock()

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.

Parameters
namemutex name
identitystring to set as lock-holder (defaults to hostname if empty)
Returns
true if operation was successful, false on failure

Definition at line 975 of file robot_memory.cpp.

References fawkes::HostInfo::name().

◆ mutex_setup_ttl()

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 lower than 60 seconds cannot be achieved
  • locks may be held for up to just below 60 seconds longer than configured, i.e., if the mutex had not yet expired when the background tasks runs.
    Parameters
    max_age_secmaximum age of locks in seconds
    Returns
    true if operation was successful, false on failure

Definition at line 1027 of file robot_memory.cpp.

◆ mutex_try_lock() [1/2]

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.

Parameters
namemutex name
forcetrue to force acquisition of the lock, i.e., even if the lock has already been acquired take ownership (steal the lock).
Returns
true if operation was successful, false on failure

Definition at line 921 of file robot_memory.cpp.

◆ mutex_try_lock() [2/2]

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.

Parameters
namemutex name
identitystring to set as lock-holder
forcetrue to force acquisition of the lock, i.e., even if the lock has already been acquired take ownership (steal the lock).
Returns
true if operation was successful, false on failure

Definition at line 840 of file robot_memory.cpp.

References fawkes::HostInfo::name().

◆ mutex_unlock()

bool RobotMemory::mutex_unlock ( const std::string &  name,
const std::string &  identity 
)

Release lock on mutex.

Parameters
namemutex name
identitystring to set as lock-holder
Returns
true if operation was successful, false on failure

Definition at line 932 of file robot_memory.cpp.

References fawkes::HostInfo::name().

◆ query()

QResCursor RobotMemory::query ( mongo::Query  query,
const std::string &  collection = "" 
)

Query information from the robot memory.

Parameters
queryThe query returned documents have to match (essentially a BSONObj)
collectionThe database and collection to query as string (e.g. robmem.worldmodel)
Returns
Cursor to get the documents from, NULL for invalid query

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().

◆ register_computable()

template<typename T >
Computable* RobotMemory::register_computable ( const mongo::Query &  query_to_compute,
const std::string &  collection,
std::list< mongo::BSONObj >(T::*)(const mongo::BSONObj &, const std::string &)  compute_func,
T *  obj,
double  caching_time = 0.0,
int  priority = 0 
)
inline

Registers a Computable which provides information in the robot memory that is computed on demand.

Parameters
query_to_computeQuery describing what the function computes. Yor computable is called when an new query matches the key value fields in the identifiyer.
collectiondb.collection to fill with computed information
compute_funcCallback function that computes the information and retruns a list of computed documents
objPointer to class the callback is a function of (usaually this)
caching_timeHow long should computed results for a query be cached and be used for identical queries in that time?
priorityComputable priority ordering the evaluation
Returns
Computable Object pointer used for removing it

Definition at line 156 of file robot_memory.h.

References ComputablesManager::register_computable().

◆ register_trigger() [1/2]

template<typename T >
EventTrigger* RobotMemory::register_trigger ( mongo::Query  query,
const std::string &  collection,
void(T::*)(mongo::BSONObj)  callback,
T *  _obj 
)
inline

Register a trigger to be notified when the robot memory is updated and the updated document matches the query.

Parameters
queryQuery the updated document has to match
collectiondb.collection to use
callbackCallback function (e.g. &Class::callback)
_objPointer to class the callback is a function of (usaually this)
Returns
Trigger object pointer, save it to remove the trigger later

Definition at line 117 of file robot_memory.h.

References query(), and EventTriggerManager::register_trigger().

Referenced by register_trigger().

◆ register_trigger() [2/2]

template<typename T >
EventTrigger* RobotMemory::register_trigger ( const std::string &  query_str,
const std::string &  collection,
void(T::*)(mongo::BSONObj)  callback,
T *  _obj 
)
inline

Register a trigger to be notified when the robot memory is updated and the updated document matches the query.

Parameters
query_strQuery as JSON string
collectiondb.collection to use
callbackCallback function (e.g. &Class::callback)
_objPointer to class the callback is a function of (usaually this)
Returns
Trigger object pointer, save it to remove the trigger later

Definition at line 134 of file robot_memory.h.

References register_trigger().

◆ remove()

int RobotMemory::remove ( mongo::Query  query,
const std::string &  collection = "" 
)

Remove documents from the robot memory.

Parameters
queryWhich documents to remove
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
Returns
1: Success 0: Error

Definition at line 440 of file robot_memory.cpp.

References query().

Referenced by ComputablesManager::cleanup_computed_docs(), and RobotMemoryThread::loop().

◆ remove_computable()

void RobotMemory::remove_computable ( Computable computable)

Remove previously registered computable.

Parameters
computableThe computable to remove

Definition at line 771 of file robot_memory.cpp.

◆ remove_trigger()

void RobotMemory::remove_trigger ( EventTrigger trigger)

Remove a previously registered trigger.

Parameters
triggerPointer to the trigger to remove

Definition at line 761 of file robot_memory.cpp.

◆ restore_collection()

int RobotMemory::restore_collection ( const std::string &  collection,
const std::string &  directory = "@CONFDIR@/robot-memory" 
)

Restore a previously dumped collection from a directory.

Parameters
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
directoryDirectory of the dump
Returns
1: Success 0: Error

Definition at line 543 of file robot_memory.cpp.

References drop_collection().

◆ update() [1/2]

int RobotMemory::update ( mongo::Query  query,
mongo::BSONObj  update,
const std::string &  collection = "",
bool  upsert = false 
)

Updates documents in the robot memory.

Parameters
queryThe query defining which documents to update
updateWhat to change in these documents
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
upsertShould the update document be inserted if the query returns no documents?
Returns
1: Success 0: Error

Definition at line 356 of file robot_memory.cpp.

References query().

Referenced by find_one_and_update(), PddlPlannerThread::loop(), RobotMemoryThread::loop(), and update().

◆ update() [2/2]

int RobotMemory::update ( mongo::Query  query,
const std::string &  update_str,
const std::string &  collection = "",
bool  upsert = false 
)

Updates documents in the robot memory.

Parameters
queryThe query defining which documents to update
update_strWhat to change in these documents as json string
collectionThe database and collection to use as string (e.g. robmem.worldmodel)
upsertShould the update document be inserted if the query returns no documents?
Returns
1: Success 0: Error

Definition at line 390 of file robot_memory.cpp.

References query(), and update().

Friends And Related Function Documentation

◆ RobotMemoryThread

friend class RobotMemoryThread
friend

Friend the RobotMemoryThread so that only it can access the loop and init functions.

Definition at line 51 of file robot_memory.h.


The documentation for this class was generated from the following files: