NCBI C++ ToolKit
neticache_client.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CONNECT_SERVICES___NETICACHE_CLIENT__HPP
2 #define CONNECT_SERVICES___NETICACHE_CLIENT__HPP
3 
4 /* $Id: neticache_client.hpp 91216 2020-09-25 17:09:07Z sadyrovr $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Anatoliy Kuznetsov, Dmitry Kazimirov
30  *
31  * File Description:
32  * Network client for ICache (NetCache).
33  *
34  */
35 
36 /// @file neticache_client.hpp
37 /// NetCache ICache client specs.
38 ///
39 
40 #include "netcache_api.hpp"
41 #include "netcache_search.hpp"
42 
43 #include <list>
44 
46 
47 #include <util/resource_pool.hpp>
48 #include <util/cache/icache.hpp>
49 
52 #include <corelib/ncbistd.hpp>
53 #include <corelib/ncbimtx.hpp>
54 
55 
57 
58 
59 /** @addtogroup NetCacheClient
60  *
61  * @{
62  */
63 
65 
66 /// Client to NetCache server (implements ICache interface)
67 ///
68 /// @note This implementation is thread safe and synchronized
69 ///
71 {
72  NCBI_NET_COMPONENT_IMPL(NetICacheClient);
73 
74  /// Defines how this object must be initialized.
75  enum EAppRegistry {
76  eAppRegistry
77  };
78 
79  /// Create an instance of CNetICacheClient and initialize
80  /// it with parameters read from the application registry.
81  /// @param use_app_reg
82  /// Selects this constructor.
83  /// The parameter is not used otherwise.
84  /// @param conf_section
85  /// Name of the registry section to look for the configuration
86  /// parameters in. If an empty string is passed, the default
87  /// section name "netcache" is used.
88  explicit CNetICacheClient(EAppRegistry use_app_reg,
89  const string& conf_section = kEmptyStr);
90 
91  // Construct an instance using connection parameters
92  // specified in the configuration file.
94  const string& driver_name = kEmptyStr);
95 
96  CNetICacheClient(const IRegistry& reg,
97  const string& conf_section = kEmptyStr);
98 
99  CNetICacheClient(const string& host,
100  unsigned short port,
101  const string& cache_name,
102  const string& client_name);
103 
104  CNetICacheClient(const string& service_name,
105  const string& cache_name,
106  const string& client_name);
107 
108  /// Send session registration command
109  void RegisterSession(unsigned pid);
110  /// Send session unregistration command
111  void UnRegisterSession(unsigned pid);
112 
113  // ICache interface implementation
114 
115  virtual TFlags GetFlags();
116  virtual void SetFlags(TFlags flags);
117  virtual void SetTimeStampPolicy(TTimeStampFlags policy,
118  unsigned int timeout,
119  unsigned int max_timeout = 0);
120  virtual TTimeStampFlags GetTimeStampPolicy() const;
121  virtual int GetTimeout() const;
122  virtual bool IsOpen() const;
123  virtual void SetVersionRetention(EKeepVersions policy);
124  virtual EKeepVersions GetVersionRetention() const;
125  virtual void Store(const string& key,
126  int version,
127  const string& subkey,
128  const void* data,
129  size_t size,
130  unsigned int time_to_live = 0,
131  const string& owner = kEmptyStr);
132 
133  virtual size_t GetSize(const string& key,
134  int version,
135  const string& subkey);
136 
137  /// Returns the size of the BLOB identified by the "key", "version", and
138  /// "subkey" parameters.
139  ///
140  /// @note
141  /// This updates the blob's expiration time.
142  size_t GetBlobSize(const string& key, int version, const string& subkey,
143  const CNamedParameterList* optional = NULL);
144 
145  virtual void GetBlobOwner(const string& key,
146  int version,
147  const string& subkey,
148  string* owner);
149 
150  typedef grid::netcache::search::CBlobInfo CBlobInfo;
151  typedef grid::netcache::search::CExpression CExpression;
152  typedef grid::netcache::search::CFields CFields;
153 
154  /// Returns information for all blobs matching provided search expression.
155  /// @see NetCacheSearch for complete list of classes and operators.
156  ///
157  /// @param expression
158  /// Search expression,
159  /// e.g. 'created < hours(1) && size >= 1024'
160  /// @param fields
161  /// Additional output fields requested in blob info,
162  /// e.g. 'expires | version_expires'
163  /// @return
164  /// Blob info consisting of key, subkey, fields from provided search
165  /// expression and output fields for all blobs matched the expression
166  ///
167  vector<CBlobInfo> Search(CExpression expression, CFields fields = CFields());
168 
169  /// @warning
170  /// This method DOES NOT follow ICache::Read() interface
171  /// on returning values/throwing exceptions.
172  ///
173  /// @return
174  /// FALSE if BLOB has not been fully read
175  ///
176  /// @throw
177  /// If any error occurs (e.g. BLOB doesn't exist or expired).
178  virtual bool Read(const string& key,
179  int version,
180  const string& subkey,
181  void* buf,
182  size_t buf_size);
183 
184  bool ReadPart(const string& key,
185  int version,
186  const string& subkey,
187  size_t offset,
188  size_t part_size,
189  void* buf,
190  size_t buf_size);
191 
192  /// Read a lengthy blob via the IReader interface. The Read() method
193  /// of the returned implementation is not blocking. The caller
194  /// must provide a reading completion loop for the Read() call.
195  /// @see CNetCacheAPI::GetReader() for an example.
197  const string& key,
198  int version,
199  const string& subkey,
200  size_t* blob_size_ptr,
201  const CNamedParameterList* optional = NULL);
202 
203  /// Read a lengthy blob via the IReader interface. The Read() method
204  /// of the returned implementation is not blocking. The caller
205  /// must provide a reading completion loop for the Read() call.
206  /// @see CNetCacheAPI::GetReader() for an example.
207  virtual IReader* GetReadStream(
208  const string& key,
209  const string& subkey,
210  int* version,
211  EBlobVersionValidity* validity);
212 
213  virtual void SetBlobVersionAsCurrent(
214  const string& key,
215  const string& subkey,
216  int version);
217 
218  /// Read data from the specified blob. The IReader implementation
219  /// returned is NOT blocking: its Read() method may return a partial
220  /// result before the requested amount of data is retrieved.
221  /// The Read() call must be placed within a loop that completes
222  /// data retrieval.
223  /// @see CNetCacheAPI::GetReader() for an example.
224  ///
225  /// @param key
226  /// ICache key
227  /// @param version
228  /// ICache key version
229  /// @param subkey
230  /// ICache subkey
231  /// @param offset
232  /// Offset in the blob at which to start reading it.
233  /// @param part_size
234  /// Maximum number of bytes to read with this call.
235  /// @param blob_size_ptr
236  /// If not NULL, this parameter must point to a variable
237  /// that will receive the total blob size in bytes.
238  /// @param caching_mode
239  /// Defines whether to enable file caching.
240  /// @param server_to_use
241  /// Explicitly define the server to use for reading.
242  /// @return
243  /// IReader* (to be deleted by the caller).
244  IReader* GetReadStreamPart(
245  const string& key,
246  int version,
247  const string& subkey,
248  size_t offset,
249  size_t part_size,
250  size_t* blob_size_ptr,
251  const CNamedParameterList* optional = NULL);
252 
253  /// Read a lengthy blob via the IReader interface. The Read() method
254  /// of the returned implementation is not blocking. The caller
255  /// must provide a reading completion loop for the Read() call.
256  /// @see CNetCacheAPI::GetReader() for an example.
257  virtual IReader* GetReadStream(const string& key,
258  int version,
259  const string& subkey);
260 
261  virtual void GetBlobAccess(const string& key,
262  int version,
263  const string& subkey,
264  SBlobAccessDescr* blob_descr);
265 
266  /// Create or update the specified blob. This method is blocking --
267  /// it waits for a confirmation from NetCache after all
268  /// data is transferred. Since blob EOF marker is sent in the
269  /// destructor, the blob will not be created until the stream
270  /// is deleted.
271  ///
272  /// @param key
273  /// ICache key
274  /// @param version
275  /// ICache key version
276  /// @param subkey
277  /// ICache subkey
278  /// @param time_to_live
279  /// BLOB time to live value in seconds.
280  /// 0 - server side default is assumed.
281  /// @param caching_mode
282  /// Defines whether to enable file caching.
283  /// @return
284  /// IEmbeddedStreamWriter* (caller must delete it).
285  IEmbeddedStreamWriter* GetNetCacheWriter(
286  const string& key,
287  int version,
288  const string& subkey,
289  const CNamedParameterList* optional = NULL);
290 
291  virtual IWriter* GetWriteStream(
292  const string& key,
293  int version,
294  const string& subkey,
295  unsigned int time_to_live = 0,
296  const string& owner = kEmptyStr);
297 
298  virtual void Remove(const string& key,
299  int version,
300  const string& subkey);
301  void RemoveBlob(const string& key, int version, const string& subkey,
302  const CNamedParameterList* optional = NULL);
303 
304  virtual time_t GetAccessTime(const string& key,
305  int version,
306  const string& subkey);
307 
308  virtual bool HasBlobs(const string& key,
309  const string& subkey);
310  bool HasBlob(const string& key, const string& subkey,
311  const CNamedParameterList* optional = NULL);
312 
313  virtual void Purge(time_t access_timeout);
314 
315  virtual void Purge(const string& key,
316  const string& subkey,
317  time_t access_timeout);
318 
319  virtual bool SameCacheParams(const TCacheParams* params) const;
320  virtual string GetCacheName(void) const;
321 
322  /// Set communication timeout
323  void SetCommunicationTimeout(const STimeout& to);
324  STimeout GetCommunicationTimeout() const;
325 
326  /// Return a CNetServerMultilineCmdOutput object for reading
327  /// meta information about the specified blob.
328  ///
329  /// @note
330  /// This does not update the blob's expiration time.
331  CNetServerMultilineCmdOutput GetBlobInfo(const string& key,
332  int version, const string& subkey,
333  const CNamedParameterList* optional = NULL);
334 
335  /// Print meta information about the specified blob.
336  void PrintBlobInfo(const string& key, int version, const string& subkey);
337 
338  CNetService GetService();
339 
340  /// @deprecated Use Search() instead
341  NCBI_DEPRECATED list<string> GetSubkeyList(const string& key)
342  {
343  using namespace ncbi::grid::netcache::search;
344  list<string> r;
345  for (auto& i : Search(fields::key == key)) r.push_back(i[fields::subkey]);
346  return r;
347  }
348 };
349 
350 extern NCBI_NET_CACHE_EXPORT const char* const kNetICacheDriverName;
351 
352 extern "C"
353 {
354 
359 
362 
363 } // extern C
364 
365 /* @} */
366 
367 
369 
371 
372 #endif /* CONNECT_SERVICES___NETICACHE_CLIENT__HPP */
Client to NetCache server (implements ICache interface)
definition of a Culling tree
Definition: ncbi_tree.hpp:100
BLOB cache read/write/maintenance interface.
Definition: icache.hpp:64
virtual bool IsOpen() const =0
virtual EKeepVersions GetVersionRetention() const =0
Get version retention.
virtual void SetVersionRetention(EKeepVersions policy)=0
Set version retention policy.
virtual size_t GetSize(const string &key, TBlobVersion version, const string &subkey)=0
Check if BLOB exists, return BLOB size.
virtual void GetBlobOwner(const string &key, TBlobVersion version, const string &subkey, string *owner)=0
Retrieve BLOB owner.
virtual void Remove(const string &key, TBlobVersion version, const string &subkey)=0
Remove specific cache entry.
virtual TFlags GetFlags()=0
Retrieve the effective combination of flags from the underlying storage.
virtual IWriter * GetWriteStream(const string &key, TBlobVersion version, const string &subkey, unsigned int time_to_live=0, const string &owner=kEmptyStr)=0
Return sequential stream interface to write BLOB data.
virtual TTimeStampFlags GetTimeStampPolicy() const =0
Get timestamp policy.
virtual bool HasBlobs(const string &key, const string &subkey)=0
Check if any BLOB exists (any version)
virtual string GetCacheName(void) const =0
virtual void Purge(time_t access_timeout)=0
Delete all BLOBs older than specified.
virtual void SetTimeStampPolicy(TTimeStampFlags policy, unsigned int timeout, unsigned int max_timeout=0)=0
Set timestamp update policy.
virtual void SetFlags(TFlags flags)=0
Pass flags to the underlying storage.
virtual time_t GetAccessTime(const string &key, TBlobVersion version, const string &subkey)=0
Return last access time for the specified cache entry.
virtual bool Read(const string &key, TBlobVersion version, const string &subkey, void *buf, size_t buf_size)=0
Fetch the BLOB.
virtual void GetBlobAccess(const string &key, TBlobVersion version, const string &subkey, SBlobAccessDescr *blob_descr)=0
Get BLOB access using BlobAccessDescr.
EBlobVersionValidity
BLOB version existence and validity – from the point of view of the underlying cache implementation.
Definition: icache.hpp:274
virtual void Store(const string &key, TBlobVersion version, const string &subkey, const void *data, size_t size, unsigned int time_to_live=0, const string &owner=kEmptyStr)=0
Add or replace BLOB.
virtual bool SameCacheParams(const TCacheParams *params) const =0
virtual int GetTimeout() const =0
Get expiration timeout.
virtual void SetBlobVersionAsCurrent(const string &key, const string &subkey, TBlobVersion version)=0
Set current valid version for a BLOB.
virtual IReader * GetReadStream(const string &key, TBlobVersion version, const string &subkey)=0
Return sequential stream interface to read BLOB data.
A very basic data-read interface.
IRegistry –.
Definition: ncbireg.hpp:73
A very basic data-write interface.
Include a standard set of the NCBI C++ Toolkit most basic headers.
static uch flags
#define NULL
Definition: ncbistd.hpp:225
list< string > GetSubkeyList(const string &key)
grid::netcache::search::CBlobInfo CBlobInfo
void Cache_RegisterDriver_NetCache(void)
grid::netcache::search::CExpression CExpression
const char *const kNetICacheDriverName
EAppRegistry
Defines how this object must be initialized.
void NCBI_EntryPoint_xcache_netcache(CPluginManager< ICache >::TDriverInfoList &info_list, CPluginManager< ICache >::EEntryPointRequest method)
grid::netcache::search::CFields CFields
list< SDriverInfo > TDriverInfoList
List of driver information.
EEntryPointRequest
Actions performed by the entry point.
#define NCBI_DEPRECATED
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
#define kEmptyStr
Definition: ncbistr.hpp:123
#define NCBI_NET_CACHE_EXPORT
Definition: ncbi_export.h:288
Interfaces for a local cache of versioned binary large objects (BLOBS).
char * buf
int i
static int version
Definition: mdb_load.c:29
const struct ncbi::grid::netcache::search::fields::SIZE size
const struct ncbi::grid::netcache::search::fields::KEY key
const struct ncbi::grid::netcache::search::fields::SUBKEY subkey
Multi-threading – mutexes; rw-locks; semaphore.
NetCache client specs.
#define NCBI_NET_COMPONENT_IMPL(component)
double r(size_t dimension_, const Int4 *score_, const double *prob_, double theta_)
int offset
Definition: replacements.h:160
BLOB access descriptor.
Definition: icache.hpp:332
Timeout structure.
Definition: ncbi_types.h:76
Modified on Sat Mar 02 10:57:27 2024 by modify_doxy.py rev. 669887