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 32 enum 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 50 class 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 73 class 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 Priority()90 dng_priority Priority () const 91 { 92 return fPriority; 93 } 94 95 /// Setter for priority level. 96 SetPriority(dng_priority priority)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 SniffNoPriorityWait()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 ThreadSafe()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 161 class 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 fSniffer(sniffer)181 : fSniffer (sniffer) 182 183 { 184 if (fSniffer) 185 fSniffer->StartTask (name, fract); 186 } 187 ~dng_sniffer_task()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 Sniff()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 UpdateProgress(real64 fract)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 UpdateProgress(uint32 done,uint32 total)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 Finish()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