1 #ifndef CONNECT_SERVICES___NETICACHE_CLIENT__HPP 2 #define CONNECT_SERVICES___NETICACHE_CLIENT__HPP 3 4 /* $Id: neticache_client.hpp 617099 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 45 #include <connect/ncbi_core_cxx.hpp> 46 47 #include <util/resource_pool.hpp> 48 #include <util/cache/icache.hpp> 49 50 #include <corelib/request_control.hpp> 51 #include <corelib/plugin_manager_store.hpp> 52 #include <corelib/ncbistd.hpp> 53 #include <corelib/ncbimtx.hpp> 54 55 56 BEGIN_NCBI_SCOPE 57 58 59 /** @addtogroup NetCacheClient 60 * 61 * @{ 62 */ 63 64 struct SNetICacheClientImpl; 65 66 /// Client to NetCache server (implements ICache interface) 67 /// 68 /// @note This implementation is thread safe and synchronized 69 /// 70 class NCBI_NET_CACHE_EXPORT CNetICacheClient : public ICache 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. 93 CNetICacheClient(CConfig* config = NULL, 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. 196 IReader* GetReadStream( 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 GetSubkeyList(const string & key)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 355 NCBI_NET_CACHE_EXPORT 356 void NCBI_EntryPoint_xcache_netcache( 357 CPluginManager<ICache>::TDriverInfoList& info_list, 358 CPluginManager<ICache>::EEntryPointRequest method); 359 360 NCBI_NET_CACHE_EXPORT 361 void Cache_RegisterDriver_NetCache(void); 362 363 } // extern C 364 365 /* @} */ 366 367 368 END_NCBI_SCOPE 369 370 #include "impl/neticache_client_int.hpp" 371 372 #endif /* CONNECT_SERVICES___NETICACHE_CLIENT__HPP */ 373