1/*****************************************************************************/
2// Copyright 2006-2008 Adobe Systems Incorporated
3// All Rights Reserved.
4//
5// NOTICE: Adobe permits you to use, modify, and distribute this file in
6// accordance with the terms of the Adobe license agreement accompanying it.
7/*****************************************************************************/
8
9/* $Id: //mondo/dng_sdk_1_4/dng_sdk/source/dng_abort_sniffer.h#2 $ */
10/* $DateTime: 2012/07/11 10:36:56 $ */
11/* $Change: 838485 $ */
12/* $Author: tknoll $ */
13
14/** \file
15 * Classes supporting user cancellation and progress tracking.
16 */
17
18/*****************************************************************************/
19
20#ifndef __dng_abort_sniffer__
21#define __dng_abort_sniffer__
22
23/*****************************************************************************/
24
25#include "dng_flags.h"
26#include "dng_types.h"
27
28/*****************************************************************************/
29
30/// \brief Thread priority level.
31
32enum dng_priority
33 {
34
35 dng_priority_low,
36 dng_priority_medium,
37 dng_priority_high,
38
39 dng_priority_count,
40
41 dng_priority_minimum = dng_priority_low,
42 dng_priority_maximum = dng_priority_high
43
44 };
45
46/*****************************************************************************/
47
48/// \brief Convenience class for setting thread priority level to minimum.
49
50class dng_set_minimum_priority
51 {
52
53 private:
54
55 dng_priority fPriority;
56
57 public:
58
59 dng_set_minimum_priority (dng_priority priority);
60
61 ~dng_set_minimum_priority ();
62
63 };
64
65/*****************************************************************************/
66
67/** \brief Class for signaling user cancellation and receiving progress updates.
68 *
69 * DNG SDK clients should derive a host application specific implementation
70 * from this class.
71 */
72
73class dng_abort_sniffer
74 {
75
76 friend class dng_sniffer_task;
77
78 private:
79
80 dng_priority fPriority;
81
82 public:
83
84 dng_abort_sniffer ();
85
86 virtual ~dng_abort_sniffer ();
87
88 /// Getter for priority level.
89
90 dng_priority Priority () const
91 {
92 return fPriority;
93 }
94
95 /// Setter for priority level.
96
97 void SetPriority (dng_priority priority)
98 {
99 fPriority = priority;
100 }
101
102 /// Check for pending user cancellation or other abort. ThrowUserCanceled
103 /// will be called if one is pending. This static method is provided as a
104 /// convenience for quickly testing for an abort and throwing an exception
105 /// if one is pending.
106 /// \param sniffer The dng_sniffer to test for a pending abort. Can be NULL,
107 /// in which case there an abort is never signalled.
108
109 static void SniffForAbort (dng_abort_sniffer *sniffer);
110
111 // A way to call Sniff while bypassing the priority wait.
112
113 void SniffNoPriorityWait ()
114 {
115 Sniff ();
116 }
117
118 // Specifies whether or not the sniffer may be called by multiple threads
119 // in parallel. Default result is false. Subclass must override to return
120 // true.
121
122 virtual bool ThreadSafe () const
123 {
124 return false;
125 }
126
127 protected:
128
129 /// Should be implemented by derived classes to check for an user
130 /// cancellation.
131
132 virtual void Sniff () = 0;
133
134 /// Signals the start of a named task withn processing in the DNG SDK.
135 /// Tasks may be nested.
136 /// \param name of the task
137 /// \param fract Percentage of total processing this task is expected to
138 /// take. From 0.0 to 1.0 .
139
140 virtual void StartTask (const char *name,
141 real64 fract);
142
143 /// Signals the end of the innermost task that has been started.
144
145 virtual void EndTask ();
146
147 /// Signals progress made on current task.
148 /// \param fract percentage of processing completed on current task.
149 /// From 0.0 to 1.0 .
150
151 virtual void UpdateProgress (real64 fract);
152
153 };
154
155/******************************************************************************/
156
157/// \brief Class to establish scope of a named subtask in DNG processing.
158///
159/// Instances of this class are intended to be stack allocated.
160
161class dng_sniffer_task
162 {
163
164 private:
165
166 dng_abort_sniffer *fSniffer;
167
168 public:
169
170 /// Inform a sniffer of a subtask in DNG processing.
171 /// \param sniffer The sniffer associated with the host on which this
172 /// processing is occurring.
173 /// \param name The name of this subtask as a NUL terminated string.
174 /// \param fract Percentage of total processing this task is expected
175 /// to take, from 0.0 to 1.0 .
176
177 dng_sniffer_task (dng_abort_sniffer *sniffer,
178 const char *name = NULL,
179 real64 fract = 0.0)
180
181 : fSniffer (sniffer)
182
183 {
184 if (fSniffer)
185 fSniffer->StartTask (name, fract);
186 }
187
188 ~dng_sniffer_task ()
189 {
190 if (fSniffer)
191 fSniffer->EndTask ();
192 }
193
194 /// Check for pending user cancellation or other abort. ThrowUserCanceled
195 /// will be called if one is pending.
196
197 void Sniff ()
198 {
199 dng_abort_sniffer::SniffForAbort (fSniffer);
200 }
201
202 /// Update progress on this subtask.
203 /// \param fract Percentage of processing completed on current task,
204 /// from 0.0 to 1.0 .
205
206 void UpdateProgress (real64 fract)
207 {
208 if (fSniffer)
209 fSniffer->UpdateProgress (fract);
210 }
211
212 /// Update progress on this subtask.
213 /// \param done Amount of task completed in arbitrary integer units.
214 /// \param total Total size of task in same arbitrary integer units as done.
215
216 void UpdateProgress (uint32 done,
217 uint32 total)
218 {
219 UpdateProgress ((real64) done /
220 (real64) total);
221 }
222
223 /// Signal task completed for progress purposes.
224
225 void Finish ()
226 {
227 UpdateProgress (1.0);
228 }
229
230 private:
231
232 // Hidden copy constructor and assignment operator.
233
234 dng_sniffer_task (const dng_sniffer_task &task);
235
236 dng_sniffer_task & operator= (const dng_sniffer_task &task);
237
238 };
239
240/*****************************************************************************/
241
242#endif
243
244/*****************************************************************************/
245