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...
 
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. More...
 
int insert (bsoncxx::document::view, const std::string &collection="")
 Inserts a document into the robot memory. More...
 
int insert (std::vector< bsoncxx::document::view > 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 (const bsoncxx::document::view &query, const bsoncxx::document::view &update, const std::string &collection="", bool upsert=false)
 Updates documents in the robot memory. More...
 
int update (const bsoncxx::document::view &query, const std::string &update_str, const std::string &collection="", bool upsert=false)
 Updates documents in the robot memory. More...
 
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. More...
 
int remove (const bsoncxx::document::view &query, const std::string &collection="")
 Remove documents from the robot memory. More...
 
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/) More...
 
mongocxx::cursor aggregate (mongocxx::pipeline &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 &dbcollection, const std::string &directory="@CONFDIR@/robot-memory", std::string target_dbcollection="")
 Restore a previously dumped collection from a directory. More...
 
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. More...
 
int create_index (bsoncxx::document::view 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 (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 the query. More...
 
template<typename T >
EventTriggerregister_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 the query. More...
 
void remove_trigger (EventTrigger *trigger)
 Remove a previously registered trigger. More...
 
template<typename T >
Computableregister_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. 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 46 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 67 of file robot_memory.cpp.

Member Function Documentation

◆ aggregate()

cursor RobotMemory::aggregate ( mongocxx::pipeline &  pipeline,
const std::string &  collection_name = "" 
)

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
collection_nameThe 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 460 of file robot_memory.cpp.

Referenced by PddlRobotMemoryThread::loop().

◆ 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 498 of file robot_memory.cpp.

◆ create_index()

int RobotMemory::create_index ( bsoncxx::document::view  keys,
const std::string &  collection_name = "",
bool  unique = false 
)

Create an index on a collection.

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

Definition at line 234 of file robot_memory.cpp.

◆ drop_collection()

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

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

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

Definition at line 484 of file robot_memory.cpp.

Referenced by ComputablesManager::check_and_compute().

◆ dump_collection()

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

Dump (= save) a collection to the filesystem to restore it later.

Parameters
dbcollectionThe 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 574 of file robot_memory.cpp.

References fawkes::StringConversions::resolve_path().

◆ find_one_and_update()

document::value RobotMemory::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.

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 368 of file robot_memory.cpp.

◆ insert() [1/3]

int RobotMemory::insert ( bsoncxx::document::view  doc,
const std::string &  collection_name = "" 
)

Inserts a document into the robot memory.

Parameters
docA view of the document to insert
collection_nameThe database and collection to use as string (e.g. robmem.worldmodel)
Returns
1: Success 0: Error

Definition at line 209 of file robot_memory.cpp.

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

◆ insert() [2/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 299 of file robot_memory.cpp.

◆ insert() [3/3]

int RobotMemory::insert ( std::vector< bsoncxx::document::view >  docs,
const std::string &  collection_name = "" 
)

Inserts all document of a vector into the robot memory.

Parameters
docsThe vector of BSON documents as views
collection_nameThe database and collection to use as string (e.g. robmem.worldmodel)
Returns
1: Success 0: Error

Definition at line 265 of file robot_memory.cpp.

◆ mapreduce()

bsoncxx::document::value RobotMemory::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/)

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 438 of file robot_memory.cpp.

◆ 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 739 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 769 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 1045 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 959 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 1018 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 892 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 801 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 903 of file robot_memory.cpp.

References fawkes::HostInfo::name().

◆ query()

cursor RobotMemory::query ( bsoncxx::document::view  query,
const std::string &  collection_name = "",
mongocxx::options::find  query_options = mongocxx::options::find() 
)

Query information from the robot memory.

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

Definition at line 178 of file robot_memory.cpp.

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

◆ register_computable()

template<typename T >
Computable* RobotMemory::register_computable ( bsoncxx::document::value &&  query_to_compute,
const std::string &  collection,
std::list< bsoncxx::document::value >(T::*)(const bsoncxx::document::view &, 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 158 of file robot_memory.h.

References ComputablesManager::register_computable().

◆ register_trigger() [1/2]

template<typename T >
EventTrigger* RobotMemory::register_trigger ( const bsoncxx::document::view &  query,
const std::string &  collection,
void(T::*)(const bsoncxx::document::view &)  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 119 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::*)(bsoncxx::document::value)  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 136 of file robot_memory.h.

References register_trigger().

◆ remove()

int RobotMemory::remove ( const bsoncxx::document::view &  query,
const std::string &  collection_name = "" 
)

Remove documents from the robot memory.

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

Definition at line 411 of file robot_memory.cpp.

Referenced by RobotMemoryThread::loop().

◆ remove_computable()

void RobotMemory::remove_computable ( Computable computable)

Remove previously registered computable.

Parameters
computableThe computable to remove

Definition at line 725 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 715 of file robot_memory.cpp.

◆ restore_collection()

int RobotMemory::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.

Parameters
dbcollectionThe database and collection to use as string (e.g. robmem.worldmodel)
directoryDirectory of the dump
target_dbcollectionOptional different database and collection where the dump is restored to. If not set, the dump will be restored in the previous place
Returns
1: Success 0: Error

Definition at line 519 of file robot_memory.cpp.

References fawkes::StringConversions::resolve_path().

◆ update() [1/2]

int RobotMemory::update ( const bsoncxx::document::view &  query,
const bsoncxx::document::view &  update,
const std::string &  collection_name = "",
bool  upsert = false 
)

Updates documents in the robot memory.

Parameters
queryThe query defining which documents to update
updateWhat to change in these documents
collection_nameThe 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 313 of file robot_memory.cpp.

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

◆ update() [2/2]

int RobotMemory::update ( const bsoncxx::document::view &  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 350 of file robot_memory.cpp.

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 49 of file robot_memory.h.


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