Debian Codegraph @

LspCpp/include/LibLsp/lsp/IProgressMonitor.h

raw
1 #pragma once
2
3 #include <string>
4 namespace lsp
5 {
6 /**
7 * The <code>IProgressMonitor</code> interface is implemented
8 * by objects that monitor the progress of an activity; the methods
9 * in this interface are invoked by code that performs the activity.
10 * <p>
11 * All activity is broken down into a linear sequence of tasks against
12 * which progress is reported. When a task begins, a <code>beginTask(const wstring&, int)
13 * </code> notification is reported, followed by any number and mixture of
14 * progress reports (<code>worked()</code>) and subtask notifications
15 * (<code>subTask(const wstring&)</code>). When the task is eventually completed, a
16 * <code>done()</code> notification is reported. After the <code>done()</code>
17 * notification, the progress monitor cannot be reused; i.e., <code>
18 * beginTask(const wstring&, int)</code> cannot be called again after the call to
19 * <code>done()</code>.
20 * </p>
21 * <p>
22 * A request to cancel an operation can be signaled using the
23 * <code>setCanceled</code> method. Operations taking a progress
24 * monitor are expected to poll the monitor (using <code>isCanceled</code>)
25 * periodically and abort at their earliest convenience. Operation can however
26 * choose to ignore cancelation requests.
27 * </p>
28 * <p>
29 * Since notification is synchronous with the activity itself, the listener should
30 * provide a fast and robust implementation. If the handling of notifications would
31 * involve blocking operations, or operations which might throw uncaught exceptions,
32 * the notifications should be queued, and the actual processing deferred (or perhaps
33 * delegated to a separate thread).
34 * </p>
35 * <p>
36 * Clients may implement this interface.
37 * </p>
38 */
39 class IProgressMonitor
40 {
41 public:
42 virtual ~IProgressMonitor()
43 {
44 }
45
46 /** Constant indicating an unknown amount of work.
47 */
48
49 static int const UNKNOWN = -1;
50
51 /**
52 * Notifies that the main task is beginning. This must only be called once
53 * on a given progress monitor instance.
54 *
55 * @param name the name (or description) of the main task
56 * @param totalWork the total number of work units into which
57 * the main task is been subdivided. If the value is <code>UNKNOWN</code>
58 * the implemenation is free to indicate progress in a way which
59 * doesn't require the total number of work units in advance.
60 */
61 virtual void beginTask(void*, int totalWork) {
62
63 };
64 /**
65 * Notifies that the work is done; that is, either the main task is completed
66 * or the user canceled it. This method may be called more than once
67 * (implementations should be prepared to handle this case).
68 */
69
70 virtual void endTask(void*, int totalWork)
71 {
72 }
73
74 virtual void done(void*) = 0;
75
76 /**
77 * Internal method to handle scaling correctly. This method
78 * must not be called by a client. Clients should
79 * always use the method <code>worked(int)</code>.
80 */
81 virtual void internalWorked(double work)
82 {
83 }
84 /**
85 * Returns whether cancelation of current operation has been requested.
86 * Long-running operations should poll to see if cancelation
87 * has been requested.
88 *
89 * @return <code>true</code> if cancellation has been requested,
90 * and <code>false</code> otherwise
91 * @see #setCanceled
92 */
93 virtual bool isCanceled() = 0;
94 /**
95 * Sets the cancel state to the given value.
96 *
97 * @param value <code>true</code> indicates that cancelation has
98 * been requested (but not necessarily acknowledged);
99 * <code>false</code> clears this flag
100 *
101 * @see #isCanceled
102 */
103 virtual void setCanceled(bool value) = 0;
104 /**
105 * Sets the task name to the given value. This method is used to
106 * restore the task label after a nested operation was executed.
107 * Normally there is no need for clients to call this method.
108 *
109 * @param name the name (or description) of the main task
110 * @see #beginTask(java.lang.const wstring&, int)
111 */
112 virtual void setTaskName(void*) {
113
114 };
115 /**
116 * Notifies that a subtask of the main task is beginning.
117 * Subtasks are optional; the main task might not have subtasks.
118 *
119 * @param name the name (or description) of the subtask
120 */
121 virtual void subTask(void*)
122 {
123 }
124 /**
125 * Notifies that a given number of work unit of the main task
126 * has been completed. Note that this amount represents an
127 * installment, as opposed to a cumulative amount of work done
128 * to date.
129 *
130 * @param work the number of work units just completed
131 */
132 virtual void worked(int work) {
133
134 };
135
136 virtual void catch_exception(void*) = 0;
137 };
138 } // namespace lsp