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

Go to the SVN repository for this file.

1 #ifndef CONNECT_SERVICES_GRID__GRID_CLIENT__HPP
2 #define CONNECT_SERVICES_GRID__GRID_CLIENT__HPP
3 
4 /* $Id: grid_client.hpp 78755 2017-07-17 15:43:10Z 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: Maxim Didenko, Dmitry Kazimirov
30  *
31  */
32 
33 /// @file grid_client.hpp
34 /// NetSchedule Framework specs.
35 ///
36 
37 
41 
42 #include <connect/connect_export.h>
43 
44 #include <corelib/ncbistre.hpp>
45 
46 
48 
49 /** @addtogroup NetScheduleClient
50  *
51  * @{
52  */
53 
54 
55 class CGridClient;
56 
57 /// Grid Job Batch Submitter
58 ///
60 {
61 public:
62  /// Set a job's input This string will be sent to
63  /// then the job is submitted.
64  ///
65  /// This method can be used to send a short data to the worker node.
66  /// To send a large data use GetOStream method. Don't call this
67  /// method after GetOStream method is called.
68  ///
69  void SetJobInput(const string& input);
70 
71  /// Get a stream where a client can write an input
72  /// data for the remote job
73  ///
74  CNcbiOstream& GetOStream();
75 
76  /// Set a job mask
77  ///
78  void SetJobMask(CNetScheduleAPI::TJobMask mask);
79 
80  /// Set a job affinity
81  ///
82  void SetJobAffinity(const string& affinity);
83 
84  void PrepareNextJob();
85 
86  /// Submit a batch to the queue
87  ///
88  void Submit(const string& job_group = kEmptyStr);
89 
90  ///
91  void Reset();
92 
93  const vector<CNetScheduleJob>& GetBatch() const { return m_Jobs; }
94 private:
95  /// Only CGridClient can create an instance of this class
96  friend class CGridClient;
97 
98  void CheckIfBatchAlreadySubmitted();
99  void CheckIfBatchSubmittedAndPrepareNextJob();
100 
102 
104  vector<CNetScheduleJob> m_Jobs;
105  size_t m_JobIndex;
108 
109  /// The copy constructor and the assignment operator
110  /// are prohibited
113 };
114 
115 /// Grid Client (the submitter).
116 ///
118 {
119 public:
120  enum ECleanUp {
121  eAutomaticCleanup = 0,
122  eManualCleanup
123  };
124 
126  eProgressMsgOn = 0,
127  eProgressMsgOff
128  };
129 
130  /// Constructor
131  ///
132  /// @param ns_client
133  /// NetSchedule client - an instance of CNetScheduleSubmitter.
134  /// @param storage
135  /// NetSchedule storage
136  /// @param cleanup
137  /// if true the grid client will automatically remove
138  /// a job's input data from a storage when the job is
139  /// done or canceled
140  ///
142  IBlobStorage& storage,
143  ECleanUp cleanup,
144  EProgressMsg progress_msg);
145 
146  /// Constructor
147  ///
148  /// @param ns_client
149  /// NetSchedule client - an instance of CNetScheduleSubmitter.
150  /// @param nc_client
151  /// NetCache client - an instance of CNetCacheAPI.
152  /// @param cleanup
153  /// if true the grid client will automatically remove
154  /// a job's input data from a storage when the job is
155  /// done or canceled
156  ///
158  CNetCacheAPI::TInstance nc_client,
159  ECleanUp cleanup,
160  EProgressMsg progress_msg);
161 
162  /// Get a job's output string.
163  ///
164  /// This string can be used in two ways.
165  /// 1. It can be an output data from a remote job (if that data is short)
166  /// If it is so don't use GetIStream method.
167  /// 2. It holds a key to a data stored in an external data storage.
168  /// (NetCache) In this case use GetIStream method to get a stream with
169  /// a job's result.
170  ///
171  const string& GetJobOutput();
172 
173  /// Get a job's input sting
174  const string& GetJobInput();
175 
176  /// Get a job's return code
177  //
178  int GetReturnCode();
179 
180  /// If something bad has happened this method will return an
181  /// explanation
182  ///
183  const string& GetErrorMessage();
184 
185  /// Get a job status
186  ///
187  CNetScheduleAPI::EJobStatus GetStatus();
188 
189  /// Get a stream with a job's result. Stream is based on network
190  /// data storage (NetCache). Size of the input data can be determined
191  /// using GetInputBlobSize
192  ///
194 
195  /// Get the size of an input stream
196  ///
197  size_t GetBlobSize() const { return m_BlobSize; }
198 
199  /// Get a job interim message
200  ///
201  string GetProgressMessage();
202 
203  /// Set a job's input This string will be sent to
204  /// then the job is submitted.
205  ///
206  /// This method can be used to send a short data to the worker node.
207  /// To send a large data use GetOStream method. Don't call this
208  /// method after GetOStream method is called.
209  ///
210  void SetJobInput(const string& input);
211 
212  /// Get a stream where a client can write an input
213  /// data for the remote job
214  ///
215  CNcbiOstream& GetOStream();
216 
217  void CloseStream();
218 
220 
221  void SetJobGroup(const string& group) {m_Job.group = group;}
222 
223  void SetJobAffinity(const string& affinity) {m_Job.affinity = affinity;}
224 
225  /// Submit a job to the queue
226  ///
227  /// @return a job key
228  string Submit(const string& affinity = kEmptyStr);
229 
230  /// Submit a job to the queue
231  ///
232  CNetScheduleAPI::EJobStatus SubmitAndWait(unsigned wait_time);
233 
234  /// Wait for job to finish its execution (done/failed/canceled).
235  /// @sa CNetScheduleAPI
236  ///
237  CNetScheduleAPI::EJobStatus WaitForJob(const string& job_key,
238  unsigned wait_time);
239 
240  CNetScheduleJob& GetJob() {return m_Job;}
241 
242  /// Get a job submitter
243  ///
244  CGridJobBatchSubmitter& GetJobBatchSubmitter();
245 
246  void SetJobKey(const string& job_key);
247 
248  /// Cancel Job
249  ///
250  /// @param job_key
251  /// Job key
252  ///
253  void CancelJob(const string& job_key);
254 
256  {
257  return m_NetScheduleSubmitter;
258  }
259  CNetCacheAPI& GetNetCacheAPI() { return m_NetCacheAPI; }
260 
261  size_t GetMaxServerInputSize();
262 
263 private:
265 
266  void Init(ECleanUp cleanup, EProgressMsg progress_msg);
267  void RemoveDataBlob(const string&);
268  void UseNextSubHitID();
269 
272 
276 
277  auto_ptr<CGridJobBatchSubmitter> m_JobBatchSubmitter;
278 
279  void x_ProlongBlobLifetime(const string& blob_key, unsigned ttl);
280  bool x_ProlongJobFieldLifetime(const string& job_field, unsigned ttl);
281  void x_RenewAllJobBlobs(unsigned ttl);
282  CNetScheduleAPI::EJobStatus x_CheckAllJobBlobs(
283  CNetScheduleAPI::EJobStatus status, time_t job_exptime);
284  void x_GetJobDetails();
285 
286  size_t m_BlobSize;
290 
291  /// The copy constructor and the assignment operator
292  /// are prohibited
293  CGridClient(const CGridClient&);
295 };
296 
297 /// Grid Client exception
298 ///
300 {
301 public:
302  enum EErrCode {
304  };
305 
306  virtual const char* GetErrCodeString(void) const
307  {
308  switch (GetErrCode())
309  {
310  case eBatchAlreadySubmitted: return "eBatchAlreadySubmitted";
311  default: return CException::GetErrCodeString();
312  }
313  }
314 
316 };
317 
318 /////////////////////////////////////////////////////////////////////////////
319 
321 
322 #endif // CONNECT_SERVICES_GRID__GRID_CLIENT__HPP
NCBI_EXCEPTION_DEFAULT(CGridClientException, CException)
CNetCacheAPI m_NetCacheAPI
CNetScheduleSubmitter m_NetScheduleSubmitter
CGridClient & m_GridClient
vector< CNetScheduleJob > m_Jobs
SGridRead m_GridRead
bool m_UseProgress
virtual const char * GetErrCodeString(void) const
Get error code interpreted as text.
NCBI C++ stream class wrappers for triggering between "new" and "old" C++ stream libraries.
Job description.
friend class CGridClient
Only CGridClient can create an instance of this class.
Definition: grid_client.hpp:96
bool m_JobDetailsRead
#define kEmptyStr
Definition: ncbistr.hpp:120
Blob Storage interface.
NetSchedule client specs.
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:101
auto_ptr< CGridJobBatchSubmitter > m_JobBatchSubmitter
#define NCBI_XCONNECT_EXPORT
auto_ptr< CObjectIStream > GetIStream(string path, ESerialDataFormat serial_format)
Smart pointer to the job submission part of the NetSchedule API.
CNetScheduleJob & GetJob()
size_t GetBlobSize() const
Get the size of an input stream.
friend class CGridJobBatchSubmitter
IO_PREFIX::ostream CNcbiOstream
Portable alias for ostream.
Definition: ncbistre.hpp:142
size_t m_BlobSize
void SetJobMask(CNetScheduleAPI::TJobMask mask)
ncbi::TMaskedQueryRegions mask
CGridClient & operator=(const CGridClient &)
void SetJobGroup(const string &group)
SGridWrite m_GridWrite
bool m_AutoCleanUp
static void Init(void)
Definition: cursor6.c:79
CNetCacheAPI & GetNetCacheAPI()
CGridJobBatchSubmitter & operator=(CGridJobBatchSubmitter &)
TErrCode GetErrCode(void) const
Get error code.
Definition: ncbiexpt.cpp:436
NetCache client specs.
EJobStatus
Job status codes.
const vector< CNetScheduleJob > & GetBatch() const
Definition: grid_client.hpp:93
Client API for NetCache server.
void SetJobAffinity(const string &affinity)
CNetScheduleSubmitter GetNetScheduleSubmitter()
IO_PREFIX::istream CNcbiIstream
Portable alias for istream.
Definition: ncbistre.hpp:139
Grid Job Batch Submitter.
Definition: grid_client.hpp:59
Grid Client exception.
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:98
CNetScheduleJob m_Job
Grid Client (the submitter).
virtual const char * GetErrCodeString(void) const
Get error code interpreted as text.
Definition: ncbiexpt.cpp:427
static int input()
Modified on Tue Sep 19 16:18:49 2017 by modify_doxy.py rev. 546573