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

Go to the SVN repository for this file.

1 #ifndef CONN___NETSCHEDULE_API__HPP
2 #define CONN___NETSCHEDULE_API__HPP
3 
4 /* $Id: netschedule_api.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: Anatoliy Kuznetsov, Maxim Didenko, Victor Joukov, Dmitry Kazimirov
30  *
31  * File Description:
32  * NetSchedule client API.
33  *
34  */
35 
36 
37 /// @file netschedule_api.hpp
38 /// NetSchedule client specs.
39 ///
40 
41 #include "netschedule_key.hpp"
42 #include "netschedule_api_expt.hpp"
43 #include "netservice_api.hpp"
44 #include "compound_id.hpp"
45 
47 
49 
50 
51 /// Defines whether the job queue is paused, and if so, defines
52 /// the pause mode set by the administrator.
57 };
58 
59 /** @addtogroup NetScheduleClient
60  *
61  * @{
62  */
63 
67 class CNetScheduleAdmin;
68 
69 struct CNetScheduleJob;
70 
71 struct SNetScheduleAPIImpl;
72 
73 /// Client API for NCBI NetSchedule server.
74 ///
75 /// This API is logically divided into two sections:
76 /// Job Submitter API and Worker Node API.
77 ///
78 /// As objects of this class are only smart pointers to the real
79 /// implementation, it is advisable that these objects are
80 /// allocated on the stack rather than the heap.
81 ///
82 /// @sa CNetServiceException, CNetScheduleException
83 ///
84 
86 {
87  NCBI_NET_COMPONENT(NetScheduleAPI);
88 
89  /// Defines how this object must be initialized.
90  enum EAppRegistry {
91  eAppRegistry
92  };
93 
94  /// Creates an instance of CNetScheduleAPI and initializes
95  /// it with parameters read from the application registry.
96  /// @param use_app_reg
97  /// Selects this constructor.
98  /// The parameter is not used otherwise.
99  /// @param conf_section
100  /// Name of the registry section to look for the configuration
101  /// parameters in. If empty string is passed, then the section
102  /// name "netschedule_api" will be used.
103  explicit CNetScheduleAPI(EAppRegistry use_app_reg,
104  const string& conf_section = kEmptyStr);
105 
106  /// Constructs a CNetScheduleAPI object and initializes it with
107  /// parameters read from the specified registry object.
108  /// @param reg
109  /// Registry to get the configuration parameters from.
110  /// @param conf_section
111  /// Name of the registry section to look for the configuration
112  /// parameters in. If empty string is passed, then the section
113  /// name "netschedule_api" will be used.
114  explicit CNetScheduleAPI(const IRegistry& reg,
115  const string& conf_section = kEmptyStr);
116 
117  /// Constructs a CNetScheduleAPI object and initializes it with
118  /// parameters read from the specified configuration object.
119  /// @param conf
120  /// A CConfig object to get the configuration parameters from.
121  /// @param conf_section
122  /// Name of the configuration section where to look for the
123  /// parameters. If empty string is passed, then the section
124  /// name "netschedule_api" will be used.
125  explicit CNetScheduleAPI(CConfig* conf,
126  const string& conf_section = kEmptyStr);
127 
128  /// Construct the client without linking it to any particular
129  /// server. Actual server (host and port) will be extracted from the
130  /// job key
131  ///
132  /// @param service_name
133  /// Name of the service to connect to (format:
134  /// LB service name or host:port)
135  /// @param client_name
136  /// Name of the client program (project)
137  /// @param queue_name
138  /// Name of the job queue
139  ///
140  CNetScheduleAPI(const string& service_name,
141  const string& client_name,
142  const string& queue_name);
143 
144  /// Set program version (like: MyProgram v. 1.2.3)
145  ///
146  /// Program version is passed to NetSchedule queue so queue
147  /// controls versions and does not allow obsolete clients
148  /// to connect and submit or execute jobs
149  ///
150  void SetProgramVersion(const string& pv);
151 
152  /// Get program version string
153  const string& GetProgramVersion() const;
154 
155  /// Return Queue name
156  const string& GetQueueName() const;
157  // -----------------------------------------------------------------
158 
159  /// Job status codes
161  {
162  eJobNotFound = -1, ///< No such job
163  ePending = 0, ///< Waiting for execution
164  eRunning = 1, ///< Running on a worker node
165  // One deprecated job state is omitted here.
166  // It had the numeric value of 2.
167  eCanceled = 3, ///< Explicitly canceled
168  eFailed = 4, ///< Failed to run (execution timeout)
169  eDone = 5, ///< Job is ready (computed successfully)
170  eReading = 6, ///< Job has its output been reading
171  eConfirmed = 7, ///< Final state - read confirmed
172  eReadFailed = 8, ///< Final state - read failed
173  eDeleted = 9, ///< The job has been wiped out of the database.
174 
175  eLastStatus ///< Fake status (do not use)
176  };
177 
178  /// Printable status type
179  static
180  string StatusToString(EJobStatus status);
181 
182  /// Parse status string into enumerator value
183  ///
184  /// Acceptable string values:
185  /// Pending, Running, Canceled, Failed, Done, Reading,
186  /// Confirmed, ReadFailed,
187  /// Abbreviated
188  /// Pend, Run, Return, Cancel, Fail
189  ///
190  /// @return eJobNotFound if string cannot be parsed
191  static
192  EJobStatus StringToStatus(const CTempString& status_str);
193 
194  /// Job masks
195  ///
196  enum EJobMask {
197  eEmptyMask = 0,
198  /// Exclusive job - the node executes only this job, even if
199  /// there are processor resources
200  eExclusiveJob = (1 << 0),
201  // Not implemented yet ---v
202  /// This jobs comes to the node before every regular jobs
203  eOutOfOrder = (1 << 1),
204  /// This job will be scheduled to every active node
205  eForEachNode = (1 << 2),
206  /// This job should be interpreted by client library, not client itself
207  /// Can contain control information, e.g. instruction for node to die
208  eSystemJob = (1 << 3),
209  // ---^
210  eUserMask = (1 << 16) ///< User's masks start from here
211  };
212  typedef unsigned TJobMask;
213 
214  /// Create an instance of CNetScheduleSubmitter.
215  CNetScheduleSubmitter GetSubmitter();
216 
217  /// Create an instance of CNetScheduleExecutor.
218  CNetScheduleExecutor GetExecutor();
219 
220  /// Create an instance of CNetScheduleJobReader.
221  ///
222  /// @param group
223  /// Restrict job retrieval to the specified job group name.
224  /// @param affinity
225  /// Restrict job retrieval to the specified affinity.
226  ///
227  CNetScheduleJobReader GetJobReader(const string& group = kEmptyStr,
228  const string& affinity = kEmptyStr);
229 
230  CNetScheduleAdmin GetAdmin();
231 
232  CNetService GetService();
233 
234  struct SServerParams {
237  };
238 
239  const SServerParams& GetServerParams();
240 
242  void GetQueueParams(const string& queue_name, TQueueParams& queue_params);
243  void GetQueueParams(TQueueParams& queue_params);
244 
245  /// Get job details
246  EJobStatus GetJobDetails(
247  CNetScheduleJob& job,
248  time_t* job_exptime = NULL,
249  ENetScheduleQueuePauseMode* pause_mode = NULL);
250 
251  /// Update the progress_message field of the job structure.
252  /// Prior to calling this method, the caller must set the
253  /// id field of the job structure.
254  void GetProgressMsg(CNetScheduleJob& job);
255 
257  {GetService().GetServerPool().SetCommunicationTimeout(to);}
258 
259  void SetClientNode(const string& client_node);
260 
261  void SetClientSession(const string& client_session);
262 
263  enum EClientType {
269  };
270 
271  void SetClientType(EClientType client_type);
272 
293  };
294  static ENetScheduleWarningType ExtractWarningType(string& warn_msg);
295  static const char* WarningTypeToString(
296  ENetScheduleWarningType warning_type);
297 };
298 
299 
300 /// New job description
301 ///
302 
304 {
305  explicit CNetScheduleNewJob(const string& _input = kEmptyStr,
306  const string& _affinity = kEmptyStr,
308  input(_input),
309  affinity(_affinity),
310  mask(_mask)
311  {
312  }
313 
314  void Reset()
315  {
316  input.erase();
317  affinity.erase();
319  job_id.erase();
320  group.erase();
321  }
322 
323  /// Input data. Arbitrary string that contains input data
324  /// for the job. It is suggested to use NetCache to keep
325  /// the actual data and pass NetCache key as job input.
326  string input;
327 
328  string affinity;
329 
330  string group;
331 
333 
334  /// Output job key.
335  string job_id;
336 };
337 
338 
339 /// Job description
340 ///
341 
343 {
344  explicit CNetScheduleJob(const string& _input = kEmptyStr,
345  const string& _affinity = kEmptyStr,
347  CNetScheduleNewJob(_input, _affinity, _mask),
348  ret_code(0)
349  {
350  }
351 
352  void Reset()
353  {
355  client_ip.erase();
356  session_id.erase();
357  page_hit_id.erase();
358  ret_code = 0;
359  output.erase();
360  error_msg.erase();
361  progress_msg.erase();
362  auth_token.erase();
363  server = NULL;
364  }
365 
366  string client_ip;
367  string session_id;
368  string page_hit_id;
369 
370  /// Job return code.
371  int ret_code;
372  /// Job result data.
373  string output;
374  string error_msg;
375  string progress_msg;
376 
377  string auth_token;
378 
379  /// The server the job belongs to.
381 };
382 
384 
385 /// Smart pointer to the job submission part of the NetSchedule API.
386 /// Objects of this class are returned by
387 /// CNetScheduleAPI::GetSubmitter(). It is possible to have several
388 /// submitters per one CNetScheduleAPI object.
389 ///
390 /// @sa CNetScheduleAPI, CNetScheduleExecutor
392 {
393  NCBI_NET_COMPONENT(NetScheduleSubmitter);
394 
395  /// Submit job.
396  /// @note on success job.job_id will be set.
397  string SubmitJob(CNetScheduleNewJob& job);
398 
399  /// Submit job batch.
400  /// Method automatically splits the submission into reasonable sized
401  /// transactions, so there is no limit on the input batch size.
402  ///
403  /// Every job in the job list receives job id
404  ///
405  void SubmitJobBatch(vector<CNetScheduleJob>& jobs,
406  const string& job_group = kEmptyStr);
407 
408  /// Incremental retrieval of jobs that are done or failed.
409  ///
410  /// @param job_id
411  /// Placeholder for storing the identifier of the job that's
412  /// done or failed.
413  /// @param auth_token
414  /// Placeholder for storing a reading reservation token, which
415  /// guarantees that no other caller will be given the same
416  /// job for reading.
417  /// @param job_status
418  /// Placeholder for storing the status of the job,
419  /// either eDone or eFailed.
420  /// @param timeout
421  /// Number of seconds to wait before the status of jobs is
422  /// automatically reverted to the original one ('Done' or
423  /// 'Failed'). If zero, the default timeout of the NetSchedule
424  /// queue will be used instead.
425  /// @param job_group
426  /// Only consider jobs belonging to the specified group.
427  /// @return
428  /// True if a job that's done or failed has been returned
429  /// via the job_id references. False if no servers reported
430  /// jobs marked as either done or failed.
431  bool Read(string* job_id,
432  string* auth_token,
433  CNetScheduleAPI::EJobStatus* job_status,
434  unsigned timeout = 0,
435  const string& job_group = kEmptyStr);
436 
437  /// Mark the specified job as successfully retrieved.
438  /// The job will change its status to 'Confirmed' after
439  /// this operation.
440  ///
441  /// @param job_id
442  /// Job key returned by Read().
443  /// @param auth_token
444  /// Reservation token returned by Read().
445  void ReadConfirm(const string& job_id, const string& auth_token);
446 
447  /// Refuse from processing the results of the specified job.
448  /// The job will change its status back to the original one
449  /// ('Done' or 'Failed') after this operation.
450  ///
451  /// @param job_id
452  /// Job key returned by Read().
453  /// @param auth_token
454  /// Reservation token returned by Read().
455  void ReadRollback(const string& job_id, const string& auth_token);
456 
457  /// Refuse from processing the results of the specified job
458  /// and increase its counter of failed job result retrievals.
459  /// If this counter exceeds the failed_read_retries parameter
460  /// specified in the configuration file, the job will permanently
461  /// change its status to 'ReadFailed'.
462  ///
463  /// @param job_id
464  /// Job key returned by Read().
465  /// @param auth_token
466  /// Reservation token returned by Read().
467  /// @param error_message
468  /// This message can be used to describe the cause why the
469  /// job results could not be read.
470  void ReadFail(const string& job_id, const string& auth_token,
471  const string& error_message = kEmptyStr);
472 
473  /// Submit job to server and wait for the result.
474  /// This function should be used if we expect that job execution
475  /// infrastructure is capable of finishing job in the specified
476  /// time frame. This method can save a lot of round trips with the
477  /// NetSchedule server (comparing to series of GetStatus calls).
478  ///
479  /// @param job
480  /// NetSchedule job description structure
481  /// @param wait_time
482  /// Time in seconds function waits for the job to finish.
483  /// If job does not finish in the output parameter will hold the empty
484  /// string.
485  ///
486  /// @return job status
487  ///
488  /// @note the result fields of the job description structure will be set
489  /// if the job is finished during specified time.
490  ///
491  CNetScheduleAPI:: EJobStatus SubmitJobAndWait(CNetScheduleJob& job,
492  unsigned wait_time);
493 
494  /// Wait for job to finish its execution (done/failed/canceled).
495  /// This function should be used if we expect that job execution
496  /// infrastructure is capable of finishing job in the specified
497  /// time frame. This method can save a lot of round trips with the
498  /// NetSchedule server (comparing to series of GetStatus calls).
499  ///
500  /// @param job_id
501  /// NetSchedule job key.
502  /// @param wait_time
503  /// Time in seconds function waits for the job to finish.
504  /// @return job status
505  /// Returns current job status,
506  /// could be any status (e.g. if job does not finish in wait_time).
507  ///
508  CNetScheduleAPI::EJobStatus WaitForJob(const string& job_id,
509  unsigned wait_time);
510 
511  /// Cancel job
512  ///
513  /// @param job_key
514  /// Job key
515  void CancelJob(const string& job_key);
516 
517  /// Cancel job group
518  ///
519  /// @param job_group
520  /// Group ID.
521  /// @param job_statuses
522  /// Optional comma-separated list of job statuses
523  void CancelJobGroup(const string& job_group,
524  const string& job_statuses = kEmptyStr);
525 
526  /// Get progress message
527  ///
528  /// @param job
529  /// NetSchedule job description structure. The message is taken
530  /// from the progress_msg field.
531  ///
532  /// @sa PutProgressMsg
533  ///
534  void GetProgressMsg(CNetScheduleJob& job);
535 
536  /// Get the current status of the specified job. Unlike the similar
537  /// method from CNetScheduleExecutor, this method prolongs the lifetime
538  /// of the job on the server.
539  ///
540  /// @param job_key
541  /// NetSchedule job key.
542  /// @param job_exptime
543  /// Number of seconds since EPOCH when the job will expire
544  /// on the server.
545  /// @param pause_mode
546  /// Queue pause mode set by the administrator.
547  ///
548  /// @return The current job status. eJobNotFound is returned if the job
549  /// cannot be found (job record has expired).
550  ///
551  CNetScheduleAPI::EJobStatus GetJobStatus(
552  const string& job_key,
553  time_t* job_exptime = NULL,
554  ENetScheduleQueuePauseMode* pause_mode = NULL);
555 
556  /// Get full information about the specified job.
557  ///
558  /// @param job
559  /// A reference to the job description structure. The job key
560  /// is taken from the job_key field. Upon return, the structure
561  /// will be filled with the current information about the job,
562  /// including its input and output.
563  /// @param job_exptime
564  /// Number of seconds since EPOCH when the job will expire
565  /// on the server.
566  ///
567  /// @return The current job status.
568  ///
569  CNetScheduleAPI::EJobStatus GetJobDetails(
570  CNetScheduleJob& job,
571  time_t* job_exptime = NULL,
572  ENetScheduleQueuePauseMode* pause_mode = NULL);
573 };
574 
575 ////////////////////////////////////////////////////////////////////////////////
576 ////
578 
579 /// Smart pointer to a part of the NetSchedule API that does job
580 /// retrieval and processing on the worker node side.
581 /// Objects of this class are returned by
582 /// CNetScheduleAPI::GetExecutor().
583 ///
584 /// @sa CNetScheduleAPI, CNetScheduleSubmitter
586 {
587  NCBI_NET_COMPONENT(NetScheduleExecutor);
588 
589  /// Affinity matching modes.
590  ///
591  /// @note Explicitly specified affinities are always searched first.
592  ///
599  };
600 
601  /// Set preferred method of requesting jobs with affinities.
602  ///
603  void SetAffinityPreference(EJobAffinityPreference aff_pref);
604 
605  /// Retrieve jobs from the specified group only.
606  ///
607  void SetJobGroup(const string& job_group);
608 
609  /// Get a pending job.
610  ///
611  /// When function returns TRUE, job information is written to the 'job'
612  /// structure, and job status is changed to eRunning. This client
613  /// (the worker node) becomes responsible for execution or returning of
614  /// the job. If there are no jobs in the queue, the function returns
615  /// FALSE immediately and this call has to be repeated.
616  ///
617  /// @param job
618  /// NetSchedule job description structure.
619  ///
620  /// @param affinity_list
621  /// Comma-separated list of affinity tokens.
622  ///
623  /// @param deadline
624  /// Deadline for waiting for a matching job to appear in the queue.
625  ///
626  /// @return
627  /// TRUE if job has been returned from the queue and its input
628  /// fields are set.
629  /// FALSE means queue is empty or for some other reason NetSchedule
630  /// decided not to give a job to this node (e.g. no jobs with
631  /// matching affinities).
632  ///
633  bool GetJob(CNetScheduleJob& job,
634  const string& affinity_list = kEmptyStr,
635  CDeadline* dealine = NULL);
636 
637  /// The same as GetJob(CNetScheduleJob&, EJobAffinityPreference,
638  /// const string&, CDeadline*),
639  /// except it accepts integer wait time in seconds instead of CDeadline.
640  bool GetJob(CNetScheduleJob& job,
641  unsigned wait_time,
642  const string& affinity_list = kEmptyStr);
643 
644  /// Put job result (job should be received by GetJob() or WaitJob())
645  ///
646  /// @param job
647  /// NetSchedule job description structure. its ret_code
648  /// and output fields should be set
649  ///
650  void PutResult(const CNetScheduleJob& job);
651 
652  /// Put job interim (progress) message.
653  ///
654  /// @note The progress message must be first saved to a NetCache blob,
655  /// then (using this method) the key of that blob must be set
656  /// as the job progress message. The blob can be overwritten then
657  /// in NetCache directly without notifying the NetSchedule server.
658  ///
659  /// @param job
660  /// NetSchedule job description structure. its progerss_msg
661  /// field should be set to a NetCache key that contains the
662  /// actual progress message.
663  ///
664  /// @sa GetProgressMsg
665  ///
666  void PutProgressMsg(const CNetScheduleJob& job);
667 
668  /// Get progress message
669  ///
670  /// @param job
671  /// NetSchedule job description structure. The message is taken from
672  /// progress_msg filed
673  ///
674  /// @sa PutProgressMsg
675  ///
676  void GetProgressMsg(CNetScheduleJob& job);
677 
678 
679  /// Submit job failure diagnostics. This method indicates that
680  /// job failed because of some fatal, unrecoverable error.
681  ///
682  /// @param job
683  /// NetSchedule job description structure. its error_msg
684  /// and optionally ret_code and output fields should be set
685  ///
686  /// @param no_retries
687  /// Instruct NetSchedule to fail the job permanently.
688  /// The job will not be rerun regardless of whether retries
689  /// are enabled for the queue or not.
690  ///
691  void PutFailure(const CNetScheduleJob& job, bool no_retries = false);
692 
693  /// Reschedule a job with new affinity and/or group information.
694  ///
695  /// This method requires that the following fields of the specified
696  /// CNetScheduleJob structure are filled: 'job_id', 'auth_token',
697  /// 'affinity' and/or 'group'.
698  void Reschedule(const CNetScheduleJob& job);
699 
700  /// Get the current status of the specified job. Unlike the similar
701  /// method from CNetScheduleSubmitter, this method does not prolong
702  /// the lifetime of the job on the server.
703  ///
704  /// @param job_key
705  /// NetSchedule job key.
706  /// @param job_exptime
707  /// Number of seconds since EPOCH when the job will expire
708  /// on the server.
709  /// @param pause_mode
710  /// Queue pause mode set by the administrator.
711  ///
712  /// @return The current job status. eJobNotFound is returned if the job
713  /// cannot be found (job record has expired).
714  ///
715  CNetScheduleAPI::EJobStatus GetJobStatus(
716  const CNetScheduleJob& job,
717  time_t* job_exptime = NULL,
718  ENetScheduleQueuePauseMode* pause_mode = NULL);
719 
720  /// Switch the job back to the "Pending" status so that it can be
721  /// run again on a different worker node.
722  ///
723  /// The node may decide to return the job if it cannot be processed
724  /// at the moment (not enough resources, the node is shutting down,
725  /// etc.)
726  ///
727  void ReturnJob(const CNetScheduleJob& job);
728 
729  /// Increment job execution timeout
730  ///
731  /// When node picks up the job for execution it may periodically
732  /// communicate to the server that job is still alive and
733  /// prolong job execution timeout, so job server does not try to
734  /// reschedule.
735  ///
736  /// @param runtime_inc
737  /// Estimated time in seconds(from the current moment) to
738  /// finish the job.
739  void JobDelayExpiration(const CNetScheduleJob& job, unsigned runtime_inc);
740 
741  /// Retrieve queue parameters from the server.
742  const CNetScheduleAPI::SServerParams& GetServerParams();
743 
744  /// Unregister client-listener. After this call, the
745  /// server will not try to send any notification messages or
746  /// maintain job affinity for the client.
747  void ClearNode();
748 
749  void AddPreferredAffinities(const vector<string>& affs_to_add)
750  { ChangePreferredAffinities(&affs_to_add, NULL); }
751 
752  void DeletePreferredAffinities(const vector<string>& affs_to_del)
753  { ChangePreferredAffinities(NULL, &affs_to_del); }
754 
755  void ChangePreferredAffinities(const vector<string>* affs_to_add,
756  const vector<string>* affs_to_delete);
757 
758  /// Return Queue name
759  const string& GetQueueName();
760  const string& GetClientName();
761  const string& GetServiceName();
762 };
763 
764 // Definition for backward compatibility.
766 
767 
769 
770 /// Smart pointer to a part of the NetSchedule API that allows to
771 /// retrieve completed jobs.
772 /// Objects of this class are returned by CNetScheduleAPI::GetJobReader().
773 ///
774 /// @sa CNetScheduleAPI
775 ///
777 {
778  NCBI_NET_COMPONENT(NetScheduleJobReader);
779 
780  /// Possible outcomes of ReadNextJob() calls.
782  eRNJ_JobReady, ///< A job is returned.
783  eRNJ_NotReady, ///< No matching jobs are ready for reading.
784  eRNJ_Timeout = eRNJ_NotReady,
785  eRNJ_NoMoreJobs, ///< No matching jobs.
786  eRNJ_Interrupt, ///< ReadNextJob() has been interrupted.
787  };
788 
789  /// Wait and return the next completed job.
790  ///
791  /// @param job Structure to fill with information about the job.
792  /// The following fields of the structure will be filled:
793  /// - job_id
794  /// - auth_token
795  /// - affinity
796  /// - client_ip
797  /// - session_id
798  /// - page_hit_id
799  ///
800  /// @param job_status Pointer to a variable where to store the final
801  /// status of the job.
802  ///
803  /// @param timeout Timeout to wait for job completion.
804  /// If NULL, the method returns immediately.
805  ///
806  EReadNextJobResult ReadNextJob(CNetScheduleJob* job,
807  CNetScheduleAPI::EJobStatus* job_status,
808  const CTimeout* timeout = NULL);
809 
810  /// Abort waiting for a completed job in the above method.
811  /// Can be called from a signal handler or a parallel thread.
812  ///
813  void InterruptReading();
814 };
815 
816 /* @} */
817 
818 
820 
822 
823 #endif /* CONN___NETSCHEDULE_API__HPP */
CDeadline.
Definition: ncbitime.hpp:1830
Client API for NCBI NetSchedule server.
Smart pointer to a part of the NetSchedule API that does job retrieval and processing on the worker n...
Smart pointer to a part of the NetSchedule API that allows to retrieve completed jobs.
Smart pointer to the job submission part of the NetSchedule API.
CTempString implements a light-weight string on top of a storage buffer whose lifetime management is ...
Definition: tempstr.hpp:65
CTimeout – Timeout interval.
Definition: ncbitime.hpp:1693
IRegistry –.
Definition: ncbireg.hpp:73
Declarations of CCompoundIDPool, CCompoundID, and CCompoundIDField.
@ eExclusiveJob
Definition: grid_cli.hpp:199
#define NULL
Definition: ncbistd.hpp:225
void Read(CObjectIStream &in, TObjectPtr object, const CTypeRef &type)
Definition: serial.cpp:60
void DeletePreferredAffinities(const vector< string > &affs_to_del)
EJobStatus
Job status codes.
CNetScheduleJob(const string &_input=kEmptyStr, const string &_affinity=kEmptyStr, CNetScheduleAPI::TJobMask _mask=CNetScheduleAPI::eEmptyMask)
string output
Job result data.
@ eNSQ_NoPause
@ eNSQ_WithPullback
@ eNSQ_WithoutPullback
CNetScheduleAPI::TJobMask mask
void AddPreferredAffinities(const vector< string > &affs_to_add)
int ret_code
Job return code.
map< string, string > TQueueParams
string input
Input data.
CNetServer server
The server the job belongs to.
void SetCommunicationTimeout(const STimeout &to)
EJobAffinityPreference
Affinity matching modes.
EAppRegistry
Defines how this object must be initialized.
CNetScheduleNewJob(const string &_input=kEmptyStr, const string &_affinity=kEmptyStr, CNetScheduleAPI::TJobMask _mask=CNetScheduleAPI::eEmptyMask)
EReadNextJobResult
Possible outcomes of ReadNextJob() calls.
string job_id
Output job key.
CNetScheduleExecutor CNetScheduleExecuter
@ eRNJ_NotReady
No matching jobs are ready for reading.
@ eRNJ_JobReady
A job is returned.
@ eRNJ_NoMoreJobs
No matching jobs.
@ eRNJ_Interrupt
ReadNextJob() has been interrupted.
#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_XCONNECT_EXPORT
#define NCBI_NET_COMPONENT(component)
ENetScheduleQueuePauseMode
Defines whether the job queue is paused, and if so, defines the pause mode set by the administrator.
Plugin manager (using class factory paradigm).
@ eCanceled
Request canceled.
Job description.
New job description.
Timeout structure.
Definition: ncbi_types.h:76
Modified on Thu Jul 18 16:02:48 2024 by modify_doxy.py rev. 669887