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

Go to the SVN repository for this file.

1 #ifndef GUI_OBJUTILS___APP_JOB__HPP
2 #define GUI_OBJUTILS___APP_JOB__HPP
3 
4 /* $Id: app_job.hpp 34478 2016-01-13 16:19:10Z katargir $
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: Andrey Yazhuk
30  *
31  * File Description:
32  *
33  */
34 
35 /** @addtogroup GUI_UTILS
36 *
37 * @{
38 */
39 
40 #include <gui/gui_export.h>
41 
42 #include <corelib/ncbiobj.hpp>
43 
44 
46 
47 ///////////////////////////////////////////////////////////////////////////////
48 /// IAppJobProgress
50 {
51 public:
52  virtual ~IAppJobProgress() {};
53 
54  /// return a number indicating the progress(0.0 - just started, 1.0 - done)
55  virtual float GetNormDone() const = 0;
56 
57  /// returns a text string describing current state
58  virtual string GetText() const = 0;
59 };
60 
61 
62 ///////////////////////////////////////////////////////////////////////////////
63 /// IAppJobError
65 {
66 public:
67  virtual ~IAppJobError() {};
68 
69  /// returns a string describing the error
70  virtual string GetText() const = 0;
71 
72  virtual bool IsUserLevel() const = 0;
73 };
74 
75 
76 ///////////////////////////////////////////////////////////////////////////////
77 /// IAppJob
78 ///
79 /// Base interface class for background job execution
80 ///
82 {
83 public:
84  /// Job states (describe FSM)
85  ///
86  enum EJobState {
92  eSuspended
93  };
94 
95  virtual ~IAppJob() {};
96 
97  /// Function will be called on the main thread
98  /// before execution of Run
99  /// Should not do any lengthy work
100  /// returns true to continue job execution on worker thread
101  /// false to quit execution with status - failed
102  virtual bool BeforeRun() { return true; }
103 
104  /// Function that does all the useful work, called by the Engine.
105  /// Run() shall be implemented so that it will allow for exiting once
106  /// RequestCancel() is called.
107  virtual EJobState Run() = 0;
108 
109  /// return progress object, the function shall be synchronized internally.
110  /// the returned object should not be modified by the job (job shall create
111  /// a new instance of Progress object on every GetProgress() invocation).
113 
114  /// Returns the Job Result. Derive your own object from CObject and return
115  /// it from your Job class. Result shall be returned only if Job finished
116  /// succesfully.
117  virtual CRef<CObject> GetResult() = 0;
118 
119  /// Returns IAppJobError object describing internal error that caused the Job
120  /// to fail. Result shall be returned only if the Job did fail.
122 
123  /// Returns a human readable description of the Job (optional)
124  virtual string GetDescr() const = 0;
125 
126  /// RequestCancel() is called to notify the Job that it shall
127  /// exit Run() function ASAP. The function shall be synchronized internally.
128  virtual void RequestCancel() = 0;
129 
130  // Return true if job was canceled
131  virtual bool IsCanceled() const = 0;
132 };
133 
134 
136 
137 /* @} */
138 
139 #endif // GUI_OBJUTILS___APP_JOB__HPP
IAppJobError.
Definition: app_job.hpp:65
IAppJobProgress.
Definition: app_job.hpp:50
IAppJob.
Definition: app_job.hpp:82
virtual CConstIRef< IAppJobProgress > GetProgress()=0
return progress object, the function shall be synchronized internally.
virtual ~IAppJobError()
Definition: app_job.hpp:67
virtual bool IsCanceled() const =0
virtual string GetText() const =0
returns a text string describing current state
virtual CConstIRef< IAppJobError > GetError()=0
Returns IAppJobError object describing internal error that caused the Job to fail.
virtual void RequestCancel()=0
RequestCancel() is called to notify the Job that it shall exit Run() function ASAP.
virtual string GetText() const =0
returns a string describing the error
virtual CRef< CObject > GetResult()=0
Returns the Job Result.
virtual bool IsUserLevel() const =0
EJobState
Job states (describe FSM)
Definition: app_job.hpp:86
virtual string GetDescr() const =0
Returns a human readable description of the Job (optional)
virtual ~IAppJobProgress()
Definition: app_job.hpp:52
virtual EJobState Run()=0
Function that does all the useful work, called by the Engine.
virtual ~IAppJob()
Definition: app_job.hpp:95
virtual float GetNormDone() const =0
return a number indicating the progress(0.0 - just started, 1.0 - done)
virtual bool BeforeRun()
Function will be called on the main thread before execution of Run Should not do any lengthy work ret...
Definition: app_job.hpp:102
@ eCanceled
Definition: app_job.hpp:91
@ eCompleted
Definition: app_job.hpp:89
@ eRunning
Definition: app_job.hpp:88
@ eInvalid
Definition: app_job.hpp:87
@ eFailed
Definition: app_job.hpp:90
#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 NCBI_GUIOBJUTILS_EXPORT
Definition: gui_export.h:512
Defines to provide correct exporting from DLLs in Windows.
Portable reference counted smart and weak pointers using CWeakRef, CRef, CObject and CObjectEx.
Modified on Wed Jun 12 11:14:33 2024 by modify_doxy.py rev. 669887