mirror of
https://github.com/RetroShare/RetroShare.git
synced 2025-05-03 22:55:04 -04:00
documentation of p3GroupDistrib, p3Channels, and CacheStrapper
give a hand at http://retroshare.sourceforge.net/wiki/index.php/API_Documentation git-svn-id: http://svn.code.sf.net/p/retroshare/code/trunk@3279 b45a01b8-16f6-495d-af2f-9b41ad6348cc
This commit is contained in:
chrisparker126
parent
1787e50b94
commit
a25dbf7358
4 changed files with 599 additions and 310 deletions
|
|
@ -65,31 +65,39 @@ typedef uint32_t RsPeerId;
|
|||
typedef std::string RsPeerId;
|
||||
|
||||
/******************************** CacheId ********************************/
|
||||
|
||||
/*!
|
||||
* Use this to identify the type of cache source, strapper,
|
||||
*/
|
||||
class CacheId
|
||||
{
|
||||
public:
|
||||
CacheId() :type(0), subid(0) { return; }
|
||||
CacheId(uint16_t a, uint16_t b) :type(a), subid(b) { return; }
|
||||
uint16_t type;
|
||||
uint16_t subid;
|
||||
uint16_t type; /// cache types, this should be set to services type
|
||||
uint16_t subid; /// should be initialised when using multicache feature of cachestrapper
|
||||
};
|
||||
|
||||
|
||||
bool operator<(const CacheId &a, const CacheId &b);
|
||||
|
||||
|
||||
/*!
|
||||
* Use for identifying physical files that have been chosen as cache data
|
||||
* note: this does not actual store the data but serves to locate on network (via hash attribute,
|
||||
* and on file via path)
|
||||
*/
|
||||
class CacheData
|
||||
{
|
||||
public:
|
||||
|
||||
RsPeerId pid;
|
||||
std::string pname; /* peer name (can be used by cachestore) */
|
||||
CacheId cid;
|
||||
std::string path;
|
||||
RsPeerId pid; /// peer id
|
||||
std::string pname; /// peer name (can be used by cachestore)
|
||||
CacheId cid; /// cache id
|
||||
std::string path; /// file system path where physical cache data is located
|
||||
std::string name;
|
||||
std::string hash;
|
||||
uint64_t size;
|
||||
time_t recvd;
|
||||
time_t recvd; /// received timestamp
|
||||
};
|
||||
|
||||
|
||||
|
|
@ -97,29 +105,37 @@ std::ostream &operator<<(std::ostream &out, const CacheData &d);
|
|||
|
||||
/***************************** CacheTransfer *****************************/
|
||||
|
||||
/**
|
||||
* Interface for FileTransfer Class to support cache
|
||||
*/
|
||||
class CacheTransfer
|
||||
{
|
||||
public:
|
||||
CacheTransfer(CacheStrapper *cs) :strapper(cs) { return; }
|
||||
virtual ~CacheTransfer() {}
|
||||
|
||||
/* upload side of things .... searches through CacheStrapper. */
|
||||
bool FindCacheFile(std::string hash, std::string &path, uint64_t &size);
|
||||
CacheTransfer(CacheStrapper *cs) :strapper(cs) { return; }
|
||||
virtual ~CacheTransfer() {}
|
||||
|
||||
/*!
|
||||
* upload side of things .... searches through CacheStrapper.
|
||||
*/
|
||||
bool FindCacheFile(std::string hash, std::string &path, uint64_t &size);
|
||||
|
||||
/* At the download side RequestCache() => overloaded RequestCacheFile()
|
||||
* the class should then call CompletedCache() or FailedCache()
|
||||
*/
|
||||
|
||||
bool RequestCache(CacheData &data, CacheStore *cbStore); /* request from CacheStore */
|
||||
/*!
|
||||
* At the download side RequestCache() => overloaded RequestCacheFile()
|
||||
* the class should then call CompletedCache() or FailedCache()
|
||||
*/
|
||||
bool RequestCache(CacheData &data, CacheStore *cbStore); /* request from CacheStore */
|
||||
|
||||
protected:
|
||||
/* to be overloaded */
|
||||
virtual bool RequestCacheFile(RsPeerId id, std::string path, std::string hash, uint64_t size);
|
||||
virtual bool CancelCacheFile(RsPeerId id, std::string path, std::string hash, uint64_t size);
|
||||
|
||||
bool CompletedCache(std::string hash); /* internal completion -> does cb */
|
||||
bool FailedCache(std::string hash); /* internal completion -> does cb */
|
||||
/*!
|
||||
* to be overloaded
|
||||
*/
|
||||
virtual bool RequestCacheFile(RsPeerId id, std::string path, std::string hash, uint64_t size);
|
||||
virtual bool CancelCacheFile(RsPeerId id, std::string path, std::string hash, uint64_t size);
|
||||
|
||||
bool CompletedCache(std::string hash); /* internal completion -> does cb */
|
||||
bool FailedCache(std::string hash); /* internal completion -> does cb */
|
||||
|
||||
private:
|
||||
|
||||
|
|
@ -135,117 +151,181 @@ bool FailedCache(std::string hash); /* internal completion
|
|||
|
||||
typedef std::map<uint16_t, CacheData> CacheSet;
|
||||
|
||||
/*!
|
||||
* Implements features needed for a service to act as a cachesource and allow pushing a of cache data from service to strapper
|
||||
* Service is able to use this class for refresh its cache (push cache data)
|
||||
* and interface to load and check cache availablility among peers (source of cache data)
|
||||
* Architecturally Cachestrapper maintains the cachesource (which is passed as a pointer handle) while the cachesource-inheriting
|
||||
* service can update cachesource as to new cache sources (cache data) created. Equivalently it enquiries through cache source for
|
||||
* new cache data from peers
|
||||
* @see p3Distrib
|
||||
*/
|
||||
class CacheSource
|
||||
{
|
||||
public:
|
||||
CacheSource(uint16_t t, bool m, CacheStrapper *cs, std::string cachedir);
|
||||
virtual ~CacheSource() {}
|
||||
|
||||
/* called to determine available cache for peer -
|
||||
* default acceptable (returns all)
|
||||
*/
|
||||
virtual bool cachesAvailable(RsPeerId pid, std::map<CacheId, CacheData> &ids);
|
||||
CacheSource(uint16_t t, bool m, CacheStrapper *cs, std::string cachedir);
|
||||
virtual ~CacheSource() {}
|
||||
|
||||
/*!
|
||||
* function called at startup to load from
|
||||
* configuration file....
|
||||
* to be overloaded by inherited class
|
||||
*/
|
||||
virtual bool loadLocalCache(const CacheData &data);
|
||||
/*!
|
||||
* called to determine available cache for peer -
|
||||
* default acceptable (returns all)
|
||||
*/
|
||||
virtual bool cachesAvailable(RsPeerId pid, std::map<CacheId, CacheData> &ids);
|
||||
|
||||
/* control Caches available */
|
||||
bool refreshCache(const CacheData &data);
|
||||
bool clearCache(CacheId id);
|
||||
/*!
|
||||
* function called at startup to load from
|
||||
* configuration file....
|
||||
* to be overloaded by inherited class
|
||||
*/
|
||||
virtual bool loadLocalCache(const CacheData &data);
|
||||
|
||||
/* get private data */
|
||||
std::string getCacheDir() { return cacheDir; }
|
||||
bool isMultiCache() { return multiCache; }
|
||||
uint16_t getCacheType() { return cacheType; }
|
||||
/* control Caches available */
|
||||
bool refreshCache(const CacheData &data);
|
||||
bool clearCache(CacheId id);
|
||||
|
||||
/* display */
|
||||
void listCaches(std::ostream &out);
|
||||
/* get private data */
|
||||
std::string getCacheDir() { return cacheDir; }
|
||||
bool isMultiCache() { return multiCache; }
|
||||
uint16_t getCacheType() { return cacheType; }
|
||||
|
||||
/* search */
|
||||
bool findCache(std::string hash, CacheData &data) const;
|
||||
/* display */
|
||||
void listCaches(std::ostream &out);
|
||||
|
||||
/* search */
|
||||
bool findCache(std::string hash, CacheData &data) const;
|
||||
|
||||
protected:
|
||||
|
||||
uint16_t cacheType; /* for checking */
|
||||
bool multiCache; /* do we care about subid's */
|
||||
CacheStrapper *mStrapper;
|
||||
uint16_t cacheType; /// for checking of cache type (usually of child class of source)
|
||||
bool multiCache; /// whether multisource is in use or not.
|
||||
CacheStrapper *mStrapper;
|
||||
|
||||
/*** MUTEX LOCKING */
|
||||
void lockData() const;
|
||||
void unlockData() const;
|
||||
/*** MUTEX LOCKING */
|
||||
void lockData() const;
|
||||
void unlockData() const;
|
||||
|
||||
CacheSet caches;
|
||||
CacheSet caches; /// all cache data local and remote stored here
|
||||
|
||||
private:
|
||||
private:
|
||||
|
||||
std::string cacheDir;
|
||||
mutable RsMutex cMutex;
|
||||
|
||||
std::string cacheDir;
|
||||
mutable RsMutex cMutex;
|
||||
};
|
||||
|
||||
|
||||
/*!
|
||||
* Base Class for data cache. eg. FileCache/Store.
|
||||
* @see p3Distrib. pqiMonitor
|
||||
*/
|
||||
class CacheStore
|
||||
{
|
||||
public:
|
||||
|
||||
CacheStore(uint16_t t, bool m, CacheStrapper *cs, CacheTransfer *cft, std::string cachedir);
|
||||
virtual ~CacheStore() {}
|
||||
/*!
|
||||
*
|
||||
* @param t set to particular rs_service id. see rsserviceids.h
|
||||
* @param m whether this is multicache service (true) or not(false)
|
||||
* @param cs cache strapper instance responsible for maintaining the cache service
|
||||
* @param cft cache transfer instance responsible for rquestiing and tranfering caches
|
||||
* @param cachedir directory used to store cache related info for cachestore client
|
||||
* @return
|
||||
*/
|
||||
CacheStore(uint16_t t, bool m, CacheStrapper *cs, CacheTransfer *cft, std::string cachedir);
|
||||
virtual ~CacheStore() {}
|
||||
|
||||
/* current stored data */
|
||||
bool getStoredCache(CacheData &data); /* use pid/cid in data */
|
||||
bool getAllStoredCaches(std::list<CacheData> &data); /* use pid/cid in data */
|
||||
/* current stored data */
|
||||
|
||||
/* input from CacheStrapper -> store can then download new data */
|
||||
void availableCache(const CacheData &data);
|
||||
/*!
|
||||
*
|
||||
* @param data returns cache data for pid/cid set in data itself
|
||||
* @return false is unsuccessful and vice versa
|
||||
*/
|
||||
bool getStoredCache(CacheData &data); /* use pid/cid in data */
|
||||
|
||||
/* called when the download is completed ... updates internal data */
|
||||
void downloadedCache(const CacheData &data);
|
||||
/*!
|
||||
*
|
||||
* @param data all cache store by cachestore is store here
|
||||
* @return false not returned, only true at the moment
|
||||
*/
|
||||
bool getAllStoredCaches(std::list<CacheData> &data); /* use pid/cid in data */
|
||||
|
||||
/* called if the download fails */
|
||||
void failedCache(const CacheData &data);
|
||||
/*!
|
||||
* input from CacheStrapper -> store can then download new data
|
||||
*/
|
||||
void availableCache(const CacheData &data);
|
||||
|
||||
/* virtual functions overloaded by cache implementor */
|
||||
virtual bool fetchCache(const CacheData &data); /* a question? */
|
||||
virtual int nameCache(CacheData &data); /* fill in the name/path */
|
||||
virtual int loadCache(const CacheData &data); /* actual load, once data available */
|
||||
/*!
|
||||
* should be called when the download is completed ... cache data is loaded
|
||||
*/
|
||||
void downloadedCache(const CacheData &data);
|
||||
|
||||
/* get private data */
|
||||
std::string getCacheDir() { return cacheDir; }
|
||||
bool isMultiCache() { return multiCache; }
|
||||
uint16_t getCacheType() { return cacheType; }
|
||||
/*!
|
||||
* called if the download fails, TODO: nothing done yet
|
||||
*/
|
||||
void failedCache(const CacheData &data);
|
||||
|
||||
/* display */
|
||||
void listCaches(std::ostream &out);
|
||||
/* virtual functions overloaded by cache implementor */
|
||||
|
||||
/*!
|
||||
* @param data cache data is stored here
|
||||
* @return false is failed (cache does not exist), otherwise true
|
||||
*/
|
||||
virtual bool fetchCache(const CacheData &data); /* a question? */
|
||||
virtual int nameCache(CacheData &data); /* fill in the name/path */
|
||||
virtual int loadCache(const CacheData &data); /* actual load, once data available */
|
||||
|
||||
/* get private data */
|
||||
|
||||
std::string getCacheDir() { return cacheDir; }
|
||||
bool isMultiCache() { return multiCache; }
|
||||
uint16_t getCacheType() { return cacheType; }
|
||||
|
||||
/*!
|
||||
* display, e.g. can pass std::out, cerr, ofstream, etc
|
||||
*/
|
||||
void listCaches(std::ostream &out);
|
||||
|
||||
protected:
|
||||
/*** MUTEX LOCKING */
|
||||
void lockData() const;
|
||||
void unlockData() const;
|
||||
|
||||
/* This function is called to store Cache Entry in the CacheStore Table.
|
||||
* it must be called from within a Mutex Lock....
|
||||
*
|
||||
* It doesn't lock itself -> to avoid race conditions
|
||||
*/
|
||||
void locked_storeCacheEntry(const CacheData &data);
|
||||
bool locked_getStoredCache(CacheData &data);
|
||||
/*!
|
||||
* ** MUTEX LOCKING
|
||||
*/
|
||||
void lockData() const;
|
||||
|
||||
private:
|
||||
/*!
|
||||
* ** MUTEX LOCKING
|
||||
*/
|
||||
void unlockData() const;
|
||||
|
||||
uint16_t cacheType; /* for checking */
|
||||
bool multiCache; /* do we care about subid's */
|
||||
/*! This function is called to store Cache Entry in the CacheStore Table.
|
||||
* it must be called from within a Mutex Lock....
|
||||
*
|
||||
* It doesn't lock itself -> to avoid race conditions
|
||||
*/
|
||||
void locked_storeCacheEntry(const CacheData &data);
|
||||
|
||||
CacheStrapper *mStrapper;
|
||||
CacheTransfer *cacheTransfer;
|
||||
/*! This function is called to store Cache Entry in the CacheStore Table.
|
||||
* it must be called from within a Mutex Lock....
|
||||
*
|
||||
* It doesn't lock itself -> to avoid race conditions
|
||||
*/
|
||||
bool locked_getStoredCache(CacheData &data);
|
||||
|
||||
std::string cacheDir;
|
||||
private:
|
||||
|
||||
mutable RsMutex cMutex;
|
||||
uint16_t cacheType; /* for checking */
|
||||
bool multiCache; /* do we care about subid's */
|
||||
|
||||
std::map<RsPeerId, CacheSet> caches;
|
||||
CacheStrapper *mStrapper;
|
||||
CacheTransfer *cacheTransfer;
|
||||
|
||||
std::string cacheDir;
|
||||
|
||||
mutable RsMutex cMutex;
|
||||
|
||||
std::map<RsPeerId, CacheSet> caches;
|
||||
|
||||
};
|
||||
|
||||
|
|
@ -254,28 +334,52 @@ bool locked_getStoredCache(CacheData &data);
|
|||
/***************************** CacheStrapper *****************************/
|
||||
|
||||
|
||||
/* Make Sure you get the Ids right! */
|
||||
/*!
|
||||
* a convenient to pass cache handles to cachestrapper to maintain the cache service
|
||||
* Make Sure you get the Ids right! see rsservicesids.h.
|
||||
* When creating a cache service this data structure is
|
||||
* source, usually the child class of store and source also serves as both handles
|
||||
* @see CacheStrapper
|
||||
*/
|
||||
class CachePair
|
||||
{
|
||||
public:
|
||||
CachePair()
|
||||
:source(NULL), store(NULL), id(0, 0) { return; }
|
||||
|
||||
CachePair(CacheSource *a, CacheStore *b, CacheId c)
|
||||
:source(a), store(b), id(c) { return; }
|
||||
/*!
|
||||
* Default constructor, all variables set to NULL
|
||||
*/
|
||||
CachePair()
|
||||
:source(NULL), store(NULL), id(0, 0) { return; }
|
||||
|
||||
CacheSource *source;
|
||||
CacheStore *store;
|
||||
CacheId id;
|
||||
/*!
|
||||
*
|
||||
* @param a cache source for service
|
||||
* @param b cache store for service
|
||||
* @param c the cache service id, c.type should be set to service id service-child class of store and source
|
||||
*/
|
||||
CachePair(CacheSource *a, CacheStore *b, CacheId c)
|
||||
:source(a), store(b), id(c) { return; }
|
||||
|
||||
CacheSource *source;
|
||||
CacheStore *store;
|
||||
CacheId id; /// should be set id type to service types of store and source service-child class, and subid for multicache use
|
||||
};
|
||||
|
||||
|
||||
bool operator<(const CachePair &a, const CachePair &b);
|
||||
|
||||
|
||||
/*!
|
||||
* CacheStrapper: maintains a set of CacheSources, and CacheStores,
|
||||
* queries and updates as new information arrives.
|
||||
*/
|
||||
class CacheStrapper: public pqiMonitor, public p3Config
|
||||
{
|
||||
public:
|
||||
|
||||
/*!
|
||||
* @param cm handle used by strapper for getting peer connection information (online peers, sslids...)
|
||||
* @return
|
||||
*/
|
||||
CacheStrapper(p3ConnectMgr *cm);
|
||||
virtual ~CacheStrapper() { return; }
|
||||
|
||||
|
|
@ -284,12 +388,30 @@ virtual void statusChange(const std::list<pqipeer> &plist);
|
|||
/************* from pqiMonitor *******************/
|
||||
|
||||
/* Feedback from CacheSources */
|
||||
|
||||
/*!
|
||||
* send data to peers online and selfe
|
||||
* @param data
|
||||
*
|
||||
*/
|
||||
void refreshCache(const CacheData &data);
|
||||
|
||||
/*!
|
||||
* forces config savelist
|
||||
* @param data
|
||||
* @see saveList()
|
||||
*/
|
||||
void refreshCacheStore(const CacheData &data);
|
||||
|
||||
/* list of Caches to send out */
|
||||
/*!
|
||||
* list of Caches to send out
|
||||
*/
|
||||
bool getCacheUpdates(std::list<std::pair<RsPeerId, CacheData> > &updates);
|
||||
|
||||
/*!
|
||||
* add to strapper's cachepair set so a related service's store and source can be maintained
|
||||
* @param pair the source and store handle for a service
|
||||
*/
|
||||
void addCachePair(CachePair pair);
|
||||
|
||||
/*** I/O (2) ***/
|
||||
|
|
@ -297,11 +419,20 @@ void recvCacheResponse(CacheData &data, time_t ts);
|
|||
void handleCacheQuery(RsPeerId id, std::map<CacheId, CacheData> &data);
|
||||
|
||||
|
||||
/* search through CacheSources. */
|
||||
/*!
|
||||
* search through CacheSources.
|
||||
* @return false if cachedate mapping to hash not found
|
||||
*/
|
||||
bool findCache(std::string hash, CacheData &data) const;
|
||||
|
||||
/* display */
|
||||
void listCaches(std::ostream &out);
|
||||
|
||||
/*!
|
||||
* does not do anything
|
||||
* @param out
|
||||
* @deprecated
|
||||
*/
|
||||
void listPeerStatus(std::ostream &out);
|
||||
|
||||
/**
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue